1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3******************
4Variables Glossary
5******************
6
7This chapter lists common variables used in the OpenEmbedded build
8system and gives an overview of their function and contents.
9
10:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>`
11:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FEATURE_PACKAGES>`
12:term:`G <GCCPIE>` :term:`H <HOMEPAGE>` :term:`I <ICECC_DISABLED>`
13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
15:term:`R <RANLIB>` :term:`S` :term:`T`
16:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>`
17:term:`W <WARN_QA>` :term:`X <XSERVER>`
18
19.. glossary::
20   :sorted:
21
22   :term:`ABIEXTENSION`
23      Extension to the Application Binary Interface (ABI) field of the GNU
24      canonical architecture name (e.g. "eabi").
25
26      ABI extensions are set in the machine include files. For example, the
27      ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
28      following extension::
29
30         ABIEXTENSION = "eabi"
31
32   :term:`ALLOW_EMPTY`
33      Specifies whether to produce an output package even if it is empty.
34      By default, BitBake does not produce empty packages. This default
35      behavior can cause issues when there is an
36      :term:`RDEPENDS` or some other hard runtime
37      requirement on the existence of the package.
38
39      Like all package-controlling variables, you must always use them in
40      conjunction with a package name override, as in::
41
42         ALLOW_EMPTY:${PN} = "1"
43         ALLOW_EMPTY:${PN}-dev = "1"
44         ALLOW_EMPTY:${PN}-staticdev = "1"
45
46   :term:`ALTERNATIVE`
47      Lists commands in a package that need an alternative binary naming
48      scheme. Sometimes the same command is provided in multiple packages.
49      When this occurs, the OpenEmbedded build system needs to use the
50      alternatives system to create a different binary naming scheme so the
51      commands can co-exist.
52
53      To use the variable, list out the package's commands that are also
54      provided by another package. For example, if the ``busybox`` package
55      has four such commands, you identify them as follows::
56
57         ALTERNATIVE:busybox = "sh sed test bracket"
58
59      For more information on the alternatives system, see the
60      ":ref:`ref-classes-update-alternatives`"
61      section.
62
63   :term:`ALTERNATIVE_LINK_NAME`
64      Used by the alternatives system to map duplicated commands to actual
65      locations. For example, if the ``bracket`` command provided by the
66      ``busybox`` package is duplicated through another package, you must
67      use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
68      location::
69
70         ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
71
72      In this example, the binary for the ``bracket`` command (i.e. ``[``)
73      from the ``busybox`` package resides in ``/usr/bin/``.
74
75      .. note::
76
77         If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``.
78
79      For more information on the alternatives system, see the
80      ":ref:`ref-classes-update-alternatives`"
81      section.
82
83   :term:`ALTERNATIVE_PRIORITY`
84      Used by the alternatives system to create default priorities for
85      duplicated commands. You can use the variable to create a single
86      default regardless of the command name or package, a default for
87      specific duplicated commands regardless of the package, or a default
88      for specific commands tied to particular packages. Here are the
89      available syntax forms::
90
91         ALTERNATIVE_PRIORITY = "priority"
92         ALTERNATIVE_PRIORITY[name] = "priority"
93         ALTERNATIVE_PRIORITY_pkg[name] = "priority"
94
95      For more information on the alternatives system, see the
96      ":ref:`ref-classes-update-alternatives`"
97      section.
98
99   :term:`ALTERNATIVE_TARGET`
100      Used by the alternatives system to create default link locations for
101      duplicated commands. You can use the variable to create a single
102      default location for all duplicated commands regardless of the
103      command name or package, a default for specific duplicated commands
104      regardless of the package, or a default for specific commands tied to
105      particular packages. Here are the available syntax forms::
106
107         ALTERNATIVE_TARGET = "target"
108         ALTERNATIVE_TARGET[name] = "target"
109         ALTERNATIVE_TARGET_pkg[name] = "target"
110
111      .. note::
112
113         If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value
114         from the :term:`ALTERNATIVE_LINK_NAME` variable.
115
116         If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the
117         same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``"
118         appended to it.
119
120         Finally, if the file referenced has not been renamed, the
121         alternatives system will rename it to avoid the need to rename
122         alternative files in the :ref:`ref-tasks-install`
123         task while retaining support for the command if necessary.
124
125      For more information on the alternatives system, see the
126      ":ref:`ref-classes-update-alternatives`" section.
127
128   :term:`ANY_OF_DISTRO_FEATURES`
129      When inheriting the :ref:`ref-classes-features_check`
130      class, this variable identifies a list of distribution features where
131      at least one must be enabled in the current configuration in order
132      for the OpenEmbedded build system to build the recipe. In other words,
133      if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES`
134      appear in :term:`DISTRO_FEATURES` within the current configuration, then
135      the recipe will be skipped, and if the build system attempts to build
136      the recipe then an error will be triggered.
137
138   :term:`APPEND`
139      An override list of append strings for each target specified with
140      :term:`LABELS`.
141
142      See the :ref:`ref-classes-grub-efi` class for more
143      information on how this variable is used.
144
145   :term:`AR`
146      The minimal command and arguments used to run ``ar``.
147
148   :term:`ARCHIVER_MODE`
149      When used with the :ref:`ref-classes-archiver` class,
150      determines the type of information used to create a released archive.
151      You can use this variable to create archives of patched source,
152      original source, configured source, and so forth by employing the
153      following variable flags (varflags)::
154
155         ARCHIVER_MODE[src] = "original"                   # Uses original (unpacked) source files.
156         ARCHIVER_MODE[src] = "patched"                    # Uses patched source files. This is the default.
157         ARCHIVER_MODE[src] = "configured"                 # Uses configured source files.
158         ARCHIVER_MODE[diff] = "1"                         # Uses patches between do_unpack and do_patch.
159         ARCHIVER_MODE[diff-exclude] ?= "file file ..."    # Lists files and directories to exclude from diff.
160         ARCHIVER_MODE[dumpdata] = "1"                     # Uses environment data.
161         ARCHIVER_MODE[recipe] = "1"                       # Uses recipe and include files.
162         ARCHIVER_MODE[srpm] = "1"                         # Uses RPM package files.
163
164      For information on how the variable works, see the
165      ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
166
167   :term:`AS`
168      Minimal command and arguments needed to run the assembler.
169
170   :term:`ASSUME_PROVIDED`
171      Lists recipe names (:term:`PN` values) BitBake does not
172      attempt to build. Instead, BitBake assumes these recipes have already
173      been built.
174
175      In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
176      tools that should not be built. An example is ``git-native``, which
177      when specified, allows for the Git binary from the host to be used
178      rather than building ``git-native``.
179
180   :term:`ASSUME_SHLIBS`
181      Provides additional ``shlibs`` provider mapping information, which
182      adds to or overwrites the information provided automatically by the
183      system. Separate multiple entries using spaces.
184
185      As an example, use the following form to add an ``shlib`` provider of
186      shlibname in packagename with the optional version::
187
188         shlibname:packagename[_version]
189
190      Here is an example that adds a shared library named ``libEGL.so.1``
191      as being provided by the ``libegl-implementation`` package::
192
193         ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
194
195   :term:`AUTO_LIBNAME_PKGS`
196      When the :ref:`ref-classes-debian` class is inherited,
197      which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which
198      packages should be checked for libraries and renamed according to
199      Debian library package naming.
200
201      The default value is "${PACKAGES}", which causes the
202      :ref:`ref-classes-debian` class to act on all packages that are
203      explicitly generated by the recipe.
204
205   :term:`AUTOREV`
206      When :term:`SRCREV` is set to the value of this variable, it specifies to
207      use the latest source revision in the repository. Here is an example::
208
209         SRCREV = "${AUTOREV}"
210
211      If you use the previous statement to retrieve the latest version of
212      software, you need to be sure :term:`PV` contains
213      ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel
214      recipe that inherits the :ref:`ref-classes-kernel` class and you
215      use the previous statement. In this example, ``${SRCPV}`` does not
216      automatically get into :term:`PV`. Consequently, you need to change
217      :term:`PV` in your recipe so that it does contain ``${SRCPV}``.
218
219      For more information see the
220      ":ref:`dev-manual/packages:automatically incrementing a package version number`"
221      section in the Yocto Project Development Tasks Manual.
222
223   :term:`AUTO_SYSLINUXMENU`
224      Enables creating an automatic menu for the syslinux bootloader. You
225      must set this variable in your recipe. The
226      :ref:`ref-classes-syslinux` class checks this variable.
227
228   :term:`AVAILTUNES`
229      The list of defined CPU and Application Binary Interface (ABI)
230      tunings (i.e. "tunes") available for use by the OpenEmbedded build
231      system.
232
233      The list simply presents the tunes that are available. Not all tunes
234      may be compatible with a particular machine configuration, or with
235      each other in a
236      :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>`
237      configuration.
238
239      To add a tune to the list, be sure to append it with spaces using the
240      "+=" BitBake operator. Do not simply replace the list by using the
241      "=" operator. See the
242      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake
243      User Manual for more information.
244
245   :term:`AZ_SAS`
246      Azure Storage Shared Access Signature, when using the
247      :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
248      This variable can be defined to be used by the fetcher to authenticate
249      and gain access to non-public artifacts::
250
251         AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
252
253      For more information see Microsoft's Azure Storage documentation at
254      https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
255
256   :term:`B`
257      The directory within the :term:`Build Directory` in which the
258      OpenEmbedded build system places generated objects during a recipe's
259      build process. By default, this directory is the same as the
260      :term:`S` directory, which is defined as::
261
262         S = "${WORKDIR}/${BP}"
263
264      You can separate the (:term:`S`) directory and the directory pointed to
265      by the :term:`B` variable. Most Autotools-based recipes support
266      separating these directories. The build system defaults to using
267      separate directories for ``gcc`` and some kernel recipes.
268
269   :term:`BAD_RECOMMENDATIONS`
270      Lists "recommended-only" packages to not install. Recommended-only
271      packages are packages installed only through the
272      :term:`RRECOMMENDS` variable. You can prevent any
273      of these "recommended" packages from being installed by listing them
274      with the :term:`BAD_RECOMMENDATIONS` variable::
275
276         BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
277
278      You can set this variable globally in your ``local.conf`` file or you
279      can attach it to a specific image recipe by using the recipe name
280      override::
281
282         BAD_RECOMMENDATIONS:pn-target_image = "package_name"
283
284      It is important to realize that if you choose to not install packages
285      using this variable and some other packages are dependent on them
286      (i.e. listed in a recipe's :term:`RDEPENDS`
287      variable), the OpenEmbedded build system ignores your request and
288      will install the packages to avoid dependency errors.
289
290      This variable is supported only when using the IPK and RPM
291      packaging backends. DEB is not supported.
292
293      See the :term:`NO_RECOMMENDATIONS` and the
294      :term:`PACKAGE_EXCLUDE` variables for related
295      information.
296
297   :term:`BASE_LIB`
298      The library directory name for the CPU or Application Binary
299      Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib
300      context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`"
301      section in the Yocto Project Development Tasks Manual for information
302      on Multilib.
303
304      The :term:`BASE_LIB` variable is defined in the machine include files in
305      the :term:`Source Directory`. If Multilib is not
306      being used, the value defaults to "lib".
307
308   :term:`BASE_WORKDIR`
309      Points to the base of the work directory for all recipes. The default
310      value is "${TMPDIR}/work".
311
312   :term:`BB_ALLOWED_NETWORKS`
313      Specifies a space-delimited list of hosts that the fetcher is allowed
314      to use to obtain the required source code. Here are
315      considerations surrounding this variable:
316
317      -  This host list is only used if :term:`BB_NO_NETWORK` is either not set
318         or set to "0".
319
320      -  There is limited support for wildcard matching against the beginning of
321         host names. For example, the following setting matches
322         ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``::
323
324            BB_ALLOWED_NETWORKS = "*.gnu.org"
325
326         .. note::
327
328            The use of the "``*``" character only works at the beginning of
329            a host name and it must be isolated from the remainder of the
330            host name. You cannot use the wildcard character in any other
331            location of the name or combined with the front part of the
332            name.
333
334            For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
335            is not.
336
337      -  Mirrors not in the host list are skipped and logged in debug.
338
339      -  Attempts to access networks not in the host list cause a failure.
340
341      Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
342      :term:`PREMIRRORS` is very useful. Adding the host
343      you want to use to :term:`PREMIRRORS` results in the source code being
344      fetched from an allowed location and avoids raising an error when a
345      host that is not allowed is in a :term:`SRC_URI`
346      statement. This is because the fetcher does not attempt to use the
347      host listed in :term:`SRC_URI` after a successful fetch from the
348      :term:`PREMIRRORS` occurs.
349
350   :term:`BB_BASEHASH_IGNORE_VARS`
351      See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual.
352
353   :term:`BB_CACHEDIR`
354      See :term:`bitbake:BB_CACHEDIR` in the BitBake manual.
355
356   :term:`BB_CHECK_SSL_CERTS`
357      See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual.
358
359   :term:`BB_CONSOLELOG`
360      See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual.
361
362   :term:`BB_CURRENTTASK`
363      See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual.
364
365   :term:`BB_DANGLINGAPPENDS_WARNONLY`
366      Defines how BitBake handles situations where an append file
367      (``.bbappend``) has no corresponding recipe file (``.bb``). This
368      condition often occurs when layers get out of sync (e.g. ``oe-core``
369      bumps a recipe version and the old recipe no longer exists and the
370      other layer has not been updated to the new version of the recipe
371      yet).
372
373      The default fatal behavior is safest because it is the sane reaction
374      given something is out of sync. It is important to realize when your
375      changes are no longer being applied.
376
377      You can change the default behavior by setting this variable to "1",
378      "yes", or "true" in your ``local.conf`` file, which is located in the
379      :term:`Build Directory`: Here is an example::
380
381         BB_DANGLINGAPPENDS_WARNONLY = "1"
382
383   :term:`BB_DEFAULT_TASK`
384      See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual.
385
386   :term:`BB_DEFAULT_UMASK`
387      See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual.
388
389   :term:`BB_DISKMON_DIRS`
390      Monitors disk space and available inodes during the build and allows
391      you to control the build based on these parameters.
392
393      Disk space monitoring is disabled by default. To enable monitoring,
394      add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
395      found in the :term:`Build Directory`. Use the
396      following form:
397
398      .. code-block:: none
399
400         BB_DISKMON_DIRS = "action,dir,threshold [...]"
401
402         where:
403
404            action is:
405               ABORT:     Immediately stop the build when
406                          a threshold is broken.
407               STOPTASKS: Stop the build after the currently
408                          executing tasks have finished when
409                          a threshold is broken.
410               WARN:      Issue a warning but continue the
411                          build when a threshold is broken.
412                          Subsequent warnings are issued as
413                          defined by the BB_DISKMON_WARNINTERVAL
414                          variable, which must be defined in
415                          the conf/local.conf file.
416
417            dir is:
418               Any directory you choose. You can specify one or
419               more directories to monitor by separating the
420               groupings with a space.  If two directories are
421               on the same device, only the first directory
422               is monitored.
423
424            threshold is:
425               Either the minimum available disk space,
426               the minimum number of free inodes, or
427               both.  You must specify at least one.  To
428               omit one or the other, simply omit the value.
429               Specify the threshold using G, M, K for Gbytes,
430               Mbytes, and Kbytes, respectively. If you do
431               not specify G, M, or K, Kbytes is assumed by
432               default.  Do not use GB, MB, or KB.
433
434      Here are some examples::
435
436         BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
437         BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
438         BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
439
440      The first example works only if you also provide the
441      :term:`BB_DISKMON_WARNINTERVAL`
442      variable in the ``conf/local.conf``. This example causes the build
443      system to immediately stop when either the disk space in
444      ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
445      below 100 Kbytes. Because two directories are provided with the
446      variable, the build system also issue a warning when the disk space
447      in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
448      of free inodes drops below 100 Kbytes. Subsequent warnings are issued
449      during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL`
450      variable.
451
452      The second example stops the build after all currently executing
453      tasks complete when the minimum disk space in the ``${TMPDIR}``
454      directory drops below 1 Gbyte. No disk monitoring occurs for the free
455      inodes in this case.
456
457      The final example immediately stops the build when the number of
458      free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
459      disk space monitoring for the directory itself occurs in this case.
460
461   :term:`BB_DISKMON_WARNINTERVAL`
462      Defines the disk space and free inode warning intervals. To set these
463      intervals, define the variable in your ``conf/local.conf`` file in
464      the :term:`Build Directory`.
465
466      If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
467      must also use the :term:`BB_DISKMON_DIRS`
468      variable and define its action as "WARN". During the build,
469      subsequent warnings are issued each time disk space or number of free
470      inodes further reduces by the respective interval.
471
472      If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
473      do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
474      monitoring interval defaults to the following::
475
476         BB_DISKMON_WARNINTERVAL = "50M,5K"
477
478      When specifying the variable in your configuration file, use the
479      following form:
480
481      .. code-block:: none
482
483         BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"
484
485         where:
486
487            disk_space_interval is:
488               An interval of memory expressed in either
489               G, M, or K for Gbytes, Mbytes, or Kbytes,
490               respectively. You cannot use GB, MB, or KB.
491
492            disk_inode_interval is:
493               An interval of free inodes expressed in either
494               G, M, or K for Gbytes, Mbytes, or Kbytes,
495               respectively. You cannot use GB, MB, or KB.
496
497      Here is an example::
498
499         BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
500         BB_DISKMON_WARNINTERVAL = "50M,5K"
501
502      These variables cause the
503      OpenEmbedded build system to issue subsequent warnings each time the
504      available disk space further reduces by 50 Mbytes or the number of
505      free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
506      directory. Subsequent warnings based on the interval occur each time
507      a respective interval is reached beyond the initial warning (i.e. 1
508      Gbytes and 100 Kbytes).
509
510   :term:`BB_ENV_PASSTHROUGH`
511      See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual.
512
513   :term:`BB_ENV_PASSTHROUGH_ADDITIONS`
514      See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual.
515
516   :term:`BB_FETCH_PREMIRRORONLY`
517      See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual.
518
519   :term:`BB_FILENAME`
520      See :term:`bitbake:BB_FILENAME` in the BitBake manual.
521
522   :term:`BB_GENERATE_MIRROR_TARBALLS`
523      Causes tarballs of the source control repositories (e.g. Git
524      repositories), including metadata, to be placed in the
525      :term:`DL_DIR` directory.
526
527      For performance reasons, creating and placing tarballs of these
528      repositories is not the default action by the OpenEmbedded build
529      system::
530
531         BB_GENERATE_MIRROR_TARBALLS = "1"
532
533      Set this variable in your
534      ``local.conf`` file in the :term:`Build Directory`.
535
536      Once you have the tarballs containing your source files, you can
537      clean up your :term:`DL_DIR` directory by deleting any Git or other
538      source control work directories.
539
540   :term:`BB_GENERATE_SHALLOW_TARBALLS`
541      See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
542
543   :term:`BB_GIT_SHALLOW`
544      See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual.
545
546   :term:`BB_GIT_SHALLOW_DEPTH`
547      See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual.
548
549   :term:`BB_HASHCHECK_FUNCTION`
550      See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual.
551
552   :term:`BB_HASHCONFIG_IGNORE_VARS`
553      See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual.
554
555   :term:`BB_HASHSERVE`
556      See :term:`bitbake:BB_HASHSERVE` in the BitBake manual.
557
558   :term:`BB_HASHSERVE_UPSTREAM`
559      See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual.
560
561   :term:`BB_INVALIDCONF`
562      See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual.
563
564   :term:`BB_LOADFACTOR_MAX`
565      The system load threshold above which BitBake will stop runnig extra
566      tasks.
567
568   :term:`BB_LOGCONFIG`
569      See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual.
570
571   :term:`BB_LOGFMT`
572      See :term:`bitbake:BB_LOGFMT` in the BitBake manual.
573
574   :term:`BB_MULTI_PROVIDER_ALLOWED`
575      See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual.
576
577   :term:`BB_NICE_LEVEL`
578      See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual.
579
580   :term:`BB_NO_NETWORK`
581      See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual.
582
583   :term:`BB_NUMBER_PARSE_THREADS`
584      See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual.
585
586   :term:`BB_NUMBER_THREADS`
587      The maximum number of tasks BitBake should run in parallel at any one
588      time. The OpenEmbedded build system automatically configures this
589      variable to be equal to the number of cores on the build system. For
590      example, a system with a dual core processor that also uses
591      hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default
592      to "4".
593
594      For single socket systems (i.e. one CPU), you should not have to
595      override this variable to gain optimal parallelism during builds.
596      However, if you have very large systems that employ multiple physical
597      CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable
598      is not set higher than "20".
599
600      For more information on speeding up builds, see the
601      ":ref:`dev-manual/speeding-up-build:speeding up a build`"
602      section in the Yocto Project Development Tasks Manual.
603
604      On the other hand, if your goal is to limit the amount of system
605      resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS`
606      to a number lower than the number of CPU threads in your machine
607      won't be sufficient. That's because each package will still be built
608      and installed through a number of parallel jobs specified by the
609      :term:`PARALLEL_MAKE` variable, which is by default the number of CPU
610      threads in your system, and is not impacted by the
611      :term:`BB_NUMBER_THREADS` value.
612
613      So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set
614      :term:`PARALLEL_MAKE`, most of your system resources will be consumed
615      anyway.
616
617      Therefore, if you intend to reduce the load of your build system by
618      setting :term:`BB_NUMBER_THREADS` to a relatively low value compared
619      to the number of CPU threads on your system, you should also set
620      :term:`PARALLEL_MAKE` to a similarly low value.
621
622      An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage
623      of build system resources under control is to use the smarter
624      :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or
625      :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake
626      from starting new tasks as long as thresholds are exceeded. Anyway,
627      as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the
628      tasks already being run from using all CPU threads on the system
629      if :term:`PARALLEL_MAKE` is not set to a low value.
630
631   :term:`BB_ORIGENV`
632      See :term:`bitbake:BB_ORIGENV` in the BitBake manual.
633
634   :term:`BB_PRESERVE_ENV`
635      See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual.
636
637   :term:`BB_PRESSURE_MAX_CPU`
638      See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual.
639
640   :term:`BB_PRESSURE_MAX_IO`
641      See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual.
642
643   :term:`BB_PRESSURE_MAX_MEMORY`
644      See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual.
645
646   :term:`BB_RUNFMT`
647      See :term:`bitbake:BB_RUNFMT` in the BitBake manual.
648
649   :term:`BB_RUNTASK`
650      See :term:`bitbake:BB_RUNTASK` in the BitBake manual.
651
652   :term:`BB_SCHEDULER`
653      See :term:`bitbake:BB_SCHEDULER` in the BitBake manual.
654
655   :term:`BB_SCHEDULERS`
656      See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual.
657
658   :term:`BB_SERVER_TIMEOUT`
659      Specifies the time (in seconds) after which to unload the BitBake
660      server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
661      long the BitBake server stays resident between invocations.
662
663      For example, the following statement in your ``local.conf`` file
664      instructs the server to be unloaded after 20 seconds of inactivity::
665
666         BB_SERVER_TIMEOUT = "20"
667
668      If you want the server to never be unloaded,
669      set :term:`BB_SERVER_TIMEOUT` to "-1".
670
671   :term:`BB_SETSCENE_DEPVALID`
672      See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual.
673
674   :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
675      See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual.
676
677   :term:`BB_SIGNATURE_HANDLER`
678      See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual.
679
680   :term:`BB_SRCREV_POLICY`
681      See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual.
682
683   :term:`BB_STRICT_CHECKSUM`
684      See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual.
685
686   :term:`BB_TASK_IONICE_LEVEL`
687      See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual.
688
689   :term:`BB_TASK_NICE_LEVEL`
690      See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual.
691
692   :term:`BB_TASKHASH`
693      See :term:`bitbake:BB_TASKHASH` in the BitBake manual.
694
695   :term:`BB_VERBOSE_LOGS`
696      See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual.
697
698   :term:`BB_WORKERCONTEXT`
699      See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual.
700
701   :term:`BBCLASSEXTEND`
702      Allows you to extend a recipe so that it builds variants of the
703      software. There are common variants for recipes as "natives" like
704      ``quilt-native``, which is a copy of Quilt built to run on the build
705      system; "crosses" such as ``gcc-cross``, which is a compiler built to
706      run on the build machine but produces binaries that run on the target
707      :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which
708      targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in
709      the form "``multilib:``\ multilib_name".
710
711      To build a different variant of the recipe with a minimal amount of
712      code, it usually is as simple as adding the following to your recipe::
713
714         BBCLASSEXTEND =+ "native nativesdk"
715         BBCLASSEXTEND =+ "multilib:multilib_name"
716
717      .. note::
718
719         Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
720         variants by rewriting variable values and applying overrides such
721         as ``:class-native``. For example, to generate a native version of
722         a recipe, a :term:`DEPENDS` on "foo" is rewritten
723         to a :term:`DEPENDS` on "foo-native".
724
725         Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
726         Parsing once adds some limitations. For example, it is not
727         possible to include a different file depending on the variant,
728         since ``include`` statements are processed when the recipe is
729         parsed.
730
731   :term:`BBDEBUG`
732      See :term:`bitbake:BBDEBUG` in the BitBake manual.
733
734   :term:`BBFILE_COLLECTIONS`
735      Lists the names of configured layers. These names are used to find
736      the other ``BBFILE_*`` variables. Typically, each layer will append
737      its name to this variable in its ``conf/layer.conf`` file.
738
739   :term:`BBFILE_PATTERN`
740      Variable that expands to match files from
741      :term:`BBFILES` in a particular layer. This variable
742      is used in the ``conf/layer.conf`` file and must be suffixed with the
743      name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
744
745   :term:`BBFILE_PRIORITY`
746      Assigns the priority for recipe files in each layer.
747
748      This variable is useful in situations where the same recipe appears
749      in more than one layer. Setting this variable allows you to
750      prioritize a layer against other layers that contain the same recipe
751      --- effectively letting you control the precedence for the multiple
752      layers. The precedence established through this variable stands
753      regardless of a recipe's version (:term:`PV` variable). For
754      example, a layer that has a recipe with a higher :term:`PV` value but for
755      which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still
756      has a lower precedence.
757
758      A larger value for the :term:`BBFILE_PRIORITY` variable results in a
759      higher precedence. For example, the value 6 has a higher precedence
760      than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
761      is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
762      for more information. The default priority, if unspecified for a
763      layer with no dependencies, is the lowest defined priority + 1 (or 1
764      if no priorities are defined).
765
766      .. tip::
767
768         You can use the command ``bitbake-layers show-layers``
769         to list all configured layers along with their priorities.
770
771   :term:`BBFILES`
772      A space-separated list of recipe files BitBake uses to build
773      software.
774
775      When specifying recipe files, you can pattern match using Python's
776      `glob <https://docs.python.org/3/library/glob.html>`__ syntax.
777      For details on the syntax, see the documentation by following the
778      previous link.
779
780   :term:`BBFILES_DYNAMIC`
781      Activates content when identified layers are present. You identify
782      the layers by the collections that the layers define.
783
784      Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files
785      whose corresponding ``.bb`` file is in a layer that attempts to
786      modify other layers through ``.bbappend`` but does not want to
787      introduce a hard dependency on those other layers.
788
789      Use the following form for :term:`BBFILES_DYNAMIC`:
790      ``collection_name:filename_pattern``.
791
792      The following example identifies two collection names and two
793      filename patterns::
794
795         BBFILES_DYNAMIC += " \
796            clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
797            core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
798            "
799
800      This next example shows an error message that occurs because invalid
801      entries are found, which cause parsing to fail:
802
803      .. code-block:: none
804
805         ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
806             /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
807             /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
808
809   :term:`BBINCLUDED`
810      See :term:`bitbake:BBINCLUDED` in the BitBake manual.
811
812   :term:`BBINCLUDELOGS`
813      Variable that controls how BitBake displays logs on build failure.
814
815   :term:`BBINCLUDELOGS_LINES`
816      If :term:`BBINCLUDELOGS` is set, specifies the
817      maximum number of lines from the task log file to print when
818      reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
819      the entire log is printed.
820
821   :term:`BBLAYERS`
822      Lists the layers to enable during the build. This variable is defined
823      in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
824      Here is an example::
825
826         BBLAYERS = " \
827             /home/scottrif/poky/meta \
828             /home/scottrif/poky/meta-poky \
829             /home/scottrif/poky/meta-yocto-bsp \
830             /home/scottrif/poky/meta-mykernel \
831             "
832
833      This example enables four layers, one of which is a custom,
834      user-defined layer named ``meta-mykernel``.
835
836   :term:`BBLAYERS_FETCH_DIR`
837      See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual.
838
839   :term:`BBMASK`
840      Prevents BitBake from processing recipes and recipe append files.
841
842      You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
843      ``.bbappend`` files. BitBake ignores any recipe or recipe append
844      files that match any of the expressions. It is as if BitBake does not
845      see them at all. Consequently, matching files are not parsed or
846      otherwise used by BitBake.
847
848      The values you provide are passed to Python's regular expression
849      compiler. Consequently, the syntax follows Python's Regular
850      Expression (re) syntax. The expressions are compared against the full
851      paths to the files. For complete syntax information, see Python's
852      documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax.
853
854      The following example uses a complete regular expression to tell
855      BitBake to ignore all recipe and recipe append files in the
856      ``meta-ti/recipes-misc/`` directory::
857
858         BBMASK = "meta-ti/recipes-misc/"
859
860      If you want to mask out multiple directories or recipes, you can
861      specify multiple regular expression fragments. This next example
862      masks out multiple directories and individual recipes::
863
864         BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
865         BBMASK += "/meta-oe/recipes-support/"
866         BBMASK += "/meta-foo/.*/openldap"
867         BBMASK += "opencv.*\.bbappend"
868         BBMASK += "lzma"
869
870      .. note::
871
872         When specifying a directory name, use the trailing slash character
873         to ensure you match just that directory name.
874
875   :term:`BBMULTICONFIG`
876      Specifies each additional separate configuration when you are
877      building targets with multiple configurations. Use this variable in
878      your ``conf/local.conf`` configuration file. Specify a
879      multiconfigname for each configuration file you are using. For
880      example, the following line specifies three configuration files::
881
882         BBMULTICONFIG = "configA configB configC"
883
884      Each configuration file you use must reside in a ``multiconfig``
885      subdirectory of a configuration directory within a layer, or
886      within the :term:`Build Directory` (e.g.
887      ``build_directory/conf/multiconfig/configA.conf`` or
888      ``mylayer/conf/multiconfig/configB.conf``).
889
890      For information on how to use :term:`BBMULTICONFIG` in an environment
891      that supports building targets with multiple configurations, see the
892      ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`"
893      section in the Yocto Project Development Tasks Manual.
894
895   :term:`BBPATH`
896      See :term:`bitbake:BBPATH` in the BitBake manual.
897
898   :term:`BBSERVER`
899      If defined in the BitBake environment, :term:`BBSERVER` points to the
900      BitBake remote server.
901
902      Use the following format to export the variable to the BitBake
903      environment::
904
905         export BBSERVER=localhost:$port
906
907      By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`.
908      Consequently, :term:`BBSERVER` is excluded from checksum and dependency
909      data.
910
911   :term:`BBTARGETS`
912      See :term:`bitbake:BBTARGETS` in the BitBake manual.
913
914   :term:`BINCONFIG`
915      When inheriting the :ref:`ref-classes-binconfig-disabled` class, this
916      variable specifies binary configuration scripts to disable in favor of
917      using ``pkg-config`` to query the information. The
918      :ref:`ref-classes-binconfig-disabled` class will modify the specified
919      scripts to return an error so that calls to them can be easily found
920      and replaced.
921
922      To add multiple scripts, separate them by spaces. Here is an example
923      from the ``libpng`` recipe::
924
925         BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
926
927   :term:`BINCONFIG_GLOB`
928      When inheriting the :ref:`ref-classes-binconfig` class,
929      this variable specifies a wildcard for configuration scripts that
930      need editing. The scripts are edited to correct any paths that have
931      been set up during compilation so that they are correct for use when
932      installed into the sysroot and called by the build processes of other
933      recipes.
934
935      .. note::
936
937         The :term:`BINCONFIG_GLOB` variable uses
938         `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__,
939         which is recognition and expansion of wildcards during pattern
940         matching. Shell globbing is very similar to
941         `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__
942         and `glob <https://docs.python.org/3/library/glob.html>`__.
943
944      For more information on how this variable works, see
945      ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`.
946      You can also find general
947      information on the class in the
948      ":ref:`ref-classes-binconfig`" section.
949
950   :term:`BITBAKE_UI`
951      See :term:`bitbake:BITBAKE_UI` in the BitBake manual.
952
953   :term:`BP`
954      The base recipe name and version but without any special recipe name
955      suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is
956      comprised of the following::
957
958         ${BPN}-${PV}
959
960   :term:`BPN`
961      This variable is a version of the :term:`PN` variable with
962      common prefixes and suffixes removed, such as ``nativesdk-``,
963      ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``.
964      The exact lists of prefixes and suffixes removed are specified by the
965      :term:`MLPREFIX` and
966      :term:`SPECIAL_PKGSUFFIX` variables,
967      respectively.
968
969   :term:`BUGTRACKER`
970      Specifies a URL for an upstream bug tracking website for a recipe.
971      The OpenEmbedded build system does not use this variable. Rather, the
972      variable is a useful pointer in case a bug in the software being
973      built needs to be manually reported.
974
975   :term:`BUILD_ARCH`
976      Specifies the architecture of the build host (e.g. ``i686``). The
977      OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
978      machine name reported by the ``uname`` command.
979
980   :term:`BUILD_AS_ARCH`
981      Specifies the architecture-specific assembler flags for the build
982      host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
983
984   :term:`BUILD_CC_ARCH`
985      Specifies the architecture-specific C compiler flags for the build
986      host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
987
988   :term:`BUILD_CCLD`
989      Specifies the linker command to be used for the build host when the C
990      compiler is being used as the linker. By default, :term:`BUILD_CCLD`
991      points to GCC and passes as arguments the value of
992      :term:`BUILD_CC_ARCH`, assuming
993      :term:`BUILD_CC_ARCH` is set.
994
995   :term:`BUILD_CFLAGS`
996      Specifies the flags to pass to the C compiler when building for the
997      build host. When building in the ``-native`` context,
998      :term:`CFLAGS` is set to the value of this variable by
999      default.
1000
1001   :term:`BUILD_CPPFLAGS`
1002      Specifies the flags to pass to the C preprocessor (i.e. to both the C
1003      and the C++ compilers) when building for the build host. When
1004      building in the ``-native`` context, :term:`CPPFLAGS`
1005      is set to the value of this variable by default.
1006
1007   :term:`BUILD_CXXFLAGS`
1008      Specifies the flags to pass to the C++ compiler when building for the
1009      build host. When building in the ``-native`` context,
1010      :term:`CXXFLAGS` is set to the value of this variable
1011      by default.
1012
1013   :term:`BUILD_FC`
1014      Specifies the Fortran compiler command for the build host. By
1015      default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
1016      value of :term:`BUILD_CC_ARCH`, assuming
1017      :term:`BUILD_CC_ARCH` is set.
1018
1019   :term:`BUILD_LD`
1020      Specifies the linker command for the build host. By default,
1021      :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
1022      the value of :term:`BUILD_LD_ARCH`, assuming
1023      :term:`BUILD_LD_ARCH` is set.
1024
1025   :term:`BUILD_LD_ARCH`
1026      Specifies architecture-specific linker flags for the build host. By
1027      default, the value of :term:`BUILD_LD_ARCH` is empty.
1028
1029   :term:`BUILD_LDFLAGS`
1030      Specifies the flags to pass to the linker when building for the build
1031      host. When building in the ``-native`` context,
1032      :term:`LDFLAGS` is set to the value of this variable
1033      by default.
1034
1035   :term:`BUILD_OPTIMIZATION`
1036      Specifies the optimization flags passed to the C compiler when
1037      building for the build host or the SDK. The flags are passed through
1038      the :term:`BUILD_CFLAGS` and
1039      :term:`BUILDSDK_CFLAGS` default values.
1040
1041      The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2
1042      -pipe".
1043
1044   :term:`BUILD_OS`
1045      Specifies the operating system in use on the build host (e.g.
1046      "linux"). The OpenEmbedded build system sets the value of
1047      :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the
1048      first word, converted to lower-case characters.
1049
1050   :term:`BUILD_PREFIX`
1051      The toolchain binary prefix used for native recipes. The OpenEmbedded
1052      build system uses the :term:`BUILD_PREFIX` value to set the
1053      :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes.
1054
1055   :term:`BUILD_STRIP`
1056      Specifies the command to be used to strip debugging symbols from
1057      binaries produced for the build host. By default, :term:`BUILD_STRIP`
1058      points to
1059      ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
1060
1061   :term:`BUILD_SYS`
1062      Specifies the system, including the architecture and the operating
1063      system, to use when building for the build host (i.e. when building
1064      :ref:`ref-classes-native` recipes).
1065
1066      The OpenEmbedded build system automatically sets this variable based
1067      on :term:`BUILD_ARCH`,
1068      :term:`BUILD_VENDOR`, and
1069      :term:`BUILD_OS`. You do not need to set the
1070      :term:`BUILD_SYS` variable yourself.
1071
1072   :term:`BUILD_VENDOR`
1073      Specifies the vendor name to use when building for the build host.
1074      The default value is an empty string ("").
1075
1076   :term:`BUILDDIR`
1077      Points to the location of the :term:`Build Directory`. You can define
1078      this directory indirectly through the :ref:`structure-core-script` script
1079      by passing in a :term:`Build Directory` path when you run the script. If
1080      you run the script and do not provide a :term:`Build Directory` path, the
1081      :term:`BUILDDIR` defaults to ``build`` in the current directory.
1082
1083   :term:`BUILDHISTORY_COMMIT`
1084      When inheriting the :ref:`ref-classes-buildhistory` class, this variable
1085      specifies whether or not to commit the build history output in a local
1086      Git repository. If set to "1", this local repository will be maintained
1087      automatically by the :ref:`ref-classes-buildhistory` class and a commit
1088      will be created on every build for changes to each top-level subdirectory
1089      of the build history output (images, packages, and sdk). If you want to
1090      track changes to build history over time, you should set this value to
1091      "1".
1092
1093      By default, the :ref:`ref-classes-buildhistory` class
1094      enables committing the buildhistory output in a local Git repository::
1095
1096         BUILDHISTORY_COMMIT ?= "1"
1097
1098   :term:`BUILDHISTORY_COMMIT_AUTHOR`
1099      When inheriting the :ref:`ref-classes-buildhistory`
1100      class, this variable specifies the author to use for each Git commit.
1101      In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the
1102      :term:`BUILDHISTORY_COMMIT` variable must
1103      be set to "1".
1104
1105      Git requires that the value you provide for the
1106      :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name
1107      email@host". Providing an email address or host that is not valid
1108      does not produce an error.
1109
1110      By default, the :ref:`ref-classes-buildhistory` class sets the variable
1111      as follows::
1112
1113         BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
1114
1115   :term:`BUILDHISTORY_DIR`
1116      When inheriting the :ref:`ref-classes-buildhistory`
1117      class, this variable specifies the directory in which build history
1118      information is kept. For more information on how the variable works,
1119      see the :ref:`ref-classes-buildhistory` class.
1120
1121      By default, the :ref:`ref-classes-buildhistory` class sets the directory
1122      as follows::
1123
1124         BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1125
1126   :term:`BUILDHISTORY_FEATURES`
1127      When inheriting the :ref:`ref-classes-buildhistory`
1128      class, this variable specifies the build history features to be
1129      enabled. For more information on how build history works, see the
1130      ":ref:`dev-manual/build-quality:maintaining build output quality`"
1131      section in the Yocto Project Development Tasks Manual.
1132
1133      You can specify these features in the form of a space-separated list:
1134
1135      -  *image:* Analysis of the contents of images, which includes the
1136         list of installed packages among other things.
1137
1138      -  *package:* Analysis of the contents of individual packages.
1139
1140      -  *sdk:* Analysis of the contents of the software development kit
1141         (SDK).
1142
1143      -  *task:* Save output file signatures for
1144         :ref:`shared state <overview-manual/concepts:shared state cache>`
1145         (sstate) tasks.
1146         This saves one file per task and lists the SHA-256 checksums for
1147         each file staged (i.e. the output of the task).
1148
1149      By default, the :ref:`ref-classes-buildhistory` class enables the
1150      following features::
1151
1152         BUILDHISTORY_FEATURES ?= "image package sdk"
1153
1154   :term:`BUILDHISTORY_IMAGE_FILES`
1155      When inheriting the :ref:`ref-classes-buildhistory`
1156      class, this variable specifies a list of paths to files copied from
1157      the image contents into the build history directory under an
1158      "image-files" directory in the directory for the image, so that you
1159      can track the contents of each file. The default is to copy
1160      ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for
1161      changes in user and group entries. You can modify the list to include
1162      any file. Specifying an invalid path does not produce an error.
1163      Consequently, you can include files that might not always be present.
1164
1165      By default, the :ref:`ref-classes-buildhistory` class provides paths to
1166      the following files::
1167
1168         BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1169
1170   :term:`BUILDHISTORY_PATH_PREFIX_STRIP`
1171      When inheriting the :ref:`ref-classes-buildhistory`
1172      class, this variable specifies a common path prefix that should be
1173      stripped off the beginning of paths in the task signature list when the
1174      ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be
1175      useful when build history is populated from multiple sources that may not
1176      all use the same top level directory.
1177
1178      By default, the :ref:`ref-classes-buildhistory` class sets the variable
1179      as follows::
1180
1181         BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
1182
1183      In this case, no prefixes will be stripped.
1184
1185   :term:`BUILDHISTORY_PUSH_REPO`
1186      When inheriting the :ref:`ref-classes-buildhistory` class, this variable
1187      optionally specifies a remote repository to which build history pushes
1188      Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work,
1189      :term:`BUILDHISTORY_COMMIT` must be set to "1".
1190
1191      The repository should correspond to a remote address that specifies a
1192      repository as understood by Git, or alternatively to a remote name
1193      that you have set up manually using ``git remote`` within the local
1194      repository.
1195
1196      By default, the :ref:`ref-classes-buildhistory` class sets the variable
1197      as follows::
1198
1199         BUILDHISTORY_PUSH_REPO ?= ""
1200
1201   :term:`BUILDNAME`
1202      See :term:`bitbake:BUILDNAME` in the BitBake manual.
1203
1204   :term:`BUILDSDK_CFLAGS`
1205      Specifies the flags to pass to the C compiler when building for the
1206      SDK. When building in the ``nativesdk-`` context,
1207      :term:`CFLAGS` is set to the value of this variable by
1208      default.
1209
1210   :term:`BUILDSDK_CPPFLAGS`
1211      Specifies the flags to pass to the C pre-processor (i.e. to both the
1212      C and the C++ compilers) when building for the SDK. When building in
1213      the ``nativesdk-`` context, :term:`CPPFLAGS` is set
1214      to the value of this variable by default.
1215
1216   :term:`BUILDSDK_CXXFLAGS`
1217      Specifies the flags to pass to the C++ compiler when building for the
1218      SDK. When building in the ``nativesdk-`` context,
1219      :term:`CXXFLAGS` is set to the value of this variable
1220      by default.
1221
1222   :term:`BUILDSDK_LDFLAGS`
1223      Specifies the flags to pass to the linker when building for the SDK.
1224      When building in the ``nativesdk-`` context,
1225      :term:`LDFLAGS` is set to the value of this variable
1226      by default.
1227
1228   :term:`BUILDSTATS_BASE`
1229      Points to the location of the directory that holds build statistics
1230      when you use and enable the :ref:`ref-classes-buildstats` class. The
1231      :term:`BUILDSTATS_BASE` directory defaults to
1232      ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
1233
1234   :term:`BUSYBOX_SPLIT_SUID`
1235      For the BusyBox recipe, specifies whether to split the output
1236      executable file into two parts: one for features that require
1237      ``setuid root``, and one for the remaining features (i.e. those that
1238      do not require ``setuid root``).
1239
1240      The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in
1241      splitting the output executable file. Set the variable to "0" to get
1242      a single output executable file.
1243
1244   :term:`BZRDIR`
1245      See :term:`bitbake:BZRDIR` in the BitBake manual.
1246
1247   :term:`CACHE`
1248      Specifies the directory BitBake uses to store a cache of the
1249      :term:`Metadata` so it does not need to be parsed every time
1250      BitBake is started.
1251
1252   :term:`CC`
1253      The minimal command and arguments used to run the C compiler.
1254
1255   :term:`CFLAGS`
1256      Specifies the flags to pass to the C compiler. This variable is
1257      exported to an environment variable and thus made visible to the
1258      software being built during the compilation step.
1259
1260      Default initialization for :term:`CFLAGS` varies depending on what is
1261      being built:
1262
1263      -  :term:`TARGET_CFLAGS` when building for the
1264         target
1265
1266      -  :term:`BUILD_CFLAGS` when building for the
1267         build host (i.e. ``-native``)
1268
1269      -  :term:`BUILDSDK_CFLAGS` when building for
1270         an SDK (i.e. ``nativesdk-``)
1271
1272   :term:`CLASSOVERRIDE`
1273      An internal variable specifying the special class override that
1274      should currently apply (e.g. "class-target", "class-native", and so
1275      forth). The classes that use this variable (e.g.
1276      :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth)
1277      set the variable to appropriate values.
1278
1279      .. note::
1280
1281         :term:`CLASSOVERRIDE` gets its default "class-target" value from the
1282         ``bitbake.conf`` file.
1283
1284      As an example, the following override allows you to install extra
1285      files, but only when building for the target::
1286
1287         do_install:append:class-target() {
1288             install my-extra-file ${D}${sysconfdir}
1289         }
1290
1291      Here is an example where ``FOO`` is set to
1292      "native" when building for the build host, and to "other" when not
1293      building for the build host::
1294
1295         FOO:class-native = "native"
1296         FOO = "other"
1297
1298      The underlying mechanism behind :term:`CLASSOVERRIDE` is simply
1299      that it is included in the default value of
1300      :term:`OVERRIDES`.
1301
1302   :term:`CLEANBROKEN`
1303      If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the
1304      ``make clean`` command does not work for the software being built.
1305      Consequently, the OpenEmbedded build system will not try to run
1306      ``make clean`` during the :ref:`ref-tasks-configure`
1307      task, which is the default behavior.
1308
1309   :term:`COMBINED_FEATURES`
1310      Provides a list of hardware features that are enabled in both
1311      :term:`MACHINE_FEATURES` and
1312      :term:`DISTRO_FEATURES`. This select list of
1313      features contains features that make sense to be controlled both at
1314      the machine and distribution configuration level. For example, the
1315      "bluetooth" feature requires hardware support but should also be
1316      optional at the distribution level, in case the hardware supports
1317      Bluetooth but you do not ever intend to use it.
1318
1319   :term:`COMMERCIAL_AUDIO_PLUGINS`
1320      This variable is specific to the :yocto_git:`GStreamer recipes
1321      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1322      It allows to build the GStreamer `"ugly"
1323      <https://github.com/GStreamer/gst-plugins-ugly>`__ and
1324      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins.
1325
1326      See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1327      section for usage details.
1328
1329   :term:`COMMERCIAL_VIDEO_PLUGINS`
1330      This variable is specific to the :yocto_git:`GStreamer recipes
1331      </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1332      It allows to build the GStreamer `"ugly"
1333      <https://github.com/GStreamer/gst-plugins-ugly>`__ and
1334      `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins.
1335
1336      See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1337      section for usage details.
1338
1339   :term:`COMMON_LICENSE_DIR`
1340      Points to ``meta/files/common-licenses`` in the
1341      :term:`Source Directory`, which is where generic license
1342      files reside.
1343
1344   :term:`COMPATIBLE_HOST`
1345      A regular expression that resolves to one or more hosts (when the
1346      recipe is native) or one or more targets (when the recipe is
1347      non-native) with which a recipe is compatible. The regular expression
1348      is matched against :term:`HOST_SYS`. You can use the
1349      variable to stop recipes from being built for classes of systems with
1350      which the recipes are not compatible. Stopping these builds is
1351      particularly useful with kernels. The variable also helps to increase
1352      parsing speed since the build system skips parsing recipes not
1353      compatible with the current system.
1354
1355   :term:`COMPATIBLE_MACHINE`
1356      A regular expression that resolves to one or more target machines
1357      with which a recipe is compatible. The regular expression is matched
1358      against :term:`MACHINEOVERRIDES`. You can use
1359      the variable to stop recipes from being built for machines with which
1360      the recipes are not compatible. Stopping these builds is particularly
1361      useful with kernels. The variable also helps to increase parsing
1362      speed since the build system skips parsing recipes not compatible
1363      with the current machine.
1364
1365      If one wants to have a recipe only available for some architectures
1366      (here ``aarch64`` and ``mips64``), the following can be used::
1367
1368         COMPATIBLE_MACHINE = "^$"
1369         COMPATIBLE_MACHINE:arch64 = "^(aarch64)$"
1370         COMPATIBLE_MACHINE:mips64 = "^(mips64)$"
1371
1372      The first line means "match all machines whose :term:`MACHINEOVERRIDES`
1373      contains the empty string", which will always be none.
1374
1375      The second is for matching all machines whose :term:`MACHINEOVERRIDES`
1376      contains one override which is exactly ``aarch64``.
1377
1378      The third is for matching all machines whose :term:`MACHINEOVERRIDES`
1379      contains one override which is exactly ``mips64``.
1380
1381      The same could be achieved with::
1382
1383         COMPATIBLE_MACHINE = "^(aarch64|mips64)$"
1384
1385      .. note::
1386
1387         When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from
1388         native, the recipe is always skipped. All native recipes must be
1389         entirely target independent and should not rely on :term:`MACHINE`.
1390
1391   :term:`COMPLEMENTARY_GLOB`
1392      Defines wildcards to match when installing a list of complementary
1393      packages for all the packages explicitly (or implicitly) installed in
1394      an image.
1395
1396      The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching
1397      (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__),
1398      which is similar to the Unix style pathname pattern expansion
1399      (`glob <https://docs.python.org/3/library/glob.html>`__).
1400
1401      The resulting list of complementary packages is associated with an
1402      item that can be added to
1403      :term:`IMAGE_FEATURES`. An example usage of
1404      this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES`
1405      will install -dev packages (containing headers and other development
1406      files) for every package in the image.
1407
1408      To add a new feature item pointing to a wildcard, use a variable flag
1409      to specify the feature item name and use the value to specify the
1410      wildcard. Here is an example::
1411
1412         COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1413
1414      .. note::
1415
1416         When installing complementary packages, recommends relationships
1417         (set via :term:`RRECOMMENDS`) are always ignored.
1418
1419   :term:`COMPONENTS_DIR`
1420      Stores sysroot components for each recipe. The OpenEmbedded build
1421      system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
1422      sysroots for other recipes.
1423
1424      The default is
1425      "``${``\ :term:`STAGING_DIR`\ ``}-components``."
1426      (i.e.
1427      "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
1428
1429   :term:`CONF_VERSION`
1430      Tracks the version of the local configuration file (i.e.
1431      ``local.conf``). The value for :term:`CONF_VERSION` increments each time
1432      ``build/conf/`` compatibility changes.
1433
1434   :term:`CONFFILES`
1435      Identifies editable or configurable files that are part of a package.
1436      If the Package Management System (PMS) is being used to update
1437      packages on the target system, it is possible that configuration
1438      files you have changed after the original installation and that you
1439      now want to remain unchanged are overwritten. In other words,
1440      editable files might exist in the package that you do not want reset
1441      as part of the package update process. You can use the :term:`CONFFILES`
1442      variable to list the files in the package that you wish to prevent
1443      the PMS from overwriting during this update process.
1444
1445      To use the :term:`CONFFILES` variable, provide a package name override
1446      that identifies the resulting package. Then, provide a
1447      space-separated list of files. Here is an example::
1448
1449         CONFFILES:${PN} += "${sysconfdir}/file1 \
1450             ${sysconfdir}/file2 ${sysconfdir}/file3"
1451
1452      There is a relationship between the :term:`CONFFILES` and :term:`FILES`
1453      variables. The files listed within :term:`CONFFILES` must be a subset of
1454      the files listed within :term:`FILES`. Because the configuration files
1455      you provide with :term:`CONFFILES` are simply being identified so that
1456      the PMS will not overwrite them, it makes sense that the files must
1457      already be included as part of the package through the :term:`FILES`
1458      variable.
1459
1460      .. note::
1461
1462         When specifying paths as part of the :term:`CONFFILES` variable, it is
1463         good practice to use appropriate path variables.
1464         For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}``
1465         rather than ``/usr/bin``. You can find a list of these variables at
1466         the top of the ``meta/conf/bitbake.conf`` file in the
1467         :term:`Source Directory`.
1468
1469   :term:`CONFIG_INITRAMFS_SOURCE`
1470      Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The
1471      OpenEmbedded build system receives and uses this kernel Kconfig
1472      variable as an environment variable. By default, the variable is set
1473      to null ("").
1474
1475      The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
1476      with a ``.cpio`` suffix or a space-separated list of directories and
1477      files for building the :term:`Initramfs` image. A cpio archive should contain
1478      a filesystem archive to be used as an :term:`Initramfs` image. Directories
1479      should contain a filesystem layout to be included in the :term:`Initramfs`
1480      image. Files should contain entries according to the format described
1481      by the ``usr/gen_init_cpio`` program in the kernel tree.
1482
1483      If you specify multiple directories and files, the :term:`Initramfs` image
1484      will be the aggregate of all of them.
1485
1486      For information on creating an :term:`Initramfs`, see the
1487      ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
1488      in the Yocto Project Development Tasks Manual.
1489
1490   :term:`CONFIG_SITE`
1491      A list of files that contains ``autoconf`` test results relevant to
1492      the current build. This variable is used by the Autotools utilities
1493      when running ``configure``.
1494
1495   :term:`CONFIGURE_FLAGS`
1496      The minimal arguments for GNU configure.
1497
1498   :term:`CONFLICT_DISTRO_FEATURES`
1499      When inheriting the :ref:`ref-classes-features_check`
1500      class, this variable identifies distribution features that would be
1501      in conflict should the recipe be built. In other words, if the
1502      :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also
1503      appears in :term:`DISTRO_FEATURES` within the current configuration, then
1504      the recipe will be skipped, and if the build system attempts to build
1505      the recipe then an error will be triggered.
1506
1507   :term:`CONVERSION_CMD`
1508      This variable is used for storing image conversion commands.
1509      Image conversion can convert an image into different objects like:
1510
1511      -   Compressed version of the image
1512
1513      -   Checksums for the image
1514
1515      An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types`
1516      class is::
1517
1518         CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}"
1519
1520   :term:`COPY_LIC_DIRS`
1521      If set to "1" along with the
1522      :term:`COPY_LIC_MANIFEST` variable, the
1523      OpenEmbedded build system copies into the image the license files,
1524      which are located in ``/usr/share/common-licenses``, for each
1525      package. The license files are placed in directories within the image
1526      itself during build time.
1527
1528      .. note::
1529
1530         The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for
1531         newly installed packages to an image, which might be most suitable for
1532         read-only filesystems that cannot be upgraded. See the
1533         :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
1534         You can also reference the ":ref:`dev-manual/licenses:providing license text`"
1535         section in the Yocto Project Development Tasks Manual for
1536         information on providing license text.
1537
1538   :term:`COPY_LIC_MANIFEST`
1539      If set to "1", the OpenEmbedded build system copies the license
1540      manifest for the image to
1541      ``/usr/share/common-licenses/license.manifest`` within the image
1542      itself during build time.
1543
1544      .. note::
1545
1546         The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for
1547         newly installed packages to an image, which might be most suitable for
1548         read-only filesystems that cannot be upgraded. See the
1549         :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
1550         You can also reference the ":ref:`dev-manual/licenses:providing license text`"
1551         section in the Yocto Project Development Tasks Manual for
1552         information on providing license text.
1553
1554   :term:`COPYLEFT_LICENSE_EXCLUDE`
1555      A space-separated list of licenses to exclude from the source archived by
1556      the :ref:`ref-classes-archiver` class. In other words, if a license in a
1557      recipe's :term:`LICENSE` value is in the value of
1558      :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the
1559      class.
1560
1561      .. note::
1562
1563         The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the
1564         :term:`COPYLEFT_LICENSE_INCLUDE` variable.
1565
1566      The default value, which is "CLOSED Proprietary", for
1567      :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the
1568      :ref:`ref-classes-copyleft_filter` class, which
1569      is inherited by the :ref:`ref-classes-archiver` class.
1570
1571   :term:`COPYLEFT_LICENSE_INCLUDE`
1572      A space-separated list of licenses to include in the source archived
1573      by the :ref:`ref-classes-archiver` class. In other
1574      words, if a license in a recipe's :term:`LICENSE`
1575      value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its
1576      source is archived by the class.
1577
1578      The default value is set by the :ref:`ref-classes-copyleft_filter` class,
1579      which is inherited by the :ref:`ref-classes-archiver` class. The default
1580      value includes "GPL*", "LGPL*", and "AGPL*".
1581
1582   :term:`COPYLEFT_PN_EXCLUDE`
1583      A list of recipes to exclude in the source archived by the
1584      :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE`
1585      variable overrides the license inclusion and exclusion caused through the
1586      :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
1587      variables, respectively.
1588
1589      The default value, which is "" indicating to not explicitly exclude
1590      any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the
1591      :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1592      :ref:`ref-classes-archiver` class.
1593
1594   :term:`COPYLEFT_PN_INCLUDE`
1595      A list of recipes to include in the source archived by the
1596      :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE`
1597      variable overrides the license inclusion and exclusion caused through the
1598      :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
1599      variables, respectively.
1600
1601      The default value, which is "" indicating to not explicitly include
1602      any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the
1603      :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1604      :ref:`ref-classes-archiver` class.
1605
1606   :term:`COPYLEFT_RECIPE_TYPES`
1607      A space-separated list of recipe types to include in the source
1608      archived by the :ref:`archiver <ref-classes-archiver>` class.
1609      Recipe types are ``target``, :ref:`ref-classes-native`,
1610      :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`,
1611      :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`.
1612
1613      The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES`
1614      is set by the :ref:`ref-classes-copyleft_filter` class, which is
1615      inherited by the :ref:`ref-classes-archiver` class.
1616
1617   :term:`CORE_IMAGE_EXTRA_INSTALL`
1618      Specifies the list of packages to be added to the image. You should
1619      only set this variable in the ``local.conf`` configuration file found
1620      in the :term:`Build Directory`.
1621
1622      This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
1623      supported.
1624
1625   :term:`COREBASE`
1626      Specifies the parent directory of the OpenEmbedded-Core Metadata
1627      layer (i.e. ``meta``).
1628
1629      It is an important distinction that :term:`COREBASE` points to the parent
1630      of this layer and not the layer itself. Consider an example where you
1631      have cloned the Poky Git repository and retained the ``poky`` name
1632      for your local copy of the repository. In this case, :term:`COREBASE`
1633      points to the ``poky`` folder because it is the parent directory of
1634      the ``poky/meta`` layer.
1635
1636   :term:`COREBASE_FILES`
1637      Lists files from the :term:`COREBASE` directory that
1638      should be copied other than the layers listed in the
1639      ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
1640      to copy metadata from the OpenEmbedded build system
1641      into the extensible SDK.
1642
1643      Explicitly listing files in :term:`COREBASE` is needed because it
1644      typically contains build directories and other files that should not
1645      normally be copied into the extensible SDK. Consequently, the value
1646      of :term:`COREBASE_FILES` is used in order to only copy the files that
1647      are actually needed.
1648
1649   :term:`CPP`
1650      The minimal command and arguments used to run the C preprocessor.
1651
1652   :term:`CPPFLAGS`
1653      Specifies the flags to pass to the C pre-processor (i.e. to both the
1654      C and the C++ compilers). This variable is exported to an environment
1655      variable and thus made visible to the software being built during the
1656      compilation step.
1657
1658      Default initialization for :term:`CPPFLAGS` varies depending on what is
1659      being built:
1660
1661      -  :term:`TARGET_CPPFLAGS` when building for
1662         the target
1663
1664      -  :term:`BUILD_CPPFLAGS` when building for the
1665         build host (i.e. ``-native``)
1666
1667      -  :term:`BUILDSDK_CPPFLAGS` when building
1668         for an SDK (i.e. ``nativesdk-``)
1669
1670   :term:`CROSS_COMPILE`
1671      The toolchain binary prefix for the target tools. The
1672      :term:`CROSS_COMPILE` variable is the same as the
1673      :term:`TARGET_PREFIX` variable.
1674
1675      .. note::
1676
1677         The OpenEmbedded build system sets the :term:`CROSS_COMPILE`
1678         variable only in certain contexts (e.g. when building for kernel
1679         and kernel module recipes).
1680
1681   :term:`CVE_CHECK_IGNORE`
1682      This variable is deprecated and should be replaced by :term:`CVE_STATUS`.
1683
1684   :term:`CVE_CHECK_REPORT_PATCHED`
1685      Specifies whether or not the :ref:`ref-classes-cve-check`
1686      class should report patched or ignored CVEs. The default is "1", but you
1687      may wish to set it to "0" if you do not need patched or ignored CVEs in
1688      the logs.
1689
1690   :term:`CVE_CHECK_SHOW_WARNINGS`
1691      Specifies whether or not the :ref:`ref-classes-cve-check`
1692      class should generate warning messages on the console when unpatched
1693      CVEs are found. The default is "1", but you may wish to set it to "0" if
1694      you are already examining/processing the logs after the build has
1695      completed and thus do not need the warning messages.
1696
1697   :term:`CVE_CHECK_SKIP_RECIPE`
1698      The list of package names (:term:`PN`) for which
1699      CVEs (Common Vulnerabilities and Exposures) are ignored.
1700
1701   :term:`CVE_DB_INCR_UPDATE_AGE_THRES`
1702      Specifies the maximum age of the CVE database in seconds for an
1703      incremental update (instead of a full-download). Use "0" to force a
1704      full-download.
1705
1706   :term:`CVE_DB_UPDATE_INTERVAL`
1707      Specifies the CVE database update interval in seconds, as used by
1708      ``cve-update-db-native``. The default value is "86400" i.e. once a day
1709      (24*60*60). If the value is set to "0" then the update will be forced
1710      every time. Alternatively, a negative value e.g. "-1" will disable
1711      updates entirely.
1712
1713   :term:`CVE_PRODUCT`
1714      In a recipe, defines the name used to match the recipe name
1715      against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
1716
1717      The default is ${:term:`BPN`} (except for recipes that inherit the
1718      :ref:`ref-classes-pypi` class where it is set based upon
1719      :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE
1720      database or matches with multiple entries in the database, the default
1721      value needs to be changed.
1722
1723      Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
1724
1725         CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
1726
1727      Sometimes the product name is not specific enough, for example
1728      "tar" has been matching CVEs for the GNU ``tar`` package and also
1729      the ``node-tar`` node.js extension. To avoid this problem, use the
1730      vendor name as a prefix. The syntax for this is::
1731
1732         CVE_PRODUCT = "vendor:package"
1733
1734   :term:`CVE_STATUS`
1735      The CVE ID which is patched or should be ignored. Here is
1736      an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
1737
1738         CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
1739
1740      It has the format "reason: description" and the description is optional.
1741      The Reason is mapped to the final CVE state by mapping via
1742      :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes`
1743      for details.
1744
1745   :term:`CVE_STATUS_GROUPS`
1746      If there are many CVEs with the same status and reason, they can by simplified by using this
1747      variable instead of many similar lines with :term:`CVE_STATUS`::
1748
1749         CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"
1750
1751         CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002"
1752         CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows"
1753         CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004"
1754         CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally"
1755
1756   :term:`CVE_CHECK_STATUSMAP`
1757      Mapping variable for all possible reasons of :term:`CVE_STATUS`:
1758      ``Patched``, ``Unpatched`` and ``Ignored``.
1759      See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details::
1760
1761         CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"
1762
1763   :term:`CVE_VERSION`
1764      In a recipe, defines the version used to match the recipe version
1765      against the version in the `NIST CVE database <https://nvd.nist.gov/>`__
1766      when usign :ref:`ref-classes-cve-check`.
1767
1768      The default is ${:term:`PV`} but if recipes use custom version numbers
1769      which do not map to upstream software component release versions and the versions
1770      used in the CVE database, then this variable can be used to set the
1771      version number for :ref:`ref-classes-cve-check`. Example::
1772
1773          CVE_VERSION = "2.39"
1774
1775   :term:`CVSDIR`
1776      The directory in which files checked out under the CVS system are
1777      stored.
1778
1779   :term:`CXX`
1780      The minimal command and arguments used to run the C++ compiler.
1781
1782   :term:`CXXFLAGS`
1783      Specifies the flags to pass to the C++ compiler. This variable is
1784      exported to an environment variable and thus made visible to the
1785      software being built during the compilation step.
1786
1787      Default initialization for :term:`CXXFLAGS` varies depending on what is
1788      being built:
1789
1790      -  :term:`TARGET_CXXFLAGS` when building for
1791         the target
1792
1793      -  :term:`BUILD_CXXFLAGS` when building for the
1794         build host (i.e. ``-native``)
1795
1796      -  :term:`BUILDSDK_CXXFLAGS` when building
1797         for an SDK (i.e. ``nativesdk-``)
1798
1799   :term:`D`
1800      The destination directory. The location in the :term:`Build Directory`
1801      where components are installed by the
1802      :ref:`ref-tasks-install` task. This location defaults
1803      to::
1804
1805         ${WORKDIR}/image
1806
1807      .. note::
1808
1809         Tasks that read from or write to this directory should run under
1810         :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
1811
1812   :term:`DATE`
1813      The date the build was started. Dates appear using the year, month,
1814      and day (YMD) format (e.g. "20150209" for February 9th, 2015).
1815
1816   :term:`DATETIME`
1817      The date and time on which the current build started. The format is
1818      suitable for timestamps.
1819
1820   :term:`DEBIAN_NOAUTONAME`
1821      When the :ref:`ref-classes-debian` class is inherited,
1822      which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
1823      particular package should not be renamed according to Debian library
1824      package naming. You must use the package name as an override when you
1825      set this variable. Here is an example from the ``fontconfig`` recipe::
1826
1827         DEBIAN_NOAUTONAME:fontconfig-utils = "1"
1828
1829   :term:`DEBIANNAME`
1830      When the :ref:`ref-classes-debian` class is inherited,
1831      which is the default behavior, :term:`DEBIANNAME` allows you to override
1832      the library name for an individual package. Overriding the library
1833      name in these cases is rare. You must use the package name as an
1834      override when you set this variable. Here is an example from the
1835      ``dbus`` recipe::
1836
1837         DEBIANNAME:${PN} = "dbus-1"
1838
1839   :term:`DEBUG_BUILD`
1840      Specifies to build packages with debugging information. This
1841      influences the value of the :term:`SELECTED_OPTIMIZATION` variable.
1842
1843   :term:`DEBUG_OPTIMIZATION`
1844      The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
1845      compiling a system for debugging. This variable defaults to "-O
1846      -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1847
1848   :term:`DEBUG_PREFIX_MAP`
1849      Allows to set C compiler options, such as ``-fdebug-prefix-map``,
1850      ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to
1851      replace build-time paths by install-time ones in the debugging sections
1852      of binaries.  This makes compiler output files location independent,
1853      at the cost of having to pass an extra command to tell the debugger
1854      where source files are.
1855
1856      This is used by the Yocto Project to guarantee
1857      :doc:`/test-manual/reproducible-builds` even when the source code of
1858      a package uses the ``__FILE__`` or ``assert()`` macros. See the
1859      `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__
1860      website for details.
1861
1862      This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1863      not intended to be user-configurable.
1864
1865   :term:`DEFAULT_PREFERENCE`
1866      Specifies a weak bias for recipe selection priority.
1867
1868      The most common usage of this is variable is to set it to "-1" within
1869      a recipe for a development version of a piece of software. Using the
1870      variable in this way causes the stable version of the recipe to build
1871      by default in the absence of :term:`PREFERRED_VERSION` being used to
1872      build the development version.
1873
1874      .. note::
1875
1876         The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden
1877         by :term:`BBFILE_PRIORITY` if that variable is different between two
1878         layers that contain different versions of the same recipe.
1879
1880   :term:`DEFAULTTUNE`
1881      The default CPU and Application Binary Interface (ABI) tunings (i.e.
1882      the "tune") used by the OpenEmbedded build system. The
1883      :term:`DEFAULTTUNE` helps define
1884      :term:`TUNE_FEATURES`.
1885
1886      The default tune is either implicitly or explicitly set by the
1887      machine (:term:`MACHINE`). However, you can override
1888      the setting using available tunes as defined with
1889      :term:`AVAILTUNES`.
1890
1891   :term:`DEPENDS`
1892      Lists a recipe's build-time dependencies. These are dependencies on
1893      other recipes whose contents (e.g. headers and shared libraries) are
1894      needed by the recipe at build time.
1895
1896      As an example, consider a recipe ``foo`` that contains the following
1897      assignment::
1898
1899          DEPENDS = "bar"
1900
1901      The practical effect of the previous assignment is that all files
1902      installed by bar will be available in the appropriate staging sysroot,
1903      given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time
1904      the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is
1905      implemented by having :ref:`ref-tasks-configure` depend on the
1906      :ref:`ref-tasks-populate_sysroot` task of each recipe listed in
1907      :term:`DEPENDS`, through a
1908      ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1909      declaration in the :ref:`ref-classes-base` class.
1910
1911      .. note::
1912
1913         It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
1914         explicitly. The standard classes and build-related variables are
1915         configured to automatically use the appropriate staging sysroots.
1916
1917      As another example, :term:`DEPENDS` can also be used to add utilities
1918      that run on the build machine during the build. For example, a recipe
1919      that makes use of a code generator built by the recipe ``codegen``
1920      might have the following::
1921
1922         DEPENDS = "codegen-native"
1923
1924      For more
1925      information, see the :ref:`ref-classes-native` class and
1926      the :term:`EXTRANATIVEPATH` variable.
1927
1928      .. note::
1929
1930         -  :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
1931            it is a list of :term:`PROVIDES` names, which
1932            usually match recipe names. Putting a package name such as
1933            "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
1934            instead, as this will put files from all the packages that make
1935            up ``foo``, which includes those from ``foo-dev``, into the
1936            sysroot.
1937
1938         -  One recipe having another recipe in :term:`DEPENDS` does not by
1939            itself add any runtime dependencies between the packages
1940            produced by the two recipes. However, as explained in the
1941            ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
1942            section in the Yocto Project Overview and Concepts Manual,
1943            runtime dependencies will often be added automatically, meaning
1944            :term:`DEPENDS` alone is sufficient for most recipes.
1945
1946         -  Counterintuitively, :term:`DEPENDS` is often necessary even for
1947            recipes that install precompiled components. For example, if
1948            ``libfoo`` is a precompiled library that links against
1949            ``libbar``, then linking against ``libfoo`` requires both
1950            ``libfoo`` and ``libbar`` to be available in the sysroot.
1951            Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
1952            to the recipe that installs ``libbar``, other recipes might
1953            fail to link against ``libfoo``.
1954
1955      For information on runtime dependencies, see the :term:`RDEPENDS`
1956      variable. You can also see the
1957      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
1958      ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
1959      sections in the BitBake User Manual for additional information on tasks
1960      and dependencies.
1961
1962   :term:`DEPLOY_DIR`
1963      Points to the general area that the OpenEmbedded build system uses to
1964      place images, packages, SDKs, and other output files that are ready
1965      to be used outside of the build system. By default, this directory
1966      resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``.
1967
1968      For more information on the structure of the Build Directory, see
1969      ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
1970      For more detail on the contents of the ``deploy`` directory, see the
1971      ":ref:`overview-manual/concepts:images`",
1972      ":ref:`overview-manual/concepts:package feeds`", and
1973      ":ref:`overview-manual/concepts:application development sdk`" sections all in the
1974      Yocto Project Overview and Concepts Manual.
1975
1976   :term:`DEPLOY_DIR_DEB`
1977      Points to the area that the OpenEmbedded build system uses to place
1978      Debian packages that are ready to be used outside of the build
1979      system. This variable applies only when :term:`PACKAGE_CLASSES` contains
1980      ":ref:`ref-classes-package_deb`".
1981
1982      The BitBake configuration file initially defines the
1983      :term:`DEPLOY_DIR_DEB` variable as a sub-folder of
1984      :term:`DEPLOY_DIR`::
1985
1986         DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
1987
1988      The :ref:`ref-classes-package_deb` class uses the
1989      :term:`DEPLOY_DIR_DEB` variable to make sure the
1990      :ref:`ref-tasks-package_write_deb` task
1991      writes Debian packages into the appropriate folder. For more
1992      information on how packaging works, see the
1993      ":ref:`overview-manual/concepts:package feeds`" section
1994      in the Yocto Project Overview and Concepts Manual.
1995
1996   :term:`DEPLOY_DIR_IMAGE`
1997      Points to the area that the OpenEmbedded build system uses to place
1998      images and other associated output files that are ready to be
1999      deployed onto the target machine. The directory is machine-specific
2000      as it contains the ``${MACHINE}`` name. By default, this directory
2001      resides within the :term:`Build Directory` as
2002      ``${DEPLOY_DIR}/images/${MACHINE}/``.
2003
2004      It must not be used directly in recipes when deploying files. Instead,
2005      it's only useful when a recipe needs to "read" a file already deployed
2006      by a dependency. So, it should be filled with the contents of
2007      :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the
2008      contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class.
2009
2010      For more information on the structure of the :term:`Build Directory`, see
2011      ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
2012      For more detail on the contents of the ``deploy`` directory, see the
2013      ":ref:`overview-manual/concepts:images`" and
2014      ":ref:`overview-manual/concepts:application development sdk`" sections both in
2015      the Yocto Project Overview and Concepts Manual.
2016
2017   :term:`DEPLOY_DIR_IPK`
2018      Points to the area that the OpenEmbedded build system uses to place
2019      IPK packages that are ready to be used outside of the build system.
2020      This variable applies only when :term:`PACKAGE_CLASSES` contains
2021      ":ref:`ref-classes-package_ipk`".
2022
2023      The BitBake configuration file initially defines this variable as a
2024      sub-folder of :term:`DEPLOY_DIR`::
2025
2026         DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
2027
2028      The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK`
2029      variable to make sure the :ref:`ref-tasks-package_write_ipk` task
2030      writes IPK packages into the appropriate folder. For more information
2031      on how packaging works, see the
2032      ":ref:`overview-manual/concepts:package feeds`" section
2033      in the Yocto Project Overview and Concepts Manual.
2034
2035   :term:`DEPLOY_DIR_RPM`
2036      Points to the area that the OpenEmbedded build system uses to place
2037      RPM packages that are ready to be used outside of the build system.
2038      This variable applies only when :term:`PACKAGE_CLASSES` contains
2039      ":ref:`ref-classes-package_rpm`".
2040
2041      The BitBake configuration file initially defines this variable as a
2042      sub-folder of :term:`DEPLOY_DIR`::
2043
2044         DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
2045
2046      The :ref:`ref-classes-package_rpm` class uses the
2047      :term:`DEPLOY_DIR_RPM` variable to make sure the
2048      :ref:`ref-tasks-package_write_rpm` task
2049      writes RPM packages into the appropriate folder. For more information
2050      on how packaging works, see the
2051      ":ref:`overview-manual/concepts:package feeds`" section
2052      in the Yocto Project Overview and Concepts Manual.
2053
2054   :term:`DEPLOYDIR`
2055      When inheriting the :ref:`ref-classes-deploy` class, the
2056      :term:`DEPLOYDIR` points to a temporary work area for deployed files that
2057      is set in the :ref:`ref-classes-deploy` class as follows::
2058
2059         DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
2060
2061      Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be
2062      deployed into :term:`DEPLOYDIR`, and the class will take care of copying
2063      them into :term:`DEPLOY_DIR_IMAGE`
2064      afterwards.
2065
2066   :term:`DESCRIPTION`
2067      The package description used by package managers. If not set,
2068      :term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
2069      variable.
2070
2071   :term:`DEV_PKG_DEPENDENCY`
2072      Provides an easy way for recipes to disable or adjust the runtime recommendation
2073      (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main
2074      (``${PN}``) package.
2075
2076   :term:`DISABLE_STATIC`
2077      Used in order to disable static linking by default (in order to save
2078      space, since static libraries are often unused in embedded systems.)
2079      The default value is " --disable-static", however it can be set to ""
2080      in order to enable static linking if desired. Certain recipes do this
2081      individually, and also there is a
2082      ``meta/conf/distro/include/no-static-libs.inc`` include file that
2083      disables static linking for a number of recipes. Some software
2084      packages or build tools (such as CMake) have explicit support for
2085      enabling / disabling static linking, and in those cases
2086      :term:`DISABLE_STATIC` is not used.
2087
2088   :term:`DISTRO`
2089      The short name of the distribution. For information on the long name
2090      of the distribution, see the :term:`DISTRO_NAME`
2091      variable.
2092
2093      The :term:`DISTRO` variable corresponds to a distribution configuration
2094      file whose root name is the same as the variable's argument and whose
2095      filename extension is ``.conf``. For example, the distribution
2096      configuration file for the Poky distribution is named ``poky.conf``
2097      and resides in the ``meta-poky/conf/distro`` directory of the
2098      :term:`Source Directory`.
2099
2100      Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
2101      follows::
2102
2103         DISTRO = "poky"
2104
2105      Distribution configuration files are located in a ``conf/distro``
2106      directory within the :term:`Metadata` that contains the
2107      distribution configuration. The value for :term:`DISTRO` must not contain
2108      spaces, and is typically all lower-case.
2109
2110      .. note::
2111
2112         If the :term:`DISTRO` variable is blank, a set of default configurations
2113         are used, which are specified within
2114         ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
2115
2116   :term:`DISTRO_CODENAME`
2117      Specifies a codename for the distribution being built.
2118
2119   :term:`DISTRO_EXTRA_RDEPENDS`
2120      Specifies a list of distro-specific packages to add to all images.
2121      This variable takes effect through ``packagegroup-base`` so the
2122      variable only really applies to the more full-featured images that
2123      include ``packagegroup-base``. You can use this variable to keep
2124      distro policy out of generic images. As with all other distro
2125      variables, you set this variable in the distro ``.conf`` file.
2126
2127   :term:`DISTRO_EXTRA_RRECOMMENDS`
2128      Specifies a list of distro-specific packages to add to all images if
2129      the packages exist. The packages might not exist or be empty (e.g.
2130      kernel modules). The list of packages are automatically installed but
2131      you can remove them.
2132
2133   :term:`DISTRO_FEATURES`
2134      The software support you want in your distribution for various
2135      features. You define your distribution features in the distribution
2136      configuration file.
2137
2138      In most cases, the presence or absence of a feature in
2139      :term:`DISTRO_FEATURES` is translated to the appropriate option supplied
2140      to the configure script during the
2141      :ref:`ref-tasks-configure` task for recipes that
2142      optionally support the feature. For example, specifying "x11" in
2143      :term:`DISTRO_FEATURES`, causes every piece of software built for the
2144      target that can optionally support X11 to have its X11 support
2145      enabled.
2146
2147      .. note::
2148
2149         Just enabling :term:`DISTRO_FEATURES` alone doesn't
2150         enable feature support for packages. Mechanisms such as making
2151         :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used
2152         to enable/disable package features.
2153
2154      Two more examples are Bluetooth and NFS support. For a more complete
2155      list of features that ships with the Yocto Project and that you can
2156      provide with this variable, see the ":ref:`ref-features-distro`" section.
2157
2158   :term:`DISTRO_FEATURES_BACKFILL`
2159      A space-separated list of features to be added to :term:`DISTRO_FEATURES`
2160      if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
2161
2162      This variable is set in the ``meta/conf/bitbake.conf`` file. It is
2163      not intended to be user-configurable. It is best to just reference
2164      the variable to see which distro features are being
2165      :ref:`backfilled <ref-features-backfill>` for all distro configurations.
2166
2167   :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
2168      A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL`
2169      that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
2170      to :term:`DISTRO_FEATURES`) during the build.
2171
2172      This corresponds to an opt-out mechanism. When new default distro
2173      features are introduced, distribution maintainers can review (`consider`)
2174      them and decide to exclude them from the
2175      :ref:`backfilled <ref-features-backfill>` features. Therefore, the
2176      combination of :term:`DISTRO_FEATURES_BACKFILL` and
2177      :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to
2178      add new default features without breaking existing distributions.
2179
2180
2181   :term:`DISTRO_FEATURES_DEFAULT`
2182      A convenience variable that gives you the default list of distro
2183      features with the exception of any features specific to the C library
2184      (``libc``).
2185
2186      When creating a custom distribution, you might find it useful to be
2187      able to reuse the default
2188      :term:`DISTRO_FEATURES` options without the
2189      need to write out the full set. Here is an example that uses
2190      :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
2191
2192         DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
2193
2194   :term:`DISTRO_FEATURES_FILTER_NATIVE`
2195      Specifies a list of features that if present in the target
2196      :term:`DISTRO_FEATURES` value should be
2197      included in :term:`DISTRO_FEATURES` when building native recipes. This
2198      variable is used in addition to the features filtered using the
2199      :term:`DISTRO_FEATURES_NATIVE`
2200      variable.
2201
2202   :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
2203      Specifies a list of features that if present in the target
2204      :term:`DISTRO_FEATURES` value should be included in
2205      :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk`
2206      recipes. This variable is used in addition to the features filtered using
2207      the :term:`DISTRO_FEATURES_NATIVESDK` variable.
2208
2209   :term:`DISTRO_FEATURES_NATIVE`
2210      Specifies a list of features that should be included in
2211      :term:`DISTRO_FEATURES` when building native
2212      recipes. This variable is used in addition to the features filtered
2213      using the
2214      :term:`DISTRO_FEATURES_FILTER_NATIVE`
2215      variable.
2216
2217   :term:`DISTRO_FEATURES_NATIVESDK`
2218      Specifies a list of features that should be included in
2219      :term:`DISTRO_FEATURES` when building
2220      :ref:`ref-classes-nativesdk` recipes. This variable is used
2221      in addition to the features filtered using the
2222      :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable.
2223
2224   :term:`DISTRO_NAME`
2225      The long name of the distribution. For information on the short name
2226      of the distribution, see the :term:`DISTRO` variable.
2227
2228      The :term:`DISTRO_NAME` variable corresponds to a distribution
2229      configuration file whose root name is the same as the variable's
2230      argument and whose filename extension is ``.conf``. For example, the
2231      distribution configuration file for the Poky distribution is named
2232      ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
2233      of the :term:`Source Directory`.
2234
2235      Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
2236      as follows::
2237
2238         DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
2239
2240      Distribution configuration files are located in a ``conf/distro``
2241      directory within the :term:`Metadata` that contains the
2242      distribution configuration.
2243
2244      .. note::
2245
2246         If the :term:`DISTRO_NAME` variable is blank, a set of default
2247         configurations are used, which are specified within
2248         ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
2249
2250   :term:`DISTRO_VERSION`
2251      The version of the distribution.
2252
2253   :term:`DISTROOVERRIDES`
2254      A colon-separated list of overrides specific to the current
2255      distribution. By default, this list includes the value of
2256      :term:`DISTRO`.
2257
2258      You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
2259      apply to the distribution.
2260
2261      The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
2262      is included in the default value of
2263      :term:`OVERRIDES`.
2264
2265      Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf
2266      </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`::
2267
2268         DISTROOVERRIDES = "poky:poky-tiny"
2269
2270   :term:`DL_DIR`
2271      The central download directory used by the build process to store
2272      downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
2273      for everything except Git repositories. If you want tarballs of Git
2274      repositories, use the
2275      :term:`BB_GENERATE_MIRROR_TARBALLS`
2276      variable.
2277
2278      You can set this directory by defining the :term:`DL_DIR` variable in the
2279      ``conf/local.conf`` file. This directory is self-maintaining and you
2280      should not have to touch it. By default, the directory is
2281      ``downloads`` in the :term:`Build Directory`::
2282
2283         #DL_DIR ?= "${TOPDIR}/downloads"
2284
2285      To specify a different download directory,
2286      simply remove the comment from the line and provide your directory.
2287
2288      During a first build, the system downloads many different source code
2289      tarballs from various upstream projects. Downloading can take a
2290      while, particularly if your network connection is slow. Tarballs are
2291      all stored in the directory defined by :term:`DL_DIR` and the build
2292      system looks there first to find source tarballs.
2293
2294      .. note::
2295
2296         When wiping and rebuilding, you can preserve this directory to
2297         speed up this part of subsequent builds.
2298
2299      You can safely share this directory between multiple builds on the
2300      same development machine. For additional information on how the build
2301      process gets source files when working behind a firewall or proxy
2302      server, see this specific question in the ":doc:`faq`"
2303      chapter. You can also refer to the
2304      ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
2305      Wiki page.
2306
2307   :term:`DOC_COMPRESS`
2308      When inheriting the :ref:`ref-classes-compress_doc`
2309      class, this variable sets the compression policy used when the
2310      OpenEmbedded build system compresses manual and info pages. By
2311      default, the compression method used is gz (gzip). Other policies
2312      available are xz and bz2.
2313
2314      For information on policies and on how to use this variable, see the
2315      comments in the ``meta/classes-recipe/compress_doc.bbclass`` file.
2316
2317   :term:`DT_FILES`
2318      Space-separated list of device tree source files to compile using
2319      a recipe that inherits the :ref:`ref-classes-devicetree` class. These
2320      are relative to the :term:`DT_FILES_PATH`.
2321
2322      For convenience, both ``.dts`` and ``.dtb`` extensions can be used.
2323
2324      Use an empty string (default) to build all device tree sources within
2325      the :term:`DT_FILES_PATH` directory.
2326
2327   :term:`DT_FILES_PATH`
2328      When compiling out-of-tree device tree sources using a recipe that
2329      inherits the :ref:`ref-classes-devicetree` class, this variable specifies
2330      the path to the directory containing dts files to build.
2331
2332      Defaults to the :term:`S` directory.
2333
2334   :term:`DT_PADDING_SIZE`
2335      When inheriting the :ref:`ref-classes-devicetree` class, this variable
2336      specifies the size of padding appended to the device tree blob, used as
2337      extra space typically for additional properties during boot.
2338
2339   :term:`EFI_PROVIDER`
2340      When building bootable images (i.e. where ``hddimg``, ``iso``, or
2341      ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
2342      :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
2343      default is "grub-efi", but "systemd-boot" can be used instead.
2344
2345      See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live`
2346      classes for more information.
2347
2348   :term:`EFI_UKI_DIR`
2349      The primary place for the UKI image inside the EFI System Partition.
2350
2351   :term:`EFI_UKI_PATH`
2352      The path for the UKI image inside the root filesystem.
2353
2354   :term:`ENABLE_BINARY_LOCALE_GENERATION`
2355      Variable that controls which locales for ``glibc`` are generated
2356      during the build (useful if the target device has 64Mbytes of RAM or
2357      less).
2358
2359   :term:`ERR_REPORT_DIR`
2360      When used with the :ref:`ref-classes-report-error` class, specifies the
2361      path used for storing the debug files created by the :ref:`error reporting
2362      tool <dev-manual/error-reporting-tool:using the error reporting tool>`,
2363      which allows you to submit build errors you encounter to a central
2364      database. By default, the value of this variable is
2365      ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2366
2367      You can set :term:`ERR_REPORT_DIR` to the path you want the error
2368      reporting tool to store the debug files as follows in your
2369      ``local.conf`` file::
2370
2371         ERR_REPORT_DIR = "path"
2372
2373   :term:`ERROR_QA`
2374      Specifies the quality assurance checks whose failures are reported as
2375      errors by the OpenEmbedded build system. You set this variable in
2376      your distribution configuration file. For a list of the checks you
2377      can control with this variable, see the
2378      ":ref:`ref-classes-insane`" section.
2379
2380   :term:`ESDK_CLASS_INHERIT_DISABLE`
2381      A list of classes to remove from the :term:`INHERIT`
2382      value globally within the extensible SDK configuration. The
2383      :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
2384      default value::
2385
2386         ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc"
2387
2388      Some classes are not generally applicable within the extensible SDK
2389      context. You can use this variable to disable those classes.
2390
2391      For additional information on how to customize the extensible SDK's
2392      configuration, see the
2393      ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2394      section in the Yocto Project Application Development and the
2395      Extensible Software Development Kit (eSDK) manual.
2396
2397   :term:`ESDK_LOCALCONF_ALLOW`
2398      A list of variables allowed through from the OpenEmbedded build
2399      system configuration into the extensible SDK configuration. By
2400      default, the list of variables is empty and is set in the
2401      :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
2402
2403      This list overrides the variables specified using the
2404      :term:`ESDK_LOCALCONF_REMOVE` variable as well as
2405      other variables automatically added due to the "/" character
2406      being found at the start of the
2407      value, which is usually indicative of being a path and thus might not
2408      be valid on the system where the SDK is installed.
2409
2410      For additional information on how to customize the extensible SDK's
2411      configuration, see the
2412      ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2413      section in the Yocto Project Application Development and the
2414      Extensible Software Development Kit (eSDK) manual.
2415
2416   :term:`ESDK_LOCALCONF_REMOVE`
2417      A list of variables not allowed through from the OpenEmbedded build
2418      system configuration into the extensible SDK configuration. Usually,
2419      these are variables that are specific to the machine on which the
2420      build system is running and thus would be potentially problematic
2421      within the extensible SDK.
2422
2423      By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the
2424      :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
2425      excludes the following variables:
2426
2427      - :term:`CONF_VERSION`
2428      - :term:`BB_NUMBER_THREADS`
2429      - :term:`BB_NUMBER_PARSE_THREADS`
2430      - :term:`PARALLEL_MAKE`
2431      - :term:`PRSERV_HOST`
2432      - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
2433      - :term:`SSTATE_DIR` :term:`TMPDIR`
2434      - :term:`BB_SERVER_TIMEOUT`
2435
2436      For additional information on how to customize the extensible SDK's
2437      configuration, see the
2438      ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2439      section in the Yocto Project Application Development and the
2440      Extensible Software Development Kit (eSDK) manual.
2441
2442   :term:`EXCLUDE_FROM_SHLIBS`
2443      Triggers the OpenEmbedded build system's shared libraries resolver to
2444      exclude an entire package when scanning for shared libraries.
2445
2446      .. note::
2447
2448         The shared libraries resolver's functionality results in part from
2449         the internal function ``package_do_shlibs``, which is part of the
2450         :ref:`ref-tasks-package` task. You should be aware that the shared
2451         libraries resolver might implicitly define some dependencies between
2452         packages.
2453
2454      The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
2455      :term:`PRIVATE_LIBS` variable, which excludes a
2456      package's particular libraries only and not the whole package.
2457
2458      Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
2459      particular package::
2460
2461         EXCLUDE_FROM_SHLIBS = "1"
2462
2463   :term:`EXCLUDE_FROM_WORLD`
2464      Directs BitBake to exclude a recipe from world builds (i.e.
2465      ``bitbake world``). During world builds, BitBake locates, parses and
2466      builds all recipes found in every layer exposed in the
2467      ``bblayers.conf`` configuration file.
2468
2469      To exclude a recipe from a world build using this variable, set the
2470      variable to "1" in the recipe.
2471
2472      .. note::
2473
2474         Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
2475         world build in order to satisfy dependencies of other recipes. Adding
2476         a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
2477         explicitly added to the list of build targets in a world build.
2478
2479   :term:`EXTENDPE`
2480      Used with file and pathnames to create a prefix for a recipe's
2481      version based on the recipe's :term:`PE` value. If :term:`PE`
2482      is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
2483      value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
2484      If a recipe's :term:`PE` is not set (the default) or is equal to zero,
2485      :term:`EXTENDPE` becomes "".
2486
2487      See the :term:`STAMP` variable for an example.
2488
2489   :term:`EXTENDPKGV`
2490      The full package version specification as it appears on the final
2491      packages produced by a recipe. The variable's value is normally used
2492      to fix a runtime dependency to the exact same version of another
2493      package in the same recipe::
2494
2495         RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2496
2497      The dependency relationships are intended to force the package
2498      manager to upgrade these types of packages in lock-step.
2499
2500   :term:`EXTERNAL_KERNEL_TOOLS`
2501      When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
2502      tools are not in the source tree.
2503
2504      When kernel tools are available in the tree, they are preferred over
2505      any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
2506      variable tells the OpenEmbedded build system to prefer the installed
2507      external tools. See the :ref:`ref-classes-kernel-yocto` class in
2508      ``meta/classes-recipe`` to see how the variable is used.
2509
2510   :term:`KERNEL_LOCALVERSION`
2511      This variable allows to append a string to the version
2512      of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION``
2513      kernel configuration parameter.
2514
2515      Using this variable is only useful when you are using a kernel recipe
2516      inheriting the :ref:`ref-classes-kernel` class, and which doesn't
2517      already set a local version. Therefore, setting this variable has no
2518      impact on ``linux-yocto`` kernels.
2519
2520   :term:`EXTERNAL_TOOLCHAIN`
2521      When you intend to use an
2522      :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`,
2523      this variable allows to specify the directory where this toolchain was
2524      installed.
2525
2526   :term:`EXTERNALSRC`
2527      When inheriting the :ref:`ref-classes-externalsrc`
2528      class, this variable points to the source tree, which is outside of
2529      the OpenEmbedded build system. When set, this variable sets the
2530      :term:`S` variable, which is what the OpenEmbedded build
2531      system uses to locate unpacked recipe source code.
2532
2533      See the ":ref:`ref-classes-externalsrc`" section for details. You
2534      can also find information on how to use this variable in the
2535      ":ref:`dev-manual/building:building software from an external source`"
2536      section in the Yocto Project Development Tasks Manual.
2537
2538   :term:`EXTERNALSRC_BUILD`
2539      When inheriting the :ref:`ref-classes-externalsrc`
2540      class, this variable points to the directory in which the recipe's
2541      source code is built, which is outside of the OpenEmbedded build
2542      system. When set, this variable sets the :term:`B` variable,
2543      which is what the OpenEmbedded build system uses to locate the
2544      :term:`Build Directory`.
2545
2546      See the ":ref:`ref-classes-externalsrc`" section for details. You
2547      can also find information on how to use this variable in the
2548      ":ref:`dev-manual/building:building software from an external source`"
2549      section in the Yocto Project Development Tasks Manual.
2550
2551   :term:`EXTRA_AUTORECONF`
2552      For recipes inheriting the :ref:`ref-classes-autotools`
2553      class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
2554      pass to the ``autoreconf`` command that is executed during the
2555      :ref:`ref-tasks-configure` task.
2556
2557      The default value is "--exclude=autopoint".
2558
2559   :term:`EXTRA_IMAGE_FEATURES`
2560      A list of additional features to include in an image. When listing
2561      more than one feature, separate them with a space.
2562
2563      Typically, you configure this variable in your ``local.conf`` file,
2564      which is found in the :term:`Build Directory`. Although you can use this
2565      variable from within a recipe, best practices dictate that you do not.
2566
2567      .. note::
2568
2569         To enable primary features from within the image recipe, use the
2570         :term:`IMAGE_FEATURES` variable.
2571
2572      Here are some examples of features you can add:
2573
2574        - "dbg-pkgs" --- adds -dbg packages for all installed packages including
2575          symbol information for debugging and profiling.
2576
2577        - "debug-tweaks" --- makes an image suitable for debugging. For example, allows root logins without passwords and
2578          enables post-installation logging. See the 'allow-empty-password' and
2579          'post-install-logging' features in the ":ref:`ref-features-image`"
2580          section for more information.
2581        - "dev-pkgs" --- adds -dev packages for all installed packages. This is
2582          useful if you want to develop against the libraries in the image.
2583        - "read-only-rootfs" --- creates an image whose root filesystem is
2584          read-only. See the
2585          ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`"
2586          section in the Yocto Project Development Tasks Manual for more
2587          information
2588        - "tools-debug" --- adds debugging tools such as gdb and strace.
2589        - "tools-sdk" --- adds development tools such as gcc, make,
2590          pkgconfig and so forth.
2591        - "tools-testapps" --- adds useful testing tools
2592          such as ts_print, aplay, arecord and so forth.
2593
2594      For a complete list of image features that ships with the Yocto
2595      Project, see the ":ref:`ref-features-image`" section.
2596
2597      For an example that shows how to customize your image by using this
2598      variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
2599      section in the Yocto Project Development Tasks Manual.
2600
2601   :term:`EXTRA_IMAGECMD`
2602      Specifies additional options for the image creation command that has
2603      been specified in :term:`IMAGE_CMD`. When setting
2604      this variable, use an override for the associated image type. Here is
2605      an example::
2606
2607         EXTRA_IMAGECMD:ext3 ?= "-i 4096"
2608
2609   :term:`EXTRA_IMAGEDEPENDS`
2610      A list of recipes to build that do not provide packages for
2611      installing into the root filesystem.
2612
2613      Sometimes a recipe is required to build the final image but is not
2614      needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
2615      variable to list these recipes and thus specify the dependencies. A
2616      typical example is a required bootloader in a machine configuration.
2617
2618      .. note::
2619
2620         To add packages to the root filesystem, see the various
2621         :term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
2622
2623   :term:`EXTRA_OECMAKE`
2624      Additional `CMake <https://cmake.org/overview/>`__ options. See the
2625      :ref:`ref-classes-cmake` class for additional information.
2626
2627   :term:`EXTRA_OECONF`
2628      Additional ``configure`` script options. See
2629      :term:`PACKAGECONFIG_CONFARGS` for
2630      additional information on passing configure script options.
2631
2632   :term:`EXTRA_OEMAKE`
2633      Additional GNU ``make`` options.
2634
2635      Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
2636      variable to specify any required GNU options.
2637
2638      :term:`PARALLEL_MAKE` and
2639      :term:`PARALLEL_MAKEINST` also make use of
2640      :term:`EXTRA_OEMAKE` to pass the required flags.
2641
2642   :term:`EXTRA_OESCONS`
2643      When inheriting the :ref:`ref-classes-scons` class, this
2644      variable specifies additional configuration options you want to pass
2645      to the ``scons`` command line.
2646
2647   :term:`EXTRA_OEMESON`
2648      Additional `Meson <https://mesonbuild.com/>`__ options. See the
2649      :ref:`ref-classes-meson` class for additional information.
2650
2651      In addition to standard Meson options, such options correspond to
2652      `Meson build options <https://mesonbuild.com/Build-options.html>`__
2653      defined in the ``meson_options.txt`` file in the sources to build.
2654      Here is an example::
2655
2656         EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled"
2657
2658      Note that any custom value for the Meson ``--buildtype`` option
2659      should be set through the :term:`MESON_BUILDTYPE` variable.
2660
2661   :term:`EXTRA_USERS_PARAMS`
2662      When inheriting the :ref:`ref-classes-extrausers`
2663      class, this variable provides image level user and group operations.
2664      This is a more global method of providing user and group
2665      configuration as compared to using the
2666      :ref:`ref-classes-useradd` class, which ties user and
2667      group configurations to a specific recipe.
2668
2669      The set list of commands you can configure using the
2670      :term:`EXTRA_USERS_PARAMS` is shown in the
2671      :ref:`ref-classes-extrausers` class. These commands map to the normal
2672      Unix commands of the same names::
2673
2674         # EXTRA_USERS_PARAMS = "\
2675         # useradd -p '' tester; \
2676         # groupadd developers; \
2677         # userdel nobody; \
2678         # groupdel -g video; \
2679         # groupmod -g 1020 developers; \
2680         # usermod -s /bin/sh tester; \
2681         # "
2682
2683      Hardcoded passwords are supported via the ``-p`` parameters for
2684      ``useradd`` or ``usermod``, but only hashed.
2685
2686      Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
2687      passwords. First on host, create the (escaped) password hash::
2688
2689         printf "%q" $(mkpasswd -m sha256crypt tester01)
2690
2691      The resulting hash is set to a variable and used in ``useradd`` command parameters::
2692
2693         inherit extrausers
2694         PASSWD = "\$X\$ABC123\$A-Long-Hash"
2695         EXTRA_USERS_PARAMS = "\
2696             useradd -p '${PASSWD}' tester-jim; \
2697             useradd -p '${PASSWD}' tester-sue; \
2698             "
2699
2700      Finally, here is an example that sets the root password::
2701
2702         inherit extrausers
2703         EXTRA_USERS_PARAMS = "\
2704             usermod -p '${PASSWD}' root; \
2705             "
2706
2707      .. note::
2708
2709         From a security perspective, hardcoding a default password is not
2710         generally a good idea or even legal in some jurisdictions. It is
2711         recommended that you do not do this if you are building a production
2712         image.
2713
2714      Additionally there is a special ``passwd-expire`` command that will
2715      cause the password for a user to be expired and thus force changing it
2716      on first login, for example::
2717
2718         EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
2719
2720      .. note::
2721
2722         At present, ``passwd-expire`` may only work for remote logins when
2723         using OpenSSH and not dropbear as an SSH server.
2724
2725   :term:`EXTRANATIVEPATH`
2726      A list of subdirectories of
2727      ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2728      added to the beginning of the environment variable ``PATH``. As an
2729      example, the following prepends
2730      "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2731      ``PATH``::
2732
2733         EXTRANATIVEPATH = "foo bar"
2734
2735   :term:`FAKEROOT`
2736      See :term:`bitbake:FAKEROOT` in the BitBake manual.
2737
2738   :term:`FAKEROOTBASEENV`
2739      See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual.
2740
2741   :term:`FAKEROOTCMD`
2742      See :term:`bitbake:FAKEROOTCMD` in the BitBake manual.
2743
2744   :term:`FAKEROOTDIRS`
2745      See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual.
2746
2747   :term:`FAKEROOTENV`
2748      See :term:`bitbake:FAKEROOTENV` in the BitBake manual.
2749
2750   :term:`FAKEROOTNOENV`
2751      See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual.
2752
2753   :term:`FEATURE_PACKAGES`
2754      Defines one or more packages to include in an image when a specific
2755      item is included in :term:`IMAGE_FEATURES`.
2756      When setting the value, :term:`FEATURE_PACKAGES` should have the name of
2757      the feature item as an override. Here is an example::
2758
2759         FEATURE_PACKAGES_widget = "package1 package2"
2760
2761      In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
2762      package1 and package2 would be included in the image.
2763
2764      .. note::
2765
2766         Packages installed by features defined through :term:`FEATURE_PACKAGES`
2767         are often package groups. While similarly named, you should not
2768         confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
2769         are discussed elsewhere in the documentation.
2770
2771   :term:`FEED_DEPLOYDIR_BASE_URI`
2772      Points to the base URL of the server and location within the
2773      document-root that provides the metadata and packages required by
2774      OPKG to support runtime package management of IPK packages. You set
2775      this variable in your ``local.conf`` file.
2776
2777      Consider the following example::
2778
2779         FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2780
2781      This example assumes you are serving
2782      your packages over HTTP and your databases are located in a directory
2783      named ``BOARD-dir``, which is underneath your HTTP server's
2784      document-root. In this case, the OpenEmbedded build system generates
2785      a set of configuration files for you in your target that work with
2786      the feed.
2787
2788   :term:`FETCHCMD`
2789      See :term:`bitbake:FETCHCMD` in the BitBake manual.
2790
2791   :term:`FILE`
2792      See :term:`bitbake:FILE` in the BitBake manual.
2793
2794   :term:`FILES`
2795      The list of files and directories that are placed in a package. The
2796      :term:`PACKAGES` variable lists the packages
2797      generated by a recipe.
2798
2799      To use the :term:`FILES` variable, provide a package name override that
2800      identifies the resulting package. Then, provide a space-separated
2801      list of files or paths that identify the files you want included as
2802      part of the resulting package. Here is an example::
2803
2804         FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
2805
2806      .. note::
2807
2808         -  When specifying files or paths, you can pattern match using
2809            Python's
2810            `glob <https://docs.python.org/3/library/glob.html>`__
2811            syntax. For details on the syntax, see the documentation by
2812            following the previous link.
2813
2814         -  When specifying paths as part of the :term:`FILES` variable, it is
2815            good practice to use appropriate path variables. For example,
2816            use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2817            rather than ``/usr/bin``. You can find a list of these
2818            variables at the top of the ``meta/conf/bitbake.conf`` file in
2819            the :term:`Source Directory`. You will also
2820            find the default values of the various ``FILES:*`` variables in
2821            this file.
2822
2823      If some of the files you provide with the :term:`FILES` variable are
2824      editable and you know they should not be overwritten during the
2825      package update process by the Package Management System (PMS), you
2826      can identify these files so that the PMS will not overwrite them. See
2827      the :term:`CONFFILES` variable for information on
2828      how to identify these files to the PMS.
2829
2830   :term:`FILES_SOLIBSDEV`
2831      Defines the file specification to match
2832      :term:`SOLIBSDEV`. In other words,
2833      :term:`FILES_SOLIBSDEV` defines the full path name of the development
2834      symbolic link (symlink) for shared libraries on the target platform.
2835
2836      The following statement from the ``bitbake.conf`` shows how it is
2837      set::
2838
2839         FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2840
2841   :term:`FILESEXTRAPATHS`
2842      A colon-separated list to extend the search path the OpenEmbedded build
2843      system uses when looking for files and patches as it processes recipes
2844      and append files. The default directories BitBake uses when it processes
2845      recipes are initially defined by the :term:`FILESPATH` variable. You can
2846      extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`.
2847
2848      Best practices dictate that you accomplish this by using
2849      :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
2850      prepend paths as follows::
2851
2852         FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
2853
2854      In the above example, the build system first
2855      looks for files in a directory that has the same name as the
2856      corresponding append file.
2857
2858      .. note::
2859
2860         When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
2861         expansion (``:=``) operator. Immediate expansion makes sure that
2862         BitBake evaluates :term:`THISDIR` at the time the
2863         directive is encountered rather than at some later time when
2864         expansion might result in a directory that does not contain the
2865         files you need.
2866
2867         Also, include the trailing separating colon character if you are
2868         prepending. The trailing colon character is necessary because you
2869         are directing BitBake to extend the path by prepending directories
2870         to the search path.
2871
2872      Here is another common use::
2873
2874         FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
2875
2876      In this example, the build system extends the
2877      :term:`FILESPATH` variable to include a directory named ``files`` that is
2878      in the same directory as the corresponding append file.
2879
2880      This next example specifically adds three paths::
2881
2882         FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
2883
2884      A final example shows how you can extend the search path and include
2885      a :term:`MACHINE`-specific override, which is useful
2886      in a BSP layer::
2887
2888          FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
2889
2890      The previous statement appears in the
2891      ``linux-yocto-dev.bbappend`` file, which is found in the
2892      :ref:`overview-manual/development-environment:yocto project source repositories` in
2893      ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2894      override is a special :term:`PACKAGE_ARCH`
2895      definition for multiple ``meta-intel`` machines.
2896
2897      .. note::
2898
2899         For a layer that supports a single BSP, the override could just be
2900         the value of :term:`MACHINE`.
2901
2902      By prepending paths in ``.bbappend`` files, you allow multiple append
2903      files that reside in different layers but are used for the same
2904      recipe to correctly extend the path.
2905
2906   :term:`FILESOVERRIDES`
2907      A colon-separated list to specify a subset of :term:`OVERRIDES` used by
2908      the OpenEmbedded build system for creating :term:`FILESPATH`. The
2909      :term:`FILESOVERRIDES` variable uses overrides to automatically extend
2910      the :term:`FILESPATH` variable. For an example of how that works, see the
2911      :term:`FILESPATH` variable description. Additionally, you find more
2912      information on how overrides are handled in the
2913      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2914      section of the BitBake User Manual.
2915
2916      By default, the :term:`FILESOVERRIDES` variable is defined as::
2917
2918         FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2919
2920      .. note::
2921
2922         Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
2923         with expected overrides and are used in an expected manner by the
2924         build system.
2925
2926   :term:`FILESPATH`
2927      A colon-separated list specifying the default set of directories the
2928      OpenEmbedded build system uses when searching for patches and files.
2929
2930      During the build process, BitBake searches each directory in
2931      :term:`FILESPATH` in the specified order when looking for files and
2932      patches specified by each ``file://`` URI in a recipe's
2933      :term:`SRC_URI` statements.
2934
2935      The default value for the :term:`FILESPATH` variable is defined in the
2936      :ref:`ref-classes-base` class found in ``meta/classes-global`` in the
2937      :term:`Source Directory`::
2938
2939         FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2940             "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2941
2942      The
2943      :term:`FILESPATH` variable is automatically extended using the overrides
2944      from the :term:`FILESOVERRIDES` variable.
2945
2946      .. note::
2947
2948         -  Do not hand-edit the :term:`FILESPATH` variable. If you want the
2949            build system to look in directories other than the defaults,
2950            extend the :term:`FILESPATH` variable by using the
2951            :term:`FILESEXTRAPATHS` variable.
2952
2953         -  Be aware that the default :term:`FILESPATH` directories do not map
2954            to directories in custom layers where append files
2955            (``.bbappend``) are used. If you want the build system to find
2956            patches or files that reside with your append files, you need
2957            to extend the :term:`FILESPATH` variable by using the
2958            :term:`FILESEXTRAPATHS` variable.
2959
2960      You can take advantage of this searching behavior in useful ways. For
2961      example, consider a case where there is the following directory structure
2962      for general and machine-specific configurations::
2963
2964         files/defconfig
2965         files/MACHINEA/defconfig
2966         files/MACHINEB/defconfig
2967
2968      Also in the example, the :term:`SRC_URI` statement contains
2969      "file://defconfig". Given this scenario, you can set
2970      :term:`MACHINE` to "MACHINEA" and cause the build
2971      system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
2972      "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2973      Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2974      build system uses files from ``files/defconfig``.
2975
2976      You can find out more about the patching process in the
2977      ":ref:`overview-manual/concepts:patching`" section
2978      in the Yocto Project Overview and Concepts Manual and the
2979      ":ref:`dev-manual/new-recipe:patching code`" section in
2980      the Yocto Project Development Tasks Manual. See the
2981      :ref:`ref-tasks-patch` task as well.
2982
2983   :term:`FILESYSTEM_PERMS_TABLES`
2984      Allows you to define your own file permissions settings table as part
2985      of your configuration for the packaging process. For example, suppose
2986      you need a consistent set of custom permissions for a set of groups
2987      and users across an entire work project. It is best to do this in the
2988      packages themselves but this is not always possible.
2989
2990      By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2991      which is located in the ``meta/files`` folder in the :term:`Source Directory`.
2992      If you create your own file
2993      permissions setting table, you should place it in your layer or the
2994      distro's layer.
2995
2996      You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
2997      ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2998      to point to your custom ``fs-perms.txt``. You can specify more than a
2999      single file permissions setting table. The paths you specify to these
3000      files must be defined within the :term:`BBPATH` variable.
3001
3002      For guidance on how to create your own file permissions settings
3003      table file, examine the existing ``fs-perms.txt``.
3004
3005   :term:`FIT_ADDRESS_CELLS`
3006      Specifies the value of the ``#address-cells`` value for the
3007      description of the FIT image.
3008
3009      The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage`
3010      class, which corresponds to 32 bit addresses.
3011
3012      For platforms that need to set 64 bit addresses, for example in
3013      :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
3014      set this value to "2", as two 32 bit values (cells) will be needed
3015      to represent such addresses.
3016
3017      Here is an example setting "0x400000000" as a load address::
3018
3019         FIT_ADDRESS_CELLS = "2"
3020         UBOOT_LOADADDRESS= "0x04 0x00000000"
3021
3022      See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
3023
3024   :term:`FIT_CONF_DEFAULT_DTB`
3025      Specifies the default device tree binary (dtb) file for a FIT image
3026      when multiple ones are provided.
3027
3028      This variable is used in the :ref:`ref-classes-kernel-fitimage` class.
3029
3030   :term:`FIT_DESC`
3031      Specifies the description string encoded into a FIT image. The
3032      default value is set by the :ref:`ref-classes-kernel-fitimage` class as
3033      follows::
3034
3035         FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
3036
3037   :term:`FIT_GENERATE_KEYS`
3038      Decides whether to generate the keys for signing the FIT image if
3039      they don't already exist. The keys are created in
3040      :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0"
3041      by the :ref:`ref-classes-kernel-fitimage` class.
3042
3043   :term:`FIT_HASH_ALG`
3044      Specifies the hash algorithm used in creating the FIT Image.
3045      This variable is set by default to "sha256" by the
3046      :ref:`ref-classes-kernel-fitimage` class.
3047
3048   :term:`FIT_KERNEL_COMP_ALG`
3049      The compression algorithm to use for the kernel image inside the FIT Image.
3050      At present, the only supported values are "gzip" (default), "lzo" or "none".
3051      If you set this variable to anything other than "none" you may also need
3052      to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
3053
3054      This variable is used in the :ref:`ref-classes-kernel-uboot` class.
3055
3056   :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
3057      File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
3058      value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you
3059      set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this
3060      variable to ".lzo".
3061
3062   :term:`FIT_KEY_GENRSA_ARGS`
3063      Arguments to ``openssl genrsa`` for generating a RSA private key for
3064      signing the FIT image. The default value is set to "-F4" by the
3065      :ref:`ref-classes-kernel-fitimage` class.
3066
3067   :term:`FIT_KEY_REQ_ARGS`
3068      Arguments to ``openssl req`` for generating a certificate for signing
3069      the FIT image. The default value is "-batch -new" by the
3070      :ref:`ref-classes-kernel-fitimage` class, "batch" for
3071      non interactive mode and "new" for generating new keys.
3072
3073   :term:`FIT_KEY_SIGN_PKCS`
3074      Format for the public key certificate used for signing the FIT image.
3075      The default value is set to "x509" by the
3076      :ref:`ref-classes-kernel-fitimage` class.
3077
3078   :term:`FIT_SIGN_ALG`
3079      Specifies the signature algorithm used in creating the FIT Image.
3080      This variable is set by default to "rsa2048" by the
3081      :ref:`ref-classes-kernel-fitimage` class.
3082
3083   :term:`FIT_PAD_ALG`
3084      Specifies the padding algorithm used in creating the FIT Image.
3085      The default value is set to "pkcs-1.5" by the
3086      :ref:`ref-classes-kernel-fitimage` class.
3087
3088   :term:`FIT_SIGN_INDIVIDUAL`
3089      If set to "1", then the :ref:`ref-classes-kernel-fitimage`
3090      class will sign the kernel, dtb and ramdisk images individually in addition
3091      to signing the FIT image itself. This could be useful if you are
3092      intending to verify signatures in another context than booting via
3093      U-Boot.
3094
3095      This variable is set to "0" by default.
3096
3097   :term:`FIT_SIGN_NUMBITS`
3098      Size of the private key used in the FIT image, in number of bits.
3099      The default value for this variable is set to "2048"
3100      by the :ref:`ref-classes-kernel-fitimage` class.
3101
3102   :term:`FONT_EXTRA_RDEPENDS`
3103      When inheriting the :ref:`ref-classes-fontcache` class,
3104      this variable specifies the runtime dependencies for font packages.
3105      By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
3106
3107   :term:`FONT_PACKAGES`
3108      When inheriting the :ref:`ref-classes-fontcache` class, this variable
3109      identifies packages containing font files that need to be cached by
3110      Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes
3111      that fonts are in the recipe's main package (i.e.
3112      ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
3113      need are in a package other than that main package.
3114
3115   :term:`FORCE_RO_REMOVE`
3116      Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
3117      during the generation of the root filesystem.
3118
3119      Set the variable to "1" to force the removal of these packages.
3120
3121   :term:`FULL_OPTIMIZATION`
3122      The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
3123      compiling an optimized system. This variable defaults to "-O2 -pipe
3124      ${DEBUG_FLAGS}".
3125
3126   :term:`GCCPIE`
3127      Enables Position Independent Executables (PIE) within the GNU C
3128      Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
3129      Programming (ROP) attacks much more difficult to execute.
3130
3131      By default the ``security_flags.inc`` file enables PIE by setting the
3132      variable as follows::
3133
3134         GCCPIE ?= "--enable-default-pie"
3135
3136   :term:`GCCVERSION`
3137      Specifies the default version of the GNU C Compiler (GCC) used for
3138      compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
3139      ``meta/conf/distro/include/tcmode-default.inc`` include file::
3140
3141         GCCVERSION ?= "8.%"
3142
3143      You can override this value by setting it in a
3144      configuration file such as the ``local.conf``.
3145
3146   :term:`GDB`
3147      The minimal command and arguments to run the GNU Debugger.
3148
3149   :term:`GIR_EXTRA_LIBS_PATH`
3150      Allows to specify an extra search path for ``.so`` files
3151      in GLib related recipes using GObject introspection,
3152      and which do not compile without this setting.
3153      See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`"
3154      section for details.
3155
3156   :term:`GITDIR`
3157      The directory in which a local copy of a Git repository is stored
3158      when it is cloned.
3159
3160   :term:`GITHUB_BASE_URI`
3161      When inheriting the :ref:`ref-classes-github-releases`
3162      class, specifies the base URL for fetching releases for the github
3163      project you wish to fetch sources from. The default value is as follows::
3164
3165         GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/"
3166
3167   :term:`GLIBC_GENERATE_LOCALES`
3168      Specifies the list of GLIBC locales to generate should you not wish
3169      to generate all LIBC locals, which can be time consuming.
3170
3171      .. note::
3172
3173         If you specifically remove the locale ``en_US.UTF-8``, you must set
3174         :term:`IMAGE_LINGUAS` appropriately.
3175
3176      You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
3177      By default, all locales are generated::
3178
3179         GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
3180
3181   :term:`GO_IMPORT`
3182      When inheriting the :ref:`ref-classes-go` class, this mandatory variable
3183      sets the import path for the Go package that will be created for the code
3184      to build. If you have a ``go.mod`` file in the source directory, this
3185      typically matches the path in the ``module`` line in this file.
3186
3187      Other Go programs importing this package will use this path.
3188
3189      Here is an example setting from the
3190      :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
3191      recipe::
3192
3193          GO_IMPORT = "golang.org/x/example"
3194
3195   :term:`GO_INSTALL`
3196      When inheriting the :ref:`ref-classes-go` class, this optional variable
3197      specifies which packages in the sources should be compiled and
3198      installed in the Go build space by the
3199      `go install <https://go.dev/ref/mod#go-install>`__ command.
3200
3201      Here is an example setting from the
3202      :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>`
3203      recipe::
3204
3205         GO_INSTALL = "\
3206             ${GO_IMPORT}/cmd/crucible \
3207             ${GO_IMPORT}/cmd/habtool \
3208         "
3209
3210      By default, :term:`GO_INSTALL` is defined as::
3211
3212         GO_INSTALL ?= "${GO_IMPORT}/..."
3213
3214      The ``...`` wildcard means that it will catch all
3215      packages found in the sources.
3216
3217      See the :term:`GO_INSTALL_FILTEROUT` variable for
3218      filtering out unwanted packages from the ones
3219      found from the :term:`GO_INSTALL` value.
3220
3221   :term:`GO_INSTALL_FILTEROUT`
3222      When using the Go "vendor" mechanism to bring in dependencies for a Go
3223      package, the default :term:`GO_INSTALL` setting, which uses the ``...``
3224      wildcard, will include the vendored packages in the build, which produces
3225      incorrect results.
3226
3227      There are also some Go packages that are structured poorly, so that the
3228      ``...`` wildcard results in building example or test code that should not
3229      be included in the build, or could fail to build.
3230
3231      This optional variable allows for filtering out a subset of the sources.
3232      It defaults to excluding everything under the ``vendor`` subdirectory
3233      under package's main directory. This is the normal location for vendored
3234      packages, but it can be overridden by a recipe to filter out other
3235      subdirectories if needed.
3236
3237   :term:`GO_WORKDIR`
3238      When using Go Modules, the current working directory must be the directory
3239      containing the ``go.mod`` file, or one of its subdirectories. When the
3240      ``go`` tool is used, it will automatically look for the ``go.mod`` file
3241      in the Go working directory or in any parent directory, but not in
3242      subdirectories.
3243
3244      When using the :ref:`ref-classes-go-mod` class to use Go modules,
3245      the optional :term:`GO_WORKDIR` variable, defaulting to the value
3246      of :term:`GO_IMPORT`, allows to specify a different Go working directory.
3247
3248   :term:`GROUPADD_PARAM`
3249      When inheriting the :ref:`ref-classes-useradd` class,
3250      this variable specifies for a package what parameters should be
3251      passed to the ``groupadd`` command if you wish to add a group to the
3252      system when the package is installed.
3253
3254      Here is an example from the ``dbus`` recipe::
3255
3256         GROUPADD_PARAM:${PN} = "-r netdev"
3257
3258      More than one group can be added by separating each set of different
3259      groups' parameters with a semicolon.
3260
3261      Here is an example adding multiple groups from the ``useradd-example.bb``
3262      file in the ``meta-skeleton`` layer::
3263
3264         GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2"
3265
3266      For information on the standard Linux shell command
3267      ``groupadd``, see https://linux.die.net/man/8/groupadd.
3268
3269   :term:`GROUPMEMS_PARAM`
3270      When inheriting the :ref:`ref-classes-useradd` class,
3271      this variable specifies for a package what parameters should be
3272      passed to the ``groupmems`` command if you wish to modify the members
3273      of a group when the package is installed.
3274
3275      For information on the standard Linux shell command ``groupmems``,
3276      see https://linux.die.net/man/8/groupmems.
3277
3278   :term:`GRUB_GFXSERIAL`
3279      Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
3280      and serial in the boot menu. Set this variable to "1" in your
3281      ``local.conf`` or distribution configuration file to enable graphics
3282      and serial in the menu.
3283
3284      See the :ref:`ref-classes-grub-efi` class for more
3285      information on how this variable is used.
3286
3287   :term:`GRUB_OPTS`
3288      Additional options to add to the GNU GRand Unified Bootloader (GRUB)
3289      configuration. Use a semi-colon character (``;``) to separate
3290      multiple options.
3291
3292      The :term:`GRUB_OPTS` variable is optional. See the
3293      :ref:`ref-classes-grub-efi` class for more information
3294      on how this variable is used.
3295
3296   :term:`GRUB_TIMEOUT`
3297      Specifies the timeout before executing the default ``LABEL`` in the
3298      GNU GRand Unified Bootloader (GRUB).
3299
3300      The :term:`GRUB_TIMEOUT` variable is optional. See the
3301      :ref:`ref-classes-grub-efi` class for more information
3302      on how this variable is used.
3303
3304   :term:`GTKIMMODULES_PACKAGES`
3305      When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
3306      this variable specifies the packages that contain the GTK+ input
3307      method modules being installed when the modules are in packages other
3308      than the main package.
3309
3310   :term:`HGDIR`
3311      See :term:`bitbake:HGDIR` in the BitBake manual.
3312
3313   :term:`HOMEPAGE`
3314      Website where more information about the software the recipe is
3315      building can be found.
3316
3317   :term:`HOST_ARCH`
3318      The name of the target architecture, which is normally the same as
3319      :term:`TARGET_ARCH`. The OpenEmbedded build system
3320      supports many architectures. Here is an example list of architectures
3321      supported. This list is by no means complete as the architecture is
3322      configurable:
3323
3324      - arm
3325      - i586
3326      - x86_64
3327      - powerpc
3328      - powerpc64
3329      - mips
3330      - mipsel
3331
3332   :term:`HOST_CC_ARCH`
3333      Specifies architecture-specific compiler flags that are passed to the
3334      C compiler.
3335
3336      Default initialization for :term:`HOST_CC_ARCH` varies depending on what
3337      is being built:
3338
3339      -  :term:`TARGET_CC_ARCH` when building for the
3340         target
3341
3342      -  :term:`BUILD_CC_ARCH` when building for the build host (i.e.
3343         ``-native``)
3344
3345      -  ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
3346         ``nativesdk-``)
3347
3348   :term:`HOST_OS`
3349      Specifies the name of the target operating system, which is normally
3350      the same as the :term:`TARGET_OS`. The variable can
3351      be set to "linux" for ``glibc``-based systems and to "linux-musl" for
3352      ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
3353      "linux-musleabi" values possible.
3354
3355   :term:`HOST_PREFIX`
3356      Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
3357      is normally the same as :term:`TARGET_PREFIX`.
3358
3359   :term:`HOST_SYS`
3360      Specifies the system, including the architecture and the operating
3361      system, for which the build is occurring in the context of the
3362      current recipe.
3363
3364      The OpenEmbedded build system automatically sets this variable based
3365      on :term:`HOST_ARCH`,
3366      :term:`HOST_VENDOR`, and
3367      :term:`HOST_OS` variables.
3368
3369      .. note::
3370
3371         You do not need to set the variable yourself.
3372
3373      Consider these two examples:
3374
3375      -  Given a native recipe on a 32-bit x86 machine running Linux, the
3376         value is "i686-linux".
3377
3378      -  Given a recipe being built for a little-endian MIPS target running
3379         Linux, the value might be "mipsel-linux".
3380
3381   :term:`HOST_VENDOR`
3382      Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
3383      same as :term:`TARGET_VENDOR`.
3384
3385   :term:`HOSTTOOLS`
3386      A space-separated list (filter) of tools on the build host that
3387      should be allowed to be called from within build tasks. Using this
3388      filter helps reduce the possibility of host contamination. If a tool
3389      specified in the value of :term:`HOSTTOOLS` is not found on the build
3390      host, the OpenEmbedded build system produces an error and the build
3391      is not started.
3392
3393      For additional information, see
3394      :term:`HOSTTOOLS_NONFATAL`.
3395
3396   :term:`HOSTTOOLS_NONFATAL`
3397      A space-separated list (filter) of tools on the build host that
3398      should be allowed to be called from within build tasks. Using this
3399      filter helps reduce the possibility of host contamination. Unlike
3400      :term:`HOSTTOOLS`, the OpenEmbedded build system
3401      does not produce an error if a tool specified in the value of
3402      :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
3403      use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
3404
3405   :term:`ICECC_CLASS_DISABLE`
3406      Identifies user classes that you do not want the Icecream distributed
3407      compile support to consider. This variable is used by the
3408      :ref:`ref-classes-icecc` class. You set this variable in
3409      your ``local.conf`` file.
3410
3411      When you list classes using this variable, the recipes inheriting
3412      those classes will not benefit from distributed compilation across
3413      remote hosts. Instead they will be built locally.
3414
3415   :term:`ICECC_DISABLED`
3416      Disables or enables the ``icecc`` (Icecream) function. For more
3417      information on this function and best practices for using this
3418      variable, see the ":ref:`ref-classes-icecc`"
3419      section.
3420
3421      Setting this variable to "1" in your ``local.conf`` disables the
3422      function::
3423
3424         ICECC_DISABLED ??= "1"
3425
3426      To enable the function, set the variable as follows::
3427
3428         ICECC_DISABLED = ""
3429
3430   :term:`ICECC_ENV_EXEC`
3431      Points to the ``icecc-create-env`` script that you provide. This
3432      variable is used by the :ref:`ref-classes-icecc` class. You
3433      set this variable in your ``local.conf`` file.
3434
3435      If you do not point to a script that you provide, the OpenEmbedded
3436      build system uses the default script provided by the
3437      :oe_git:`icecc-create-env_0.1.bb
3438      </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`
3439      recipe, which is a modified version and not the one that comes with
3440      ``icecream``.
3441
3442   :term:`ICECC_PARALLEL_MAKE`
3443      Extra options passed to the ``make`` command during the
3444      :ref:`ref-tasks-compile` task that specify parallel
3445      compilation. This variable usually takes the form of "-j x", where x
3446      represents the maximum number of parallel threads ``make`` can run.
3447
3448      .. note::
3449
3450         The options passed affect builds on all enabled machines on the
3451         network, which are machines running the ``iceccd`` daemon.
3452
3453      If your enabled machines support multiple cores, coming up with the
3454      maximum number of parallel threads that gives you the best
3455      performance could take some experimentation since machine speed,
3456      network lag, available memory, and existing machine loads can all
3457      affect build time. Consequently, unlike the
3458      :term:`PARALLEL_MAKE` variable, there is no
3459      rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
3460      performance.
3461
3462      If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
3463      use it (i.e. the system does not detect and assign the number of
3464      cores as is done with :term:`PARALLEL_MAKE`).
3465
3466   :term:`ICECC_PATH`
3467      The location of the ``icecc`` binary. You can set this variable in
3468      your ``local.conf`` file. If your ``local.conf`` file does not define
3469      this variable, the :ref:`ref-classes-icecc` class attempts
3470      to define it by locating ``icecc`` using ``which``.
3471
3472   :term:`ICECC_RECIPE_DISABLE`
3473      Identifies user recipes that you do not want the Icecream distributed
3474      compile support to consider. This variable is used by the
3475      :ref:`ref-classes-icecc` class. You set this variable in
3476      your ``local.conf`` file.
3477
3478      When you list recipes using this variable, you are excluding them
3479      from distributed compilation across remote hosts. Instead they will
3480      be built locally.
3481
3482   :term:`ICECC_RECIPE_ENABLE`
3483      Identifies user recipes that use an empty
3484      :term:`PARALLEL_MAKE` variable that you want to
3485      force remote distributed compilation on using the Icecream
3486      distributed compile support. This variable is used by the
3487      :ref:`ref-classes-icecc` class. You set this variable in
3488      your ``local.conf`` file.
3489
3490   :term:`IMAGE_BASENAME`
3491      The base name of image output files. This variable defaults to the
3492      recipe name (``${``\ :term:`PN`\ ``}``).
3493
3494   :term:`IMAGE_BOOT_FILES`
3495      A space-separated list of files installed into the boot partition
3496      when preparing an image using the Wic tool with the
3497      ``bootimg-partition`` source plugin. By default,
3498      the files are
3499      installed under the same name as the source files. To change the
3500      installed name, separate it from the original name with a semi-colon
3501      (;). Source files need to be located in
3502      :term:`DEPLOY_DIR_IMAGE`. Here are two
3503      examples::
3504
3505         IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
3506         IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
3507
3508      Alternatively, source files can be picked up using a glob pattern. In
3509      this case, the destination file must have the same name as the base
3510      name of the source file path. To install files into a directory
3511      within the target location, pass its name after a semi-colon (;).
3512      Here are two examples::
3513
3514         IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
3515         IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
3516
3517      The first example
3518      installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
3519      into the root of the target partition. The second example installs
3520      the same files into a ``boot`` directory within the target partition.
3521
3522      You can find information on how to use the Wic tool in the
3523      ":ref:`dev-manual/wic:creating partitioned images using wic`"
3524      section of the Yocto Project Development Tasks Manual. Reference
3525      material for Wic is located in the
3526      ":doc:`/ref-manual/kickstart`" chapter.
3527
3528   :term:`IMAGE_BUILDINFO_FILE`
3529      When using the :ref:`ref-classes-image-buildinfo` class,
3530      specifies the file in the image to write the build information into. The
3531      default value is "``${sysconfdir}/buildinfo``".
3532
3533   :term:`IMAGE_BUILDINFO_VARS`
3534      When using the :ref:`ref-classes-image-buildinfo` class,
3535      specifies the list of variables to include in the `Build Configuration`
3536      section of the output file (as a space-separated list). Defaults to
3537      ":term:`DISTRO` :term:`DISTRO_VERSION`".
3538
3539   :term:`IMAGE_CLASSES`
3540      A list of classes that all images should inherit. This is typically used
3541      to enable functionality across all image recipes.
3542
3543      Classes specified in :term:`IMAGE_CLASSES` must be located in the
3544      ``classes-recipe/`` or ``classes/`` subdirectories.
3545
3546   :term:`IMAGE_CMD`
3547      Specifies the command to create the image file for a specific image
3548      type, which corresponds to the value set in
3549      :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
3550      ``btrfs``, and so forth). When setting this variable, you should use
3551      an override for the associated type. Here is an example::
3552
3553         IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
3554             --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
3555             ${EXTRA_IMAGECMD}"
3556
3557      You typically do not need to set this variable unless you are adding
3558      support for a new image type. For more examples on how to set this
3559      variable, see the :ref:`ref-classes-image_types`
3560      class file, which is ``meta/classes-recipe/image_types.bbclass``.
3561
3562   :term:`IMAGE_DEVICE_TABLES`
3563      Specifies one or more files that contain custom device tables that
3564      are passed to the ``makedevs`` command as part of creating an image.
3565      These files list basic device nodes that should be created under
3566      ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
3567      ``files/device_table-minimal.txt`` is used, which is located by
3568      :term:`BBPATH`. For details on how you should write
3569      device table files, see ``meta/files/device_table-minimal.txt`` as an
3570      example.
3571
3572   :term:`IMAGE_EFI_BOOT_FILES`
3573      A space-separated list of files installed into the boot partition
3574      when preparing an image using the Wic tool with the
3575      ``bootimg-efi`` source plugin. By default,
3576      the files are
3577      installed under the same name as the source files. To change the
3578      installed name, separate it from the original name with a semi-colon
3579      (;). Source files need to be located in
3580      :term:`DEPLOY_DIR_IMAGE`. Here are two
3581      examples::
3582
3583         IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
3584         IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
3585
3586      Alternatively, source files can be picked up using a glob pattern. In
3587      this case, the destination file must have the same name as the base
3588      name of the source file path. To install files into a directory
3589      within the target location, pass its name after a semi-colon (;).
3590      Here are two examples::
3591
3592         IMAGE_EFI_BOOT_FILES = "boot/loader/*"
3593         IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
3594
3595      The first example
3596      installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
3597      into the root of the target partition. The second example installs
3598      the same files into a ``boot`` directory within the target partition.
3599
3600      You can find information on how to use the Wic tool in the
3601      ":ref:`dev-manual/wic:creating partitioned images using wic`"
3602      section of the Yocto Project Development Tasks Manual. Reference
3603      material for Wic is located in the
3604      ":doc:`/ref-manual/kickstart`" chapter.
3605
3606   :term:`IMAGE_FEATURES`
3607      The primary list of features to include in an image. Typically, you
3608      configure this variable in an image recipe. Although you can use this
3609      variable from your ``local.conf`` file, which is found in the
3610      :term:`Build Directory`, best practices dictate that you do
3611      not.
3612
3613      .. note::
3614
3615         To enable extra features from outside the image recipe, use the
3616         :term:`EXTRA_IMAGE_FEATURES` variable.
3617
3618      For a list of image features that ships with the Yocto Project, see
3619      the ":ref:`ref-features-image`" section.
3620
3621      For an example that shows how to customize your image by using this
3622      variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
3623      section in the Yocto Project Development Tasks Manual.
3624
3625   :term:`IMAGE_FSTYPES`
3626      Specifies the formats the OpenEmbedded build system uses during the
3627      build when creating the root filesystem. For example, setting
3628      :term:`IMAGE_FSTYPES` as follows causes the build system to create root
3629      filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
3630
3631         IMAGE_FSTYPES = "ext3 tar.bz2"
3632
3633      For the complete list of supported image formats from which you can
3634      choose, see :term:`IMAGE_TYPES`.
3635
3636      .. note::
3637
3638         -  If an image recipe uses the "inherit image" line and you are
3639            setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
3640            :term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
3641
3642         -  Due to the way the OpenEmbedded build system processes this
3643            variable, you cannot update its contents by using ``:append``
3644            or ``:prepend``. You must use the ``+=`` operator to add one or
3645            more options to the :term:`IMAGE_FSTYPES` variable.
3646
3647   :term:`IMAGE_INSTALL`
3648      Used by recipes to specify the packages to install into an image
3649      through the :ref:`ref-classes-image` class. Use the
3650      :term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
3651
3652      Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
3653      install into an image through :ref:`ref-classes-image`. Additionally,
3654      there are "helper" classes such as the :ref:`ref-classes-core-image`
3655      class which can take lists used with :term:`IMAGE_FEATURES` and turn
3656      them into auto-generated entries in :term:`IMAGE_INSTALL` in addition
3657      to its default contents.
3658
3659      When you use this variable, it is best to use it as follows::
3660
3661         IMAGE_INSTALL:append = " package-name"
3662
3663      Be sure to include the space
3664      between the quotation character and the start of the package name or
3665      names.
3666
3667      .. note::
3668
3669         -  When working with a
3670            :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
3671            image, do not use the :term:`IMAGE_INSTALL` variable to specify
3672            packages for installation. Instead, use the
3673            :term:`PACKAGE_INSTALL` variable, which
3674            allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a
3675            fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
3676            For information on creating an :term:`Initramfs`, see the
3677            ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
3678            section in the Yocto Project Development Tasks Manual.
3679
3680         -  Using :term:`IMAGE_INSTALL` with the
3681            :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
3682            BitBake operator within the ``/conf/local.conf`` file or from
3683            within an image recipe is not recommended. Use of this operator in
3684            these ways can cause ordering issues. Since
3685            :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a
3686            default value using the
3687            :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
3688            operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
3689            results in unexpected behavior when used within
3690            ``conf/local.conf``. Furthermore, the same operation from within an
3691            image recipe may or may not succeed depending on the specific
3692            situation. In both these cases, the behavior is contrary to how
3693            most users expect the ``+=`` operator to work.
3694
3695   :term:`IMAGE_LINGUAS`
3696      Specifies the list of locales to install into the image during the
3697      root filesystem construction process. The OpenEmbedded build system
3698      automatically splits locale files, which are used for localization,
3699      into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
3700      ensures that any locale packages that correspond to packages already
3701      selected for installation into the image are also installed. Here is
3702      an example::
3703
3704         IMAGE_LINGUAS = "pt-br de-de"
3705
3706      In this example, the build system ensures any Brazilian Portuguese
3707      and German locale files that correspond to packages in the image are
3708      installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
3709      ``*-locale-pt`` and ``*-locale-de``, since some software packages
3710      only provide locale files by language and not by country-specific
3711      language).
3712
3713      See the :term:`GLIBC_GENERATE_LOCALES`
3714      variable for information on generating GLIBC locales.
3715
3716
3717   :term:`IMAGE_LINK_NAME`
3718      The name of the output image symlink (which does not include
3719      the version part as :term:`IMAGE_NAME` does). The default value
3720      is derived using the :term:`IMAGE_BASENAME` and
3721      :term:`IMAGE_MACHINE_SUFFIX` variables::
3722
3723         IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}"
3724
3725      .. note::
3726
3727         It is possible to set this to "" to disable symlink creation,
3728         however, you also need to set :term:`IMAGE_NAME` to still have
3729         a reasonable value e.g.::
3730
3731            IMAGE_LINK_NAME = ""
3732            IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
3733
3734   :term:`IMAGE_MACHINE_SUFFIX`
3735      Specifies the by default machine-specific suffix for image file names
3736      (before the extension). The default value is set as follows::
3737
3738         IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}"
3739
3740      The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE`
3741      subdirectory, so you may find it unnecessary to also include this suffix
3742      in the name of every image file. If you prefer to remove the suffix you
3743      can set this variable to an empty string::
3744
3745         IMAGE_MACHINE_SUFFIX = ""
3746
3747      (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.)
3748
3749   :term:`IMAGE_MANIFEST`
3750      The manifest file for the image. This file lists all the installed
3751      packages that make up the image. The file contains package
3752      information on a line-per-package basis as follows::
3753
3754          packagename packagearch version
3755
3756      The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
3757      file as follows::
3758
3759         IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
3760
3761      The location is
3762      derived using the :term:`IMGDEPLOYDIR`
3763      and :term:`IMAGE_NAME` variables. You can find
3764      information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
3765      section in the Yocto Project Overview and Concepts Manual.
3766
3767   :term:`IMAGE_NAME`
3768      The name of the output image files minus the extension. By default
3769      this variable is set using the :term:`IMAGE_LINK_NAME`, and
3770      :term:`IMAGE_VERSION_SUFFIX` variables::
3771
3772         IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}"
3773
3774   :term:`IMAGE_NAME_SUFFIX`
3775      Suffix used for the image output filename --- defaults to ``".rootfs"``
3776      to distinguish the image file from other files created during image
3777      building; however if this suffix is redundant or not desired you can
3778      clear the value of this variable (set the value to ""). For example,
3779      this is typically cleared in :term:`Initramfs` image recipes.
3780
3781   :term:`IMAGE_OVERHEAD_FACTOR`
3782      Defines a multiplier that the build system applies to the initial
3783      image size for cases when the multiplier times the returned disk
3784      usage value for the image is greater than the sum of
3785      :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
3786      the multiplier applied to the initial image size creates free disk
3787      space in the image as overhead. By default, the build process uses a
3788      multiplier of 1.3 for this variable. This default value results in
3789      30% free disk space added to the image when this method is used to
3790      determine the final generated image size. You should be aware that
3791      post install scripts and the package management system uses disk
3792      space inside this overhead area. Consequently, the multiplier does
3793      not produce an image with all the theoretical free disk space. See
3794      :term:`IMAGE_ROOTFS_SIZE` for information on how the build system
3795      determines the overall image size.
3796
3797      The default 30% free disk space typically gives the image enough room
3798      to boot and allows for basic post installs while still leaving a
3799      small amount of free disk space. If 30% free space is inadequate, you
3800      can increase the default value. For example, the following setting
3801      gives you 50% free space added to the image::
3802
3803         IMAGE_OVERHEAD_FACTOR = "1.5"
3804
3805      Alternatively, you can ensure a specific amount of free disk space is
3806      added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3807      variable.
3808
3809   :term:`IMAGE_PKGTYPE`
3810      Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
3811      OpenEmbedded build system. The variable is defined appropriately by
3812      the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`,
3813      or :ref:`ref-classes-package_ipk` class.
3814
3815      The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image`
3816      classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs.
3817
3818      You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
3819      variable is set indirectly through the appropriate
3820      :ref:`package_* <ref-classes-package>` class using the
3821      :term:`PACKAGE_CLASSES` variable. The
3822      OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
3823      or IPK) that appears with the variable
3824
3825      .. note::
3826
3827         Files using the ``.tar`` format are never used as a substitute
3828         packaging format for DEB, RPM, and IPK formatted files for your image
3829         or SDK.
3830
3831   :term:`IMAGE_POSTPROCESS_COMMAND`
3832      Specifies a list of functions to call once the OpenEmbedded build
3833      system creates the final image output files. You can specify
3834      functions separated by spaces::
3835
3836         IMAGE_POSTPROCESS_COMMAND += "function"
3837
3838      If you need to pass the root filesystem path to a command within the
3839      function, you can use ``${IMAGE_ROOTFS}``, which points to the
3840      directory that becomes the root filesystem image. See the
3841      :term:`IMAGE_ROOTFS` variable for more
3842      information.
3843
3844   :term:`IMAGE_PREPROCESS_COMMAND`
3845      Specifies a list of functions to call before the OpenEmbedded build
3846      system creates the final image output files. You can specify
3847      functions separated by spaces::
3848
3849         IMAGE_PREPROCESS_COMMAND += "function"
3850
3851      If you need to pass the root filesystem path to a command within the
3852      function, you can use ``${IMAGE_ROOTFS}``, which points to the
3853      directory that becomes the root filesystem image. See the
3854      :term:`IMAGE_ROOTFS` variable for more
3855      information.
3856
3857   :term:`IMAGE_ROOTFS`
3858      The location of the root filesystem while it is under construction
3859      (i.e. during the :ref:`ref-tasks-rootfs` task). This
3860      variable is not configurable. Do not change it.
3861
3862   :term:`IMAGE_ROOTFS_ALIGNMENT`
3863      Specifies the alignment for the output image file in Kbytes. If the
3864      size of the image is not a multiple of this value, then the size is
3865      rounded up to the nearest multiple of the value. The default value is
3866      "1". See :term:`IMAGE_ROOTFS_SIZE` for
3867      additional information.
3868
3869   :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3870      Defines additional free disk space created in the image in Kbytes. By
3871      default, this variable is set to "0". This free disk space is added
3872      to the image after the build system determines the image size as
3873      described in :term:`IMAGE_ROOTFS_SIZE`.
3874
3875      This variable is particularly useful when you want to ensure that a
3876      specific amount of free disk space is available on a device after an
3877      image is installed and running. For example, to be sure 5 Gbytes of
3878      free disk space is available, set the variable as follows::
3879
3880         IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3881
3882      For example, the Yocto Project Build Appliance specifically requests
3883      40 Gbytes of extra space with the line::
3884
3885         IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3886
3887   :term:`IMAGE_ROOTFS_SIZE`
3888      Defines the size in Kbytes for the generated image. The OpenEmbedded
3889      build system determines the final size for the generated image using
3890      an algorithm that takes into account the initial disk space used for
3891      the generated image, a requested size for the image, and requested
3892      additional free disk space to be added to the image. Programatically,
3893      the build system determines the final size of the generated image as
3894      follows::
3895
3896         if (image-du * overhead) < rootfs-size:
3897             internal-rootfs-size = rootfs-size + xspace
3898         else:
3899             internal-rootfs-size = (image-du * overhead) + xspace
3900         where:
3901             image-du = Returned value of the du command on the image.
3902             overhead = IMAGE_OVERHEAD_FACTOR
3903             rootfs-size = IMAGE_ROOTFS_SIZE
3904             internal-rootfs-size = Initial root filesystem size before any modifications.
3905             xspace = IMAGE_ROOTFS_EXTRA_SPACE
3906
3907      See the :term:`IMAGE_OVERHEAD_FACTOR`
3908      and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3909      variables for related information.
3910
3911   :term:`IMAGE_TYPEDEP`
3912      Specifies a dependency from one image type on another. Here is an
3913      example from the :ref:`ref-classes-image-live` class::
3914
3915         IMAGE_TYPEDEP:live = "ext3"
3916
3917      In the previous example, the variable ensures that when "live" is
3918      listed with the :term:`IMAGE_FSTYPES` variable,
3919      the OpenEmbedded build system produces an ``ext3`` image first since
3920      one of the components of the live image is an ``ext3`` formatted
3921      partition containing the root filesystem.
3922
3923   :term:`IMAGE_TYPES`
3924      Specifies the complete list of supported image types by default:
3925
3926      - btrfs
3927      - container
3928      - cpio
3929      - cpio.gz
3930      - cpio.lz4
3931      - cpio.lzma
3932      - cpio.xz
3933      - cramfs
3934      - erofs
3935      - erofs-lz4
3936      - erofs-lz4hc
3937      - ext2
3938      - ext2.bz2
3939      - ext2.gz
3940      - ext2.lzma
3941      - ext3
3942      - ext3.gz
3943      - ext4
3944      - ext4.gz
3945      - f2fs
3946      - hddimg
3947      - iso
3948      - jffs2
3949      - jffs2.sum
3950      - multiubi
3951      - squashfs
3952      - squashfs-lz4
3953      - squashfs-lzo
3954      - squashfs-xz
3955      - tar
3956      - tar.bz2
3957      - tar.gz
3958      - tar.lz4
3959      - tar.xz
3960      - tar.zst
3961      - ubi
3962      - ubifs
3963      - wic
3964      - wic.bz2
3965      - wic.gz
3966      - wic.lzma
3967
3968      For more information about these types of images, see
3969      ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`.
3970
3971   :term:`IMAGE_VERSION_SUFFIX`
3972      Version suffix that is part of the default :term:`IMAGE_NAME` and
3973      :term:`KERNEL_ARTIFACT_NAME` values.
3974      Defaults to ``"-${DATETIME}"``, however you could set this to a
3975      version string that comes from your external build environment if
3976      desired, and this suffix would then be used consistently across
3977      the build artifacts.
3978
3979   :term:`IMGDEPLOYDIR`
3980      When inheriting the :ref:`ref-classes-image` class directly or
3981      through the :ref:`ref-classes-core-image` class, the
3982      :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
3983      that is set in the ``image`` class as follows::
3984
3985         IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
3986
3987      Recipes inheriting the :ref:`ref-classes-image` class should copy
3988      files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take
3989      care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
3990
3991   :term:`INCOMPATIBLE_LICENSE`
3992      Specifies a space-separated list of license names (as they would
3993      appear in :term:`LICENSE`) that should be excluded
3994      from the build (if set globally), or from an image (if set locally
3995      in an image recipe).
3996
3997      When the variable is set globally, recipes that provide no alternatives to listed
3998      incompatible licenses are not built. Packages that are individually
3999      licensed with the specified incompatible licenses will be deleted.
4000      Most of the time this does not allow a feasible build (because it becomes impossible
4001      to satisfy build time dependencies), so the recommended way to
4002      implement license restrictions is to set the variable in specific
4003      image recipes where the restrictions must apply. That way there
4004      are no build time restrictions, but the license check is still
4005      performed when the image's filesystem is assembled from packages.
4006
4007      There is some support for wildcards in this variable's value,
4008      however it is restricted to specific licenses. Currently only
4009      these wildcards are allowed and expand as follows:
4010
4011      - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later``
4012      - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later``
4013      - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later``
4014
4015      .. note::
4016
4017         This functionality is only regularly tested using the following
4018         setting::
4019
4020                 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"
4021
4022
4023         Although you can use other settings, you might be required to
4024         remove dependencies on (or provide alternatives to) components that
4025         are required to produce a functional system image.
4026
4027   :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`
4028      Specifies a space-separated list of package and license pairs that
4029      are allowed to be used even if the license is specified in
4030      :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are
4031      separated using a colon. Example::
4032
4033         INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only"
4034
4035   :term:`INHERIT`
4036      Causes the named class or classes to be inherited globally. Anonymous
4037      functions in the class or classes are not executed for the base
4038      configuration and in each individual recipe. The OpenEmbedded build
4039      system ignores changes to :term:`INHERIT` in individual recipes.
4040      Classes inherited using :term:`INHERIT` must be located in the
4041      ``classes-global/`` or ``classes/`` subdirectories.
4042
4043      For more information on :term:`INHERIT`, see the
4044      :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
4045      section in the BitBake User Manual.
4046
4047   :term:`INHERIT_DISTRO`
4048      Lists classes that will be inherited at the distribution level. It is
4049      unlikely that you want to edit this variable.
4050
4051      Classes specified in :term:`INHERIT_DISTRO` must be located in the
4052      ``classes-global/`` or ``classes/`` subdirectories.
4053
4054      The default value of the variable is set as follows in the
4055      ``meta/conf/distro/defaultsetup.conf`` file::
4056
4057         INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx"
4058
4059   :term:`INHIBIT_DEFAULT_DEPS`
4060      Prevents the default dependencies, namely the C compiler and standard
4061      C library (libc), from being added to :term:`DEPENDS`.
4062      This variable is usually used within recipes that do not require any
4063      compilation using the C compiler.
4064
4065      Set the variable to "1" to prevent the default dependencies from
4066      being added.
4067
4068   :term:`INHIBIT_PACKAGE_DEBUG_SPLIT`
4069      Prevents the OpenEmbedded build system from splitting out debug
4070      information during packaging. By default, the build system splits out
4071      debugging information during the
4072      :ref:`ref-tasks-package` task. For more information on
4073      how debug information is split out, see the
4074      :term:`PACKAGE_DEBUG_SPLIT_STYLE`
4075      variable.
4076
4077      To prevent the build system from splitting out debug information
4078      during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
4079      follows::
4080
4081         INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
4082
4083   :term:`INHIBIT_PACKAGE_STRIP`
4084      If set to "1", causes the build to not strip binaries in resulting
4085      packages and prevents the ``-dbg`` package from containing the source
4086      files.
4087
4088      By default, the OpenEmbedded build system strips binaries and puts
4089      the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
4090      Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
4091      plan to debug in general.
4092
4093   :term:`INHIBIT_SYSROOT_STRIP`
4094      If set to "1", causes the build to not strip binaries in the
4095      resulting sysroot.
4096
4097      By default, the OpenEmbedded build system strips binaries in the
4098      resulting sysroot. When you specifically set the
4099      :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
4100      this stripping.
4101
4102      If you want to use this variable, include the :ref:`ref-classes-staging`
4103      class. This class uses a ``sys_strip()`` function to test for the variable
4104      and acts accordingly.
4105
4106      .. note::
4107
4108         Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
4109         special circumstances. For example, suppose you are building
4110         bare-metal firmware by using an external GCC toolchain. Furthermore,
4111         even if the toolchain's binaries are strippable, there are other files
4112         needed for the build that are not strippable.
4113
4114   :term:`INIT_MANAGER`
4115      Specifies the system init manager to use. Available options are:
4116
4117      -  ``sysvinit``
4118      -  ``systemd``
4119      -  ``mdev-busybox``
4120
4121      With ``sysvinit``, the init manager is set to
4122      :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init
4123      system. This is the default choice in the Poky distribution, together with
4124      the Udev device manager (see the ":ref:`device-manager`" section).
4125
4126      With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`,
4127      which comes with the :wikipedia:`udev <Udev>` device manager.
4128
4129      With ``mdev-busybox``, the init manager becomes the much simpler BusyBox
4130      init, together with the BusyBox mdev device manager. This is the simplest
4131      and lightest solution, and probably the best choice for low-end systems
4132      with a rather slow CPU and a limited amount of RAM.
4133
4134      More concretely, this is used to include
4135      ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global
4136      configuration. You can have a look at the
4137      :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>`
4138      files for more information, and also the ":ref:`init-manager`"
4139      section in the Yocto Project Development Tasks Manual.
4140
4141   :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
4142      Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs`
4143      where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is
4144      set by default to ``${DEPLOY_DIR_IMAGE}`` in the
4145      :ref:`ref-classes-kernel` class and it's only meant to be changed when
4146      building an :term:`Initramfs` image from a separate multiconfig via
4147      :term:`INITRAMFS_MULTICONFIG`.
4148
4149   :term:`INITRAMFS_FSTYPES`
4150      Defines the format for the output image of an initial RAM filesystem
4151      (:term:`Initramfs`), which is used during boot. Supported formats are the
4152      same as those supported by the
4153      :term:`IMAGE_FSTYPES` variable.
4154
4155      The default value of this variable, which is set in the
4156      ``meta/conf/bitbake.conf`` configuration file in the
4157      :term:`Source Directory`, is "cpio.gz". The Linux kernel's
4158      :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem
4159      :wikipedia:`initrd <Initrd>` mechanism, expects
4160      an optionally compressed cpio archive.
4161
4162   :term:`INITRAMFS_IMAGE`
4163      Specifies the :term:`PROVIDES` name of an image
4164      recipe that is used to build an initial RAM filesystem (:term:`Initramfs`)
4165      image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
4166      additional recipe to be built as a dependency to whatever root
4167      filesystem recipe you might be using (e.g. ``core-image-sato``). The
4168      :term:`Initramfs` image recipe you provide should set
4169      :term:`IMAGE_FSTYPES` to
4170      :term:`INITRAMFS_FSTYPES`.
4171
4172      An :term:`Initramfs` image provides a temporary root filesystem used for
4173      early system initialization (e.g. loading of modules needed to locate
4174      and mount the "real" root filesystem).
4175
4176      .. note::
4177
4178         See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
4179         recipe in the :term:`Source Directory`
4180         for an example :term:`Initramfs` recipe. To select this sample recipe as
4181         the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE`
4182         to "core-image-minimal-initramfs".
4183
4184      You can also find more information by referencing the
4185      ``meta-poky/conf/templates/default/local.conf.sample.extended``
4186      configuration file in the Source Directory, the :ref:`ref-classes-image`
4187      class, and the :ref:`ref-classes-kernel` class to see how to use the
4188      :term:`INITRAMFS_IMAGE` variable.
4189
4190      If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
4191      :term:`Initramfs` image is built.
4192
4193      For more information, you can also see the
4194      :term:`INITRAMFS_IMAGE_BUNDLE`
4195      variable, which allows the generated image to be bundled inside the
4196      kernel image. Additionally, for information on creating an :term:`Initramfs`
4197      image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
4198      in the Yocto Project Development Tasks Manual.
4199
4200   :term:`INITRAMFS_IMAGE_BUNDLE`
4201      Controls whether or not the image recipe specified by
4202      :term:`INITRAMFS_IMAGE` is run through an
4203      extra pass
4204      (:ref:`ref-tasks-bundle_initramfs`) during
4205      kernel compilation in order to build a single binary that contains
4206      both the kernel image and the initial RAM filesystem (:term:`Initramfs`)
4207      image. This makes use of the
4208      :term:`CONFIG_INITRAMFS_SOURCE` kernel
4209      feature.
4210
4211      .. note::
4212
4213         Bundling the :term:`Initramfs` with the kernel conflates the code in the
4214         :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
4215         compatible software may be part of a bundled :term:`Initramfs`.
4216
4217      .. note::
4218
4219         Using an extra compilation pass to bundle the :term:`Initramfs` avoids a
4220         circular dependency between the kernel recipe and the :term:`Initramfs`
4221         recipe should the :term:`Initramfs` include kernel modules. Should that be
4222         the case, the :term:`Initramfs` recipe depends on the kernel for the
4223         kernel modules, and the kernel depends on the :term:`Initramfs` recipe
4224         since the :term:`Initramfs` is bundled inside the kernel image.
4225
4226      The combined binary is deposited into the ``tmp/deploy`` directory,
4227      which is part of the :term:`Build Directory`.
4228
4229      Setting the variable to "1" in a configuration file causes the
4230      OpenEmbedded build system to generate a kernel image with the
4231      :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within::
4232
4233         INITRAMFS_IMAGE_BUNDLE = "1"
4234
4235      By default, the :ref:`ref-classes-kernel` class sets this variable to a
4236      null string as follows::
4237
4238         INITRAMFS_IMAGE_BUNDLE ?= ""
4239
4240      .. note::
4241
4242         You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a
4243         configuration file. You cannot set the variable in a recipe file.
4244
4245      See the
4246      :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>`
4247      file for additional information. Also, for information on creating an
4248      :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
4249      in the Yocto Project Development Tasks Manual.
4250
4251   :term:`INITRAMFS_IMAGE_NAME`
4252
4253      This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with
4254      :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value
4255      is set as follows:
4256
4257         INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}"
4258
4259      That is, if :term:`INITRAMFS_IMAGE` is set, the value of
4260      :term:`INITRAMFS_IMAGE_NAME` will be set based upon
4261      :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`.
4262
4263
4264   :term:`INITRAMFS_LINK_NAME`
4265      The link name of the initial RAM filesystem image. This variable is
4266      set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
4267      follows::
4268
4269         INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
4270
4271      The value of the
4272      ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
4273      file, has the following value::
4274
4275         KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4276
4277      See the :term:`MACHINE` variable for additional
4278      information.
4279
4280   :term:`INITRAMFS_MULTICONFIG`
4281      Defines the multiconfig to create a multiconfig dependency to be used by
4282      the :ref:`ref-classes-kernel` class.
4283
4284      This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from
4285      a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`.
4286
4287      For more information on how to bundle an :term:`Initramfs` image from a separate
4288      multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`"
4289      section in the Yocto Project Development Tasks Manual.
4290
4291   :term:`INITRAMFS_NAME`
4292      The base name of the initial RAM filesystem image. This variable is
4293      set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
4294      follows::
4295
4296         INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
4297
4298      See :term:`KERNEL_ARTIFACT_NAME` for additional information.
4299
4300   :term:`INITRD`
4301      Indicates list of filesystem images to concatenate and use as an
4302      initial RAM disk (``initrd``).
4303
4304      The :term:`INITRD` variable is an optional variable used with the
4305      :ref:`ref-classes-image-live` class.
4306
4307   :term:`INITRD_IMAGE`
4308      When building a "live" bootable image (i.e. when
4309      :term:`IMAGE_FSTYPES` contains "live"),
4310      :term:`INITRD_IMAGE` specifies the image recipe that should be built to
4311      provide the initial RAM disk image. The default value is
4312      "core-image-minimal-initramfs".
4313
4314      See the :ref:`ref-classes-image-live` class for more information.
4315
4316   :term:`INITSCRIPT_NAME`
4317      The filename of the initialization script as installed to
4318      ``${sysconfdir}/init.d``.
4319
4320      This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
4321      The variable is mandatory.
4322
4323   :term:`INITSCRIPT_PACKAGES`
4324      A list of the packages that contain initscripts. If multiple packages
4325      are specified, you need to append the package name to the other
4326      ``INITSCRIPT_*`` as an override.
4327
4328      This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
4329      The variable is optional and defaults to the :term:`PN`
4330      variable.
4331
4332   :term:`INITSCRIPT_PARAMS`
4333      Specifies the options to pass to ``update-rc.d``. Here is an example::
4334
4335         INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
4336
4337      In this example, the script has a runlevel of 99, starts the script
4338      in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
4339
4340      The variable's default value is "defaults", which is set in the
4341      :ref:`ref-classes-update-rc.d` class.
4342
4343      The value in :term:`INITSCRIPT_PARAMS` is passed through to the
4344      ``update-rc.d`` command. For more information on valid parameters,
4345      please see the ``update-rc.d`` manual page at
4346      https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
4347
4348   :term:`INSANE_SKIP`
4349      Specifies the QA checks to skip for a specific package within a
4350      recipe. For example, to skip the check for symbolic link ``.so``
4351      files in the main package of a recipe, add the following to the
4352      recipe. The package name override must be used, which in this example
4353      is ``${PN}``::
4354
4355         INSANE_SKIP:${PN} += "dev-so"
4356
4357      See the ":ref:`ref-classes-insane`" section for a
4358      list of the valid QA checks you can specify using this variable.
4359
4360   :term:`INSTALL_TIMEZONE_FILE`
4361      By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
4362      Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the
4363      configuration level to disable this behavior.
4364
4365   :term:`IPK_FEED_URIS`
4366      When the IPK backend is in use and package management is enabled on
4367      the target, you can use this variable to set up ``opkg`` in the
4368      target image to point to package feeds on a nominated server. Once
4369      the feed is established, you can perform installations or upgrades
4370      using the package manager at runtime.
4371
4372   :term:`KARCH`
4373      Defines the kernel architecture used when assembling the
4374      configuration. Architectures supported for this release are:
4375
4376      - powerpc
4377      - i386
4378      - x86_64
4379      - arm
4380      - qemu
4381      - mips
4382
4383      You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`.
4384
4385   :term:`KBRANCH`
4386      A regular expression used by the build process to explicitly identify
4387      the kernel branch that is validated, patched, and configured during a
4388      build. You must set this variable to ensure the exact kernel branch
4389      you want is being used by the build process.
4390
4391      Values for this variable are set in the kernel's recipe file and the
4392      kernel's append file. For example, if you are using the
4393      ``linux-yocto_4.12`` kernel, the kernel recipe file is the
4394      ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
4395      is set as follows in that kernel recipe file::
4396
4397         KBRANCH ?= "standard/base"
4398
4399      This variable is also used from the kernel's append file to identify
4400      the kernel branch specific to a particular machine or target
4401      hardware. Continuing with the previous kernel example, the kernel's
4402      append file is located in the
4403      BSP layer for a given machine. For example, the append file for the
4404      Beaglebone and generic versions of both 32 and 64-bit IA
4405      machines (``meta-yocto-bsp``) is named
4406      ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``.
4407      Here are the related statements from that append file::
4408
4409         KBRANCH:genericx86  = "v6.1/standard/base"
4410         KBRANCH:genericx86-64  = "v6.1/standard/base"
4411         KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone"
4412
4413      The :term:`KBRANCH` statements
4414      identify the kernel branch to use when building for each supported
4415      BSP.
4416
4417   :term:`KBUILD_DEFCONFIG`
4418      When used with the :ref:`ref-classes-kernel-yocto`
4419      class, specifies an "in-tree" kernel configuration file for use
4420      during a kernel build.
4421
4422      Typically, when using a ``defconfig`` to configure a kernel during a
4423      build, you place the file in your layer in the same manner as you
4424      would place patch files and configuration fragment files (i.e.
4425      "out-of-tree"). However, if you want to use a ``defconfig`` file that
4426      is part of the kernel tree (i.e. "in-tree"), you can use the
4427      :term:`KBUILD_DEFCONFIG` variable and append the
4428      :term:`KMACHINE` variable to point to the
4429      ``defconfig`` file.
4430
4431      To use the variable, set it in the append file for your kernel recipe
4432      using the following form::
4433
4434         KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
4435
4436      Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses
4437      a ``defconfig`` file named "bcm2709_defconfig"::
4438
4439         KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
4440
4441      As an alternative, you can use the following within your append file::
4442
4443         KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
4444
4445      For more
4446      information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the
4447      ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
4448      section in the Yocto Project Linux Kernel Development Manual.
4449
4450   :term:`KCONFIG_MODE`
4451      When used with the :ref:`ref-classes-kernel-yocto`
4452      class, specifies the kernel configuration values to use for options
4453      not specified in the provided ``defconfig`` file. Valid options are::
4454
4455         KCONFIG_MODE = "alldefconfig"
4456         KCONFIG_MODE = "allnoconfig"
4457
4458      In ``alldefconfig`` mode the options not explicitly specified will be
4459      assigned their Kconfig default value. In ``allnoconfig`` mode the
4460      options not explicitly specified will be disabled in the kernel
4461      config.
4462
4463      In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where
4464      the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
4465      will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
4466      in ``${WORKDIR}`` through a meta-layer will be handled in
4467      ``allnoconfig`` mode.
4468
4469      An "in-tree" ``defconfig`` file can be selected via the
4470      :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to
4471      be explicitly set.
4472
4473      A ``defconfig`` file compatible with ``allnoconfig`` mode can be
4474      generated by copying the ``.config`` file from a working Linux kernel
4475      build, renaming it to ``defconfig`` and placing it into the Linux
4476      kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does
4477      not need to be explicitly set.
4478
4479      A ``defconfig`` file compatible with ``alldefconfig`` mode can be
4480      generated using the
4481      :ref:`ref-tasks-savedefconfig`
4482      task and placed into the Linux kernel ``${WORKDIR}`` through your
4483      meta-layer. Explicitely set :term:`KCONFIG_MODE`::
4484
4485         KCONFIG_MODE = "alldefconfig"
4486
4487   :term:`KERNEL_ALT_IMAGETYPE`
4488      Specifies an alternate kernel image type for creation in addition to
4489      the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and
4490      :term:`KERNEL_IMAGETYPES` variables.
4491
4492   :term:`KERNEL_ARTIFACT_NAME`
4493      Specifies the name of all of the build artifacts. You can change the
4494      name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME`
4495      variable.
4496
4497      The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
4498      ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the
4499      following default value::
4500
4501         KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
4502
4503      See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX`
4504      and :term:`IMAGE_VERSION_SUFFIX` variables for additional information.
4505
4506   :term:`KERNEL_CLASSES`
4507      A list of classes defining kernel image types that the
4508      :ref:`ref-classes-kernel` class should inherit. You typically
4509      append this variable to enable extended image types. An example is
4510      ":ref:`ref-classes-kernel-fitimage`", which enables
4511      FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``.
4512      You can register custom kernel image types with the
4513      :ref:`ref-classes-kernel` class using this variable.
4514
4515   :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY`
4516      When kernel configuration fragments are missing for some
4517      :term:`KERNEL_FEATURES` specified by layers or BSPs,
4518      building and configuring the kernel stops with an error.
4519
4520      You can turn these errors into warnings by setting the
4521      following in ``conf/local.conf``::
4522
4523         KERNEL_DANGLING_FEATURES_WARN_ONLY = "1"
4524
4525      You will still be warned that runtime issues may occur,
4526      but at least the kernel configuration and build process will
4527      be allowed to continue.
4528
4529   :term:`KERNEL_DEBUG_TIMESTAMPS`
4530      If set to "1", enables timestamping functionality during building
4531      the kernel. The default is "0" to disable this for reproducibility
4532      reasons.
4533
4534   :term:`KERNEL_DEPLOY_DEPEND`
4535      Provides a means of controlling the dependency of an image recipe
4536      on the kernel. The default value is "virtual/kernel:do_deploy",
4537      however for a small initramfs image or other images that do not
4538      need the kernel, this can be set to "" in the image recipe.
4539
4540   :term:`KERNEL_DEVICETREE`
4541      Specifies the name of the generated Linux kernel device tree (i.e.
4542      the ``.dtb``) file.
4543
4544      .. note::
4545
4546         There is legacy support for specifying the full path to the device
4547         tree. However, providing just the ``.dtb`` file is preferred.
4548
4549      In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
4550      class must be inherited.
4551
4552   :term:`KERNEL_DEVICETREE_BUNDLE`
4553      When set to "1", this variable allows to bundle the Linux kernel
4554      and the Device Tree Binary together in a single file.
4555
4556      This feature is currently only supported on the "arm" (32 bit)
4557      architecture.
4558
4559      This variable is set to "0" by default by the
4560      :ref:`ref-classes-kernel-devicetree` class.
4561
4562   :term:`KERNEL_DTB_LINK_NAME`
4563      The link name of the kernel device tree binary (DTB). This variable
4564      is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
4565      follows::
4566
4567         KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4568
4569      The
4570      value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
4571      the same file, has the following value::
4572
4573         KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4574
4575      See the :term:`MACHINE` variable for additional
4576      information.
4577
4578   :term:`KERNEL_DTB_NAME`
4579      The base name of the kernel device tree binary (DTB). This variable
4580      is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
4581      follows::
4582
4583         KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4584
4585      See :term:`KERNEL_ARTIFACT_NAME` for additional information.
4586
4587   :term:`KERNEL_DTBDEST`
4588      This variable, used by the :ref:`ref-classes-kernel-devicetree`
4589      class, allows to change the installation directory of the DTB
4590      (Device Tree Binary) files.
4591
4592      It is set by default to "${KERNEL_IMAGEDEST}" by the
4593      :ref:`ref-classes-kernel` class.
4594
4595   :term:`KERNEL_DTBVENDORED`
4596      This variable, used by the :ref:`ref-classes-kernel-devicetree`,
4597      allows to ignore vendor subdirectories when installing DTB
4598      (Device Tree Binary) files, when it is set to "false".
4599
4600      To keep vendor subdirectories, set this variable to "true".
4601
4602      It is set by default to "false" by the :ref:`ref-classes-kernel` class.
4603
4604   :term:`KERNEL_DTC_FLAGS`
4605      Specifies the ``dtc`` flags that are passed to the Linux kernel build
4606      system when generating the device trees (via ``DTC_FLAGS`` environment
4607      variable).
4608
4609      In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
4610      class must be inherited.
4611
4612   :term:`KERNEL_EXTRA_ARGS`
4613      Specifies additional ``make`` command-line arguments the OpenEmbedded
4614      build system passes on when compiling the kernel.
4615
4616   :term:`KERNEL_FEATURES`
4617      Includes additional kernel metadata. In the OpenEmbedded build
4618      system, the default Board Support Packages (BSPs)
4619      :term:`Metadata` is provided through the
4620      :term:`KMACHINE` and :term:`KBRANCH`
4621      variables. You can use the :term:`KERNEL_FEATURES` variable from within
4622      the kernel recipe or kernel append file to further add metadata for
4623      all BSPs or specific BSPs.
4624
4625      The metadata you add through this variable includes config fragments
4626      and features descriptions, which usually includes patches as well as
4627      config fragments. You typically override the :term:`KERNEL_FEATURES`
4628      variable for a specific machine. In this way, you can provide
4629      validated, but optional, sets of kernel configurations and features.
4630
4631      For example, the following example from the ``linux-yocto-rt_4.12``
4632      kernel recipe adds "netfilter" and "taskstats" features to all BSPs
4633      as well as "virtio" configurations to all QEMU machines. The last two
4634      statements add specific configurations to targeted machine types::
4635
4636         KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
4637         KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
4638         KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
4639         KERNEL_FEATURES:append:qemux86 = "  cfg/sound.scc cfg/paravirt_kvm.scc"
4640         KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"
4641
4642   :term:`KERNEL_FIT_LINK_NAME`
4643      The link name of the kernel flattened image tree (FIT) image. This
4644      variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
4645      file as follows::
4646
4647         KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4648
4649      The value of the
4650      ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
4651      file, has the following value::
4652
4653         KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4654
4655      See the :term:`MACHINE` variable for additional
4656      information.
4657
4658   :term:`KERNEL_FIT_NAME`
4659      The base name of the kernel flattened image tree (FIT) image. This
4660      variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
4661      file as follows::
4662
4663         KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4664
4665      See :term:`KERNEL_ARTIFACT_NAME` for additional information.
4666
4667   :term:`KERNEL_IMAGE_LINK_NAME`
4668      The link name for the kernel image. This variable is set in the
4669      ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
4670
4671         KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4672
4673      The value of
4674      the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
4675      file, has the following value::
4676
4677         KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4678
4679      See the :term:`MACHINE` variable for additional
4680      information.
4681
4682   :term:`KERNEL_IMAGE_MAXSIZE`
4683      Specifies the maximum size of the kernel image file in kilobytes. If
4684      :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is
4685      checked against the set value during the
4686      :ref:`ref-tasks-sizecheck` task. The task fails if
4687      the kernel image file is larger than the setting.
4688
4689      :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a
4690      limited amount of space in which the kernel image must be stored.
4691
4692      By default, this variable is not set, which means the size of the
4693      kernel image is not checked.
4694
4695   :term:`KERNEL_IMAGE_NAME`
4696      The base name of the kernel image. This variable is set in the
4697      ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
4698
4699         KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4700
4701      See :term:`KERNEL_ARTIFACT_NAME` for additional information.
4702
4703   :term:`KERNEL_IMAGETYPE`
4704      The type of kernel to build for a device, usually set by the machine
4705      configuration files and defaults to "zImage". This variable is used
4706      when building the kernel and is passed to ``make`` as the target to
4707      build.
4708
4709      To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`.
4710
4711   :term:`KERNEL_IMAGETYPES`
4712      Lists additional types of kernel images to build for a device in addition
4713      to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the
4714      machine configuration files.
4715
4716   :term:`KERNEL_MODULE_AUTOLOAD`
4717      Lists kernel modules that need to be auto-loaded during boot.
4718
4719      .. note::
4720
4721         This variable replaces the deprecated :term:`module_autoload`
4722         variable.
4723
4724      You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it
4725      can be recognized by the kernel recipe or by an out-of-tree kernel
4726      module recipe (e.g. a machine configuration file, a distribution
4727      configuration file, an append file for the recipe, or the recipe
4728      itself).
4729
4730      Specify it as follows::
4731
4732         KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
4733
4734      Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build
4735      system to populate the ``/etc/modules-load.d/modname.conf`` file with
4736      the list of modules to be auto-loaded on boot. The modules appear
4737      one-per-line in the file. Here is an example of the most common use
4738      case::
4739
4740         KERNEL_MODULE_AUTOLOAD += "module_name"
4741
4742      For information on how to populate the ``modname.conf`` file with
4743      ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable.
4744
4745   :term:`KERNEL_MODULE_PROBECONF`
4746      Provides a list of modules for which the OpenEmbedded build system
4747      expects to find ``module_conf_``\ modname values that specify
4748      configuration for each of the modules. For information on how to
4749      provide those module configurations, see the
4750      :term:`module_conf_* <module_conf>` variable.
4751
4752   :term:`KERNEL_PACKAGE_NAME`
4753      Specifies the base name of the kernel packages, such as "kernel"
4754      in the kernel packages such as "kernel-modules", "kernel-image" and
4755      "kernel-dbg".
4756
4757      The default value for this variable is set to "kernel" by the
4758      :ref:`ref-classes-kernel` class.
4759
4760   :term:`KERNEL_PATH`
4761      The location of the kernel sources. This variable is set to the value
4762      of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4763      class. For information on how this variable is used, see the
4764      ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
4765      section in the Yocto Project Linux Kernel Development Manual.
4766
4767      To help maximize compatibility with out-of-tree drivers used to build
4768      modules, the OpenEmbedded build system also recognizes and uses the
4769      :term:`KERNEL_SRC` variable, which is identical to
4770      the :term:`KERNEL_PATH` variable. Both variables are common variables
4771      used by external Makefiles to point to the kernel source directory.
4772
4773   :term:`KERNEL_SRC`
4774      The location of the kernel sources. This variable is set to the value
4775      of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4776      class. For information on how this variable is used, see the
4777      ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
4778      section in the Yocto Project Linux Kernel Development Manual.
4779
4780      To help maximize compatibility with out-of-tree drivers used to build
4781      modules, the OpenEmbedded build system also recognizes and uses the
4782      :term:`KERNEL_PATH` variable, which is identical
4783      to the :term:`KERNEL_SRC` variable. Both variables are common variables
4784      used by external Makefiles to point to the kernel source directory.
4785
4786   :term:`KERNEL_STRIP`
4787      Allows to specific which ``strip`` command to use to strip the kernel
4788      binary, typically either GNU binutils ``strip`` or ``llvm-strip``.
4789
4790   :term:`KERNEL_VERSION`
4791      Specifies the version of the kernel as extracted from ``version.h``
4792      or ``utsrelease.h`` within the kernel sources. Effects of setting
4793      this variable do not take effect until the kernel has been
4794      configured. Consequently, attempting to refer to this variable in
4795      contexts prior to configuration will not work.
4796
4797   :term:`KERNELDEPMODDEPEND`
4798      Specifies whether the data referenced through
4799      :term:`PKGDATA_DIR` is needed or not.
4800      :term:`KERNELDEPMODDEPEND` does not control whether or not that data
4801      exists, but simply whether or not it is used. If you do not need to
4802      use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
4803      :term:`Initramfs` recipe. Setting the variable there when the data is not
4804      needed avoids a potential dependency loop.
4805
4806   :term:`KFEATURE_DESCRIPTION`
4807      Provides a short description of a configuration fragment. You use
4808      this variable in the ``.scc`` file that describes a configuration
4809      fragment file. Here is the variable used in a file named ``smp.scc``
4810      to describe SMP being enabled::
4811
4812          define KFEATURE_DESCRIPTION "Enable SMP"
4813
4814   :term:`KMACHINE`
4815      The machine as known by the kernel. Sometimes the machine name used
4816      by the kernel does not match the machine name used by the
4817      OpenEmbedded build system. For example, the machine name that the
4818      OpenEmbedded build system understands as ``core2-32-intel-common``
4819      goes by a different name in the Linux Yocto kernel. The kernel
4820      understands that machine as ``intel-core2-32``. For cases like these,
4821      the :term:`KMACHINE` variable maps the kernel machine name to the
4822      OpenEmbedded build system machine name.
4823
4824      These mappings between different names occur in the Yocto Linux
4825      Kernel's ``meta`` branch. As an example take a look in the
4826      ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
4827
4828         LINUX_VERSION:core2-32-intel-common = "3.19.0"
4829         COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
4830         SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
4831         SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
4832         KMACHINE:core2-32-intel-common = "intel-core2-32"
4833         KBRANCH:core2-32-intel-common = "standard/base"
4834         KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}"
4835
4836      The :term:`KMACHINE` statement says
4837      that the kernel understands the machine name as "intel-core2-32".
4838      However, the OpenEmbedded build system understands the machine as
4839      "core2-32-intel-common".
4840
4841   :term:`KTYPE`
4842      Defines the kernel type to be used in assembling the configuration.
4843      The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
4844      kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
4845      section in the
4846      Yocto Project Linux Kernel Development Manual for more information on
4847      kernel types.
4848
4849      You define the :term:`KTYPE` variable in the
4850      :ref:`kernel-dev/advanced:bsp descriptions`. The
4851      value you use must match the value used for the
4852      :term:`LINUX_KERNEL_TYPE` value used by the
4853      kernel recipe.
4854
4855   :term:`LABELS`
4856      Provides a list of targets for automatic configuration.
4857
4858      See the :ref:`ref-classes-grub-efi` class for more
4859      information on how this variable is used.
4860
4861   :term:`LAYERDEPENDS`
4862      Lists the layers, separated by spaces, on which this recipe depends.
4863      Optionally, you can specify a specific layer version for a dependency
4864      by adding it to the end of the layer name. Here is an example::
4865
4866         LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4867
4868      In this previous example,
4869      version 3 of "anotherlayer" is compared against
4870      :term:`LAYERVERSION`\ ``_anotherlayer``.
4871
4872      An error is produced if any dependency is missing or the version
4873      numbers (if specified) do not match exactly. This variable is used in
4874      the ``conf/layer.conf`` file and must be suffixed with the name of
4875      the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
4876
4877   :term:`LAYERDIR`
4878      When used inside the ``layer.conf`` configuration file, this variable
4879      provides the path of the current layer. This variable is not
4880      available outside of ``layer.conf`` and references are expanded
4881      immediately when parsing of the file completes.
4882
4883   :term:`LAYERDIR_RE`
4884      See :term:`bitbake:LAYERDIR_RE` in the BitBake manual.
4885
4886   :term:`LAYERRECOMMENDS`
4887      Lists the layers, separated by spaces, recommended for use with this
4888      layer.
4889
4890      Optionally, you can specify a specific layer version for a
4891      recommendation by adding the version to the end of the layer name.
4892      Here is an example::
4893
4894         LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
4895
4896      In this previous example, version 3 of "anotherlayer" is compared
4897      against ``LAYERVERSION_anotherlayer``.
4898
4899      This variable is used in the ``conf/layer.conf`` file and must be
4900      suffixed with the name of the specific layer (e.g.
4901      ``LAYERRECOMMENDS_mylayer``).
4902
4903   :term:`LAYERSERIES_COMPAT`
4904      See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual.
4905
4906   :term:`LAYERVERSION`
4907      Optionally specifies the version of a layer as a single number. You
4908      can use this within :term:`LAYERDEPENDS` for
4909      another layer in order to depend on a specific version of the layer.
4910      This variable is used in the ``conf/layer.conf`` file and must be
4911      suffixed with the name of the specific layer (e.g.
4912      ``LAYERVERSION_mylayer``).
4913
4914   :term:`LD`
4915      The minimal command and arguments used to run the linker.
4916
4917   :term:`LDFLAGS`
4918      Specifies the flags to pass to the linker. This variable is exported
4919      to an environment variable and thus made visible to the software
4920      being built during the compilation step.
4921
4922      Default initialization for :term:`LDFLAGS` varies depending on what is
4923      being built:
4924
4925      -  :term:`TARGET_LDFLAGS` when building for the
4926         target
4927
4928      -  :term:`BUILD_LDFLAGS` when building for the
4929         build host (i.e. ``-native``)
4930
4931      -  :term:`BUILDSDK_LDFLAGS` when building for
4932         an SDK (i.e. ``nativesdk-``)
4933
4934   :term:`LEAD_SONAME`
4935      Specifies the lead (or primary) compiled library file (i.e. ``.so``)
4936      that the :ref:`ref-classes-debian` class applies its
4937      naming policy to given a recipe that packages multiple libraries.
4938
4939      This variable works in conjunction with the :ref:`ref-classes-debian`
4940      class.
4941
4942   :term:`LIC_FILES_CHKSUM`
4943      Checksums of the license text in the recipe source code.
4944
4945      This variable tracks changes in license text of the source code
4946      files. If the license text is changed, it will trigger a build
4947      failure, which gives the developer an opportunity to review any
4948      license change.
4949
4950      This variable must be defined for all recipes (unless
4951      :term:`LICENSE` is set to "CLOSED").
4952
4953      For more information, see the ":ref:`dev-manual/licenses:tracking license changes`"
4954      section in the Yocto Project Development Tasks Manual.
4955
4956   :term:`LICENSE`
4957      The list of source licenses for the recipe. Follow these rules:
4958
4959      -  Do not use spaces within individual license names.
4960
4961      -  Separate license names using \| (pipe) when there is a choice
4962         between licenses.
4963
4964      -  Separate license names using & (ampersand) when there are
4965         multiple licenses for different parts of the source.
4966
4967      -  You can use spaces between license names.
4968
4969      -  For standard licenses, use the names of the files in
4970         ``meta/files/common-licenses/`` or the
4971         :term:`SPDXLICENSEMAP` flag names defined in
4972         ``meta/conf/licenses.conf``.
4973
4974      Here are some examples::
4975
4976         LICENSE = "LGPL-2.1-only | GPL-3.0-only"
4977         LICENSE = "MPL-1.0 & LGPL-2.1-only"
4978         LICENSE = "GPL-2.0-or-later"
4979
4980      The first example is from the
4981      recipes for Qt, which the user may choose to distribute under either
4982      the LGPL version 2.1 or GPL version 3. The second example is from
4983      Cairo where two licenses cover different parts of the source code.
4984      The final example is from ``sysstat``, which presents a single
4985      license.
4986
4987      You can also specify licenses on a per-package basis to handle
4988      situations where components of the output have different licenses.
4989      For example, a piece of software whose code is licensed under GPLv2
4990      but has accompanying documentation licensed under the GNU Free
4991      Documentation License 1.2 could be specified as follows::
4992
4993         LICENSE = "GFDL-1.2 & GPL-2.0-only"
4994         LICENSE:${PN} = "GPL-2.0.only"
4995         LICENSE:${PN}-doc = "GFDL-1.2"
4996
4997   :term:`LICENSE_CREATE_PACKAGE`
4998      Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded
4999      build system to create an extra package (i.e.
5000      ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
5001      those packages to the
5002      :term:`RRECOMMENDS`\ ``:${PN}``.
5003
5004      The ``${PN}-lic`` package installs a directory in
5005      ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
5006      name, and installs files in that directory that contain license and
5007      copyright information (i.e. copies of the appropriate license files
5008      from ``meta/common-licenses`` that match the licenses specified in
5009      the :term:`LICENSE` variable of the recipe metadata
5010      and copies of files marked in
5011      :term:`LIC_FILES_CHKSUM` as containing
5012      license text).
5013
5014      For related information on providing license text, see the
5015      :term:`COPY_LIC_DIRS` variable, the
5016      :term:`COPY_LIC_MANIFEST` variable, and the
5017      ":ref:`dev-manual/licenses:providing license text`"
5018      section in the Yocto Project Development Tasks Manual.
5019
5020   :term:`LICENSE_FLAGS`
5021      Specifies additional flags for a recipe you must allow through
5022      :term:`LICENSE_FLAGS_ACCEPTED` in
5023      order for the recipe to be built. When providing multiple flags,
5024      separate them with spaces.
5025
5026      This value is independent of :term:`LICENSE` and is
5027      typically used to mark recipes that might require additional licenses
5028      in order to be used in a commercial product. For more information,
5029      see the
5030      ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
5031      section in the Yocto Project Development Tasks Manual.
5032
5033   :term:`LICENSE_FLAGS_ACCEPTED`
5034      Lists license flags that when specified in
5035      :term:`LICENSE_FLAGS` within a recipe should not
5036      prevent that recipe from being built.  For more information, see the
5037      ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
5038      section in the Yocto Project Development Tasks Manual.
5039
5040   :term:`LICENSE_FLAGS_DETAILS`
5041      Adds details about a flag in :term:`LICENSE_FLAGS`. This way,
5042      if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`,
5043      the error message will be more informative, containing the specified
5044      extra details.
5045
5046      For example, a recipe with an EULA may set::
5047
5048         LICENSE_FLAGS = "FooBar-EULA"
5049         LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula."
5050
5051      If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the
5052      error message is more useful::
5053
5054        Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED.
5055        For further details, see https://example.com/eula.
5056
5057   :term:`LICENSE_PATH`
5058      Path to additional licenses used during the build. By default, the
5059      OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
5060      directory that holds common license text used during the build. The
5061      :term:`LICENSE_PATH` variable allows you to extend that location to other
5062      areas that have additional licenses::
5063
5064         LICENSE_PATH += "path-to-additional-common-licenses"
5065
5066   :term:`LINUX_KERNEL_TYPE`
5067      Defines the kernel type to be used in assembling the configuration.
5068      The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
5069      kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
5070      section in the
5071      Yocto Project Linux Kernel Development Manual for more information on
5072      kernel types.
5073
5074      If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to
5075      "standard". Together with :term:`KMACHINE`, the
5076      :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by
5077      the kernel tools to find the appropriate description within the
5078      kernel :term:`Metadata` with which to build out the sources
5079      and configuration.
5080
5081   :term:`LINUX_VERSION`
5082      The Linux version from ``kernel.org`` on which the Linux kernel image
5083      being built using the OpenEmbedded build system is based. You define
5084      this variable in the kernel recipe. For example, the
5085      ``linux-yocto-3.4.bb`` kernel recipe found in
5086      ``meta/recipes-kernel/linux`` defines the variables as follows::
5087
5088         LINUX_VERSION ?= "3.4.24"
5089
5090      The :term:`LINUX_VERSION` variable is used to define :term:`PV`
5091      for the recipe::
5092
5093         PV = "${LINUX_VERSION}+git${SRCPV}"
5094
5095   :term:`LINUX_VERSION_EXTENSION`
5096      A string extension compiled into the version string of the Linux
5097      kernel built with the OpenEmbedded build system. You define this
5098      variable in the kernel recipe. For example, the linux-yocto kernel
5099      recipes all define the variable as follows::
5100
5101         LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
5102
5103      Defining this variable essentially sets the Linux kernel
5104      configuration item ``CONFIG_LOCALVERSION``, which is visible through
5105      the ``uname`` command. Here is an example that shows the extension
5106      assuming it was set as previously shown::
5107
5108         $ uname -r
5109         3.7.0-rc8-custom
5110
5111   :term:`LOG_DIR`
5112      Specifies the directory to which the OpenEmbedded build system writes
5113      overall log files. The default directory is ``${TMPDIR}/log``.
5114
5115      For the directory containing logs specific to each task, see the
5116      :term:`T` variable.
5117
5118   :term:`MACHINE`
5119      Specifies the target device for which the image is built. You define
5120      :term:`MACHINE` in the ``local.conf`` file found in the
5121      :term:`Build Directory`. By default, :term:`MACHINE` is set to
5122      "qemux86", which is an x86-based architecture machine to be emulated
5123      using QEMU::
5124
5125         MACHINE ?= "qemux86"
5126
5127      The variable corresponds to a machine configuration file of the same
5128      name, through which machine-specific configurations are set. Thus,
5129      when :term:`MACHINE` is set to "qemux86", the corresponding
5130      ``qemux86.conf`` machine configuration file can be found in
5131      the :term:`Source Directory` in
5132      ``meta/conf/machine``.
5133
5134      The list of machines supported by the Yocto Project as shipped
5135      include the following::
5136
5137         MACHINE ?= "qemuarm"
5138         MACHINE ?= "qemuarm64"
5139         MACHINE ?= "qemumips"
5140         MACHINE ?= "qemumips64"
5141         MACHINE ?= "qemuppc"
5142         MACHINE ?= "qemux86"
5143         MACHINE ?= "qemux86-64"
5144         MACHINE ?= "genericx86"
5145         MACHINE ?= "genericx86-64"
5146         MACHINE ?= "beaglebone"
5147
5148      The last five are Yocto Project reference hardware
5149      boards, which are provided in the ``meta-yocto-bsp`` layer.
5150
5151      .. note::
5152
5153         Adding additional Board Support Package (BSP) layers to your
5154         configuration adds new possible settings for :term:`MACHINE`.
5155
5156   :term:`MACHINE_ARCH`
5157      Specifies the name of the machine-specific architecture. This
5158      variable is set automatically from :term:`MACHINE` or
5159      :term:`TUNE_PKGARCH`. You should not hand-edit
5160      the :term:`MACHINE_ARCH` variable.
5161
5162   :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
5163      A list of required machine-specific packages to install as part of
5164      the image being built. The build process depends on these packages
5165      being present. Furthermore, because this is a "machine-essential"
5166      variable, the list of packages are essential for the machine to boot.
5167      The impact of this variable affects images based on
5168      ``packagegroup-core-boot``, including the ``core-image-minimal``
5169      image.
5170
5171      This variable is similar to the
5172      :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception
5173      that the image being built has a build dependency on the variable's
5174      list of packages. In other words, the image will not build if a file
5175      in this list is not found.
5176
5177      As an example, suppose the machine for which you are building
5178      requires ``example-init`` to be run during boot to initialize the
5179      hardware. In this case, you would use the following in the machine's
5180      ``.conf`` configuration file::
5181
5182         MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
5183
5184   :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
5185      A list of recommended machine-specific packages to install as part of
5186      the image being built. The build process does not depend on these
5187      packages being present. However, because this is a
5188      "machine-essential" variable, the list of packages are essential for
5189      the machine to boot. The impact of this variable affects images based
5190      on ``packagegroup-core-boot``, including the ``core-image-minimal``
5191      image.
5192
5193      This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
5194      variable with the exception that the image being built does not have
5195      a build dependency on the variable's list of packages. In other
5196      words, the image will still build if a package in this list is not
5197      found. Typically, this variable is used to handle essential kernel
5198      modules, whose functionality may be selected to be built into the
5199      kernel rather than as a module, in which case a package will not be
5200      produced.
5201
5202      Consider an example where you have a custom kernel where a specific
5203      touchscreen driver is required for the machine to be usable. However,
5204      the driver can be built as a module or into the kernel depending on
5205      the kernel configuration. If the driver is built as a module, you
5206      want it to be installed. But, when the driver is built into the
5207      kernel, you still want the build to succeed. This variable sets up a
5208      "recommends" relationship so that in the latter case, the build will
5209      not fail due to the missing package. To accomplish this, assuming the
5210      package for the module was called ``kernel-module-ab123``, you would
5211      use the following in the machine's ``.conf`` configuration file::
5212
5213         MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
5214
5215      .. note::
5216
5217         In this example, the ``kernel-module-ab123`` recipe needs to
5218         explicitly set its :term:`PACKAGES` variable to ensure that BitBake
5219         does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to
5220         satisfy the dependency.
5221
5222      Some examples of these machine essentials are flash, screen,
5223      keyboard, mouse, or touchscreen drivers (depending on the machine).
5224
5225   :term:`MACHINE_EXTRA_RDEPENDS`
5226      A list of machine-specific packages to install as part of the image
5227      being built that are not essential for the machine to boot. However,
5228      the build process for more fully-featured images depends on the
5229      packages being present.
5230
5231      This variable affects all images based on ``packagegroup-base``,
5232      which does not include the ``core-image-minimal`` or
5233      ``core-image-full-cmdline`` images.
5234
5235      The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable
5236      with the exception that the image being built has a build dependency
5237      on the variable's list of packages. In other words, the image will
5238      not build if a file in this list is not found.
5239
5240      An example is a machine that has WiFi capability but is not essential
5241      for the machine to boot the image. However, if you are building a
5242      more fully-featured image, you want to enable the WiFi. The package
5243      containing the firmware for the WiFi hardware is always expected to
5244      exist, so it is acceptable for the build process to depend upon
5245      finding the package. In this case, assuming the package for the
5246      firmware was called ``wifidriver-firmware``, you would use the
5247      following in the ``.conf`` file for the machine::
5248
5249         MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
5250
5251   :term:`MACHINE_EXTRA_RRECOMMENDS`
5252      A list of machine-specific packages to install as part of the image
5253      being built that are not essential for booting the machine. The image
5254      being built has no build dependency on this list of packages.
5255
5256      This variable affects only images based on ``packagegroup-base``,
5257      which does not include the ``core-image-minimal`` or
5258      ``core-image-full-cmdline`` images.
5259
5260      This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable
5261      with the exception that the image being built does not have a build
5262      dependency on the variable's list of packages. In other words, the
5263      image will build if a file in this list is not found.
5264
5265      An example is a machine that has WiFi capability but is not essential
5266      For the machine to boot the image. However, if you are building a
5267      more fully-featured image, you want to enable WiFi. In this case, the
5268      package containing the WiFi kernel module will not be produced if the
5269      WiFi driver is built into the kernel, in which case you still want
5270      the build to succeed instead of failing as a result of the package
5271      not being found. To accomplish this, assuming the package for the
5272      module was called ``kernel-module-examplewifi``, you would use the
5273      following in the ``.conf`` file for the machine::
5274
5275         MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
5276
5277   :term:`MACHINE_FEATURES`
5278      Specifies the list of hardware features the
5279      :term:`MACHINE` is capable of supporting. For related
5280      information on enabling features, see the
5281      :term:`DISTRO_FEATURES`,
5282      :term:`COMBINED_FEATURES`, and
5283      :term:`IMAGE_FEATURES` variables.
5284
5285      For a list of hardware features supported by the Yocto Project as
5286      shipped, see the ":ref:`ref-features-machine`" section.
5287
5288   :term:`MACHINE_FEATURES_BACKFILL`
5289      A list of space-separated features to be added to
5290      :term:`MACHINE_FEATURES` if not also present in
5291      :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
5292
5293      This variable is set in the ``meta/conf/bitbake.conf`` file. It is not
5294      intended to be user-configurable. It is best to just reference the
5295      variable to see which machine features are being
5296      :ref:`backfilled <ref-features-backfill>` for all machine configurations.
5297
5298   :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
5299      A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL`
5300      that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
5301      to :term:`MACHINE_FEATURES`) during the build.
5302
5303      This corresponds to an opt-out mechanism. When new default machine
5304      features are introduced, machine definition maintainers can review
5305      (`consider`) them and decide to exclude them from the
5306      :ref:`backfilled <ref-features-backfill>` features. Therefore, the
5307      combination of :term:`MACHINE_FEATURES_BACKFILL` and
5308      :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to
5309      add new default features without breaking existing machine definitions.
5310
5311   :term:`MACHINEOVERRIDES`
5312      A colon-separated list of overrides that apply to the current
5313      machine. By default, this list includes the value of
5314      :term:`MACHINE`.
5315
5316      You can extend :term:`MACHINEOVERRIDES` to add extra overrides that
5317      should apply to a machine. For example, all machines emulated in QEMU
5318      (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
5319      ``meta/conf/machine/include/qemu.inc`` that prepends the following
5320      override to :term:`MACHINEOVERRIDES`::
5321
5322         MACHINEOVERRIDES =. "qemuall:"
5323
5324      This
5325      override allows variables to be overridden for all machines emulated
5326      in QEMU, like in the following example from the ``connman-conf``
5327      recipe::
5328
5329         SRC_URI:append:qemuall = " file://wired.config \
5330             file://wired-setup \
5331             "
5332
5333      The underlying mechanism behind
5334      :term:`MACHINEOVERRIDES` is simply that it is included in the default
5335      value of :term:`OVERRIDES`.
5336
5337   :term:`MAINTAINER`
5338      The email address of the distribution maintainer.
5339
5340   :term:`MESON_BUILDTYPE`
5341      Value of the Meson ``--buildtype`` argument used by the
5342      :ref:`ref-classes-meson` class. It defaults to ``debug`` if
5343      :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise.
5344
5345      See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__
5346      for the values you could set in a recipe. Values such as ``plain``,
5347      ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow
5348      you to specify the inclusion of debugging symbols and the compiler
5349      optimizations (none, performance or size).
5350
5351   :term:`MESON_TARGET`
5352      A variable for the :ref:`ref-classes-meson` class, allowing to choose
5353      a Meson target to build in :ref:`ref-tasks-compile`.  Otherwise, the
5354      default targets are built.
5355
5356   :term:`METADATA_BRANCH`
5357      The branch currently checked out for the OpenEmbedded-Core layer (path
5358      determined by :term:`COREBASE`).
5359
5360   :term:`METADATA_REVISION`
5361      The revision currently checked out for the OpenEmbedded-Core layer (path
5362      determined by :term:`COREBASE`).
5363
5364   :term:`MIME_XDG_PACKAGES`
5365      The current implementation of the :ref:`ref-classes-mime-xdg`
5366      class cannot detect ``.desktop`` files installed through absolute
5367      symbolic links. Use this setting to make the class create post-install
5368      and post-remove scripts for these packages anyway, to invoke the
5369      ``update-destop-database`` command.
5370
5371   :term:`MIRRORS`
5372      Specifies additional paths from which the OpenEmbedded build system
5373      gets source code. When the build system searches for source code, it
5374      first tries the local download directory. If that location fails, the
5375      build system tries locations defined by
5376      :term:`PREMIRRORS`, the upstream source, and then
5377      locations specified by :term:`MIRRORS` in that order.
5378
5379      The default value for :term:`MIRRORS` is defined in the
5380      ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
5381
5382   :term:`MLPREFIX`
5383      Specifies a prefix has been added to :term:`PN` to create a
5384      special version of a recipe or package (i.e. a Multilib version). The
5385      variable is used in places where the prefix needs to be added to or
5386      removed from a name (e.g. the :term:`BPN` variable).
5387      :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`.
5388
5389      .. note::
5390
5391         The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation
5392         is historical and comes from a time when ":ref:`ref-classes-nativesdk`"
5393         was a suffix rather than a prefix on the recipe name. When
5394         ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense
5395         to set :term:`MLPREFIX` for it as well.
5396
5397      To help understand when :term:`MLPREFIX` might be needed, consider when
5398      :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk`
5399      version of a recipe in addition to the target version. If that recipe
5400      declares build-time dependencies on tasks in other recipes by using
5401      :term:`DEPENDS`, then a dependency on "foo" will automatically get
5402      rewritten to a dependency on "nativesdk-foo". However, dependencies like
5403      the following will not get rewritten automatically::
5404
5405         do_foo[depends] += "recipe:do_foo"
5406
5407      If you want such a dependency to also get transformed, you can do the
5408      following::
5409
5410         do_foo[depends] += "${MLPREFIX}recipe:do_foo"
5411
5412   :term:`module_autoload`
5413      This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
5414      variable. You should replace all occurrences of :term:`module_autoload`
5415      with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
5416
5417         module_autoload_rfcomm = "rfcomm"
5418
5419      should now be replaced with::
5420
5421         KERNEL_MODULE_AUTOLOAD += "rfcomm"
5422
5423      See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
5424
5425   :term:`module_conf`
5426      Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__
5427      syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
5428      file.
5429
5430      You can use this variable anywhere that it can be recognized by the
5431      kernel recipe or out-of-tree kernel module recipe (e.g. a machine
5432      configuration file, a distribution configuration file, an append file
5433      for the recipe, or the recipe itself). If you use this variable, you
5434      must also be sure to list the module name in the
5435      :term:`KERNEL_MODULE_PROBECONF`
5436      variable.
5437
5438      Here is the general syntax::
5439
5440         module_conf_module_name = "modprobe.d-syntax"
5441
5442      You must use the kernel module name override.
5443
5444      Run ``man modprobe.d`` in the shell to find out more information on
5445      the exact syntax you want to provide with :term:`module_conf`.
5446
5447      Including :term:`module_conf` causes the OpenEmbedded build system to
5448      populate the ``/etc/modprobe.d/modname.conf`` file with
5449      ``modprobe.d`` syntax lines. Here is an example that adds the options
5450      ``arg1`` and ``arg2`` to a module named ``mymodule``::
5451
5452         module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
5453
5454      For information on how to specify kernel modules to auto-load on
5455      boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable.
5456
5457   :term:`MODULE_TARBALL_DEPLOY`
5458      Controls creation of the ``modules-*.tgz`` file. Set this variable to
5459      "0" to disable creation of this file, which contains all of the
5460      kernel modules resulting from a kernel build.
5461
5462   :term:`MODULE_TARBALL_LINK_NAME`
5463      The link name of the kernel module tarball. This variable is set in
5464      the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
5465
5466         MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
5467
5468      The value
5469      of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
5470      same file, has the following value::
5471
5472         KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
5473
5474      See the :term:`MACHINE` variable for additional information.
5475
5476   :term:`MODULE_TARBALL_NAME`
5477      The base name of the kernel module tarball. This variable is set in
5478      the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
5479
5480         MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
5481
5482      See :term:`KERNEL_ARTIFACT_NAME` for additional information.
5483
5484   :term:`MOUNT_BASE`
5485      On non-systemd systems (where ``udev-extraconf`` is being used),
5486      specifies the base directory for auto-mounting filesystems. The
5487      default value is "/run/media".
5488
5489   :term:`MULTIMACH_TARGET_SYS`
5490      Uniquely identifies the type of the target system for which packages
5491      are being built. This variable allows output for different types of
5492      target systems to be put into different subdirectories of the same
5493      output directory.
5494
5495      The default value of this variable is::
5496
5497         ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
5498
5499      Some classes (e.g.  :ref:`ref-classes-cross-canadian`) modify the
5500      :term:`MULTIMACH_TARGET_SYS` value.
5501
5502      See the :term:`STAMP` variable for an example. See the
5503      :term:`STAGING_DIR_TARGET` variable for more information.
5504
5505   :term:`NATIVELSBSTRING`
5506      A string identifying the host distribution. Strings consist of the
5507      host distributor ID followed by the release, as reported by the
5508      ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
5509      example, when running a build on Ubuntu 12.10, the value is
5510      "Ubuntu-12.10". If this information is unable to be determined, the
5511      value resolves to "Unknown".
5512
5513      This variable is used by default to isolate native shared state
5514      packages for different distributions (e.g. to avoid problems with
5515      ``glibc`` version incompatibilities). Additionally, the variable is
5516      checked against
5517      :term:`SANITY_TESTED_DISTROS` if that
5518      variable is set.
5519
5520   :term:`NM`
5521      The minimal command and arguments to run ``nm``.
5522
5523   :term:`NO_GENERIC_LICENSE`
5524      Avoids QA errors when you use a non-common, non-CLOSED license in a
5525      recipe. There are packages, such as the linux-firmware package, with many
5526      licenses that are not in any way common. Also, new licenses are added
5527      occasionally to avoid introducing a lot of common license files,
5528      which are only applicable to a specific package.
5529      :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does
5530      not exist in common licenses.
5531
5532      The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
5533      recipe::
5534
5535         NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
5536
5537      Here is an example that
5538      uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
5539      source::
5540
5541         NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
5542
5543   :term:`NO_RECOMMENDATIONS`
5544      Prevents installation of all "recommended-only" packages.
5545      Recommended-only packages are packages installed only through the
5546      :term:`RRECOMMENDS` variable). Setting the
5547      :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
5548
5549         NO_RECOMMENDATIONS = "1"
5550
5551      You can set this variable globally in your ``local.conf`` file or you
5552      can attach it to a specific image recipe by using the recipe name
5553      override::
5554
5555         NO_RECOMMENDATIONS:pn-target_image = "1"
5556
5557      It is important to realize that if you choose to not install packages
5558      using this variable and some other packages are dependent on them
5559      (i.e. listed in a recipe's :term:`RDEPENDS`
5560      variable), the OpenEmbedded build system ignores your request and
5561      will install the packages to avoid dependency errors.
5562
5563      .. note::
5564
5565         Some recommended packages might be required for certain system
5566         functionality, such as kernel modules. It is up to you to add
5567         packages with the :term:`IMAGE_INSTALL` variable.
5568
5569      This variable is only supported when using the IPK and RPM
5570      packaging backends. DEB is not supported.
5571
5572      See the :term:`BAD_RECOMMENDATIONS` and
5573      the :term:`PACKAGE_EXCLUDE` variables for
5574      related information.
5575
5576   :term:`NOAUTOPACKAGEDEBUG`
5577      Disables auto package from splitting ``.debug`` files. If a recipe
5578      requires ``FILES:${PN}-dbg`` to be set manually, the
5579      :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
5580      content of the debug package. For example::
5581
5582         NOAUTOPACKAGEDEBUG = "1"
5583         FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
5584         FILES:${PN}-dbg = "/usr/src/debug/"
5585         FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
5586
5587   :term:`NON_MULTILIB_RECIPES`
5588      A list of recipes that should not be built for multilib. OE-Core's
5589      ``multilib.conf`` file defines a reasonable starting point for this
5590      list with::
5591
5592         NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
5593
5594   :term:`NVDCVE_API_KEY`
5595      The NVD API key used to retrieve data from the CVE database when
5596      using :ref:`ref-classes-cve-check`.
5597
5598      By default, no API key is used, which results in larger delays between API
5599      requests and limits the number of queries to the public rate limits posted
5600      at the `NVD developer's page <https://nvd.nist.gov/developers/start-here>`__.
5601
5602      NVD API keys can be requested through the
5603      `Request an API Key <https://nvd.nist.gov/developers/request-an-api-key>`__
5604      page. You can set this variable to the NVD API key in your ``local.conf`` file.
5605      Example::
5606
5607          NVDCVE_API_KEY = "fe753&7a2-1427-347d-23ff-b2e2b7ca5f3"
5608
5609   :term:`OBJCOPY`
5610      The minimal command and arguments to run ``objcopy``.
5611
5612   :term:`OBJDUMP`
5613      The minimal command and arguments to run ``objdump``.
5614
5615   :term:`OE_BINCONFIG_EXTRA_MANGLE`
5616      When inheriting the :ref:`ref-classes-binconfig` class,
5617      this variable specifies additional arguments passed to the "sed"
5618      command. The sed command alters any paths in configuration scripts
5619      that have been set up during compilation. Inheriting this class
5620      results in all paths in these scripts being changed to point into the
5621      ``sysroots/`` directory so that all builds that use the script will
5622      use the correct directories for the cross compiling layout.
5623
5624      See the ``meta/classes-recipe/binconfig.bbclass`` in the
5625      :term:`Source Directory` for details on how this class
5626      applies these additional sed command arguments.
5627
5628   :term:`OECMAKE_GENERATOR`
5629      A variable for the :ref:`ref-classes-cmake` class, allowing to choose
5630      which back-end will be generated by CMake to build an application.
5631
5632      By default, this variable is set to ``Ninja``, which is faster than GNU
5633      make, but if building is broken with Ninja, a recipe can use this
5634      variable to use GNU make instead::
5635
5636         OECMAKE_GENERATOR = "Unix Makefiles"
5637
5638   :term:`OE_IMPORTS`
5639      An internal variable used to tell the OpenEmbedded build system what
5640      Python modules to import for every Python function run by the system.
5641
5642      .. note::
5643
5644         Do not set this variable. It is for internal use only.
5645
5646   :term:`OE_INIT_ENV_SCRIPT`
5647      The name of the build environment setup script for the purposes of
5648      setting up the environment within the extensible SDK. The default
5649      value is "oe-init-build-env".
5650
5651      If you use a custom script to set up your build environment, set the
5652      :term:`OE_INIT_ENV_SCRIPT` variable to its name.
5653
5654   :term:`OE_TERMINAL`
5655      Controls how the OpenEmbedded build system spawns interactive
5656      terminals on the host development system (e.g. using the BitBake
5657      command with the ``-c devshell`` command-line option). For more
5658      information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in
5659      the Yocto Project Development Tasks Manual.
5660
5661      You can use the following values for the :term:`OE_TERMINAL` variable:
5662
5663      - auto
5664      - gnome
5665      - xfce
5666      - rxvt
5667      - screen
5668      - konsole
5669      - none
5670
5671   :term:`OEROOT`
5672      The directory from which the top-level build environment setup script
5673      is sourced. The Yocto Project provides a top-level build environment
5674      setup script: :ref:`structure-core-script`. When you run this
5675      script, the :term:`OEROOT` variable resolves to the directory that
5676      contains the script.
5677
5678      For additional information on how this variable is used, see the
5679      initialization script.
5680
5681   :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE`
5682      Set the package manager(s) for build reproducibility testing.
5683      See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`
5684      and :doc:`/test-manual/reproducible-builds`.
5685
5686   :term:`OEQA_REPRODUCIBLE_TEST_TARGET`
5687      Set build target for build reproducibility testing. By default
5688      all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD`
5689      and :doc:`/test-manual/reproducible-builds`.
5690
5691   :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS`
5692      Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>`
5693      when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`.
5694
5695   :term:`OLDEST_KERNEL`
5696      Declares the oldest version of the Linux kernel that the produced
5697      binaries must support. This variable is passed into the build of the
5698      Embedded GNU C Library (``glibc``).
5699
5700      The default for this variable comes from the
5701      ``meta/conf/bitbake.conf`` configuration file. You can override this
5702      default by setting the variable in a custom distribution
5703      configuration file.
5704
5705   :term:`OPKG_MAKE_INDEX_EXTRA_PARAMS`
5706      Specifies extra parameters for the ``opkg-make-index`` command.
5707
5708   :term:`OVERLAYFS_ETC_DEVICE`
5709      When the :ref:`ref-classes-overlayfs-etc` class is
5710      inherited, specifies the device to be mounted for the read/write
5711      layer of ``/etc``. There is no default, so you must set this if you
5712      wish to enable :ref:`ref-classes-overlayfs-etc`, for
5713      example, assuming ``/dev/mmcblk0p2`` was the desired device::
5714
5715         OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
5716
5717   :term:`OVERLAYFS_ETC_EXPOSE_LOWER`
5718      When the :ref:`ref-classes-overlayfs-etc` class is
5719      inherited, if set to "1" then a read-only access to the original
5720      ``/etc`` content will be provided as a ``lower/`` subdirectory of
5721      :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0".
5722
5723   :term:`OVERLAYFS_ETC_FSTYPE`
5724      When the :ref:`ref-classes-overlayfs-etc` class is
5725      inherited, specifies the file system type for the read/write
5726      layer of ``/etc``. There is no default, so you must set this if you
5727      wish to enable :ref:`ref-classes-overlayfs-etc`,
5728      for example, assuming the file system is ext4::
5729
5730         OVERLAYFS_ETC_FSTYPE = "ext4"
5731
5732   :term:`OVERLAYFS_ETC_MOUNT_OPTIONS`
5733      When the :ref:`ref-classes-overlayfs-etc` class is
5734      inherited, specifies the mount options for the read-write layer.
5735      The default value is "defaults".
5736
5737   :term:`OVERLAYFS_ETC_MOUNT_POINT`
5738      When the :ref:`ref-classes-overlayfs-etc` class is
5739      inherited, specifies the parent mount path for the filesystem layers.
5740      There is no default, so you must set this if you wish to enable
5741      :ref:`ref-classes-overlayfs-etc`, for example if the desired path is
5742      "/data"::
5743
5744         OVERLAYFS_ETC_MOUNT_POINT = "/data"
5745
5746   :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME`
5747      When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls
5748      how the generated init will be named. For more information, see the
5749      :ref:`ref-classes-overlayfs-etc` class documentation. The default value
5750      is "1".
5751
5752   :term:`OVERLAYFS_MOUNT_POINT`
5753      When inheriting the :ref:`ref-classes-overlayfs` class,
5754      specifies mount point(s) to be used. For example::
5755
5756         OVERLAYFS_MOUNT_POINT[data] = "/data"
5757
5758      The assumes you have a ``data.mount`` systemd unit defined elsewhere in
5759      your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed
5760      into the image. For more information see :ref:`ref-classes-overlayfs`.
5761
5762      .. note::
5763
5764         Although the :ref:`ref-classes-overlayfs` class is
5765         inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT`
5766         should be set in your machine configuration.
5767
5768   :term:`OVERLAYFS_QA_SKIP`
5769      When inheriting the :ref:`ref-classes-overlayfs` class,
5770      provides the ability to disable QA checks for particular overlayfs
5771      mounts. For example::
5772
5773         OVERLAYFS_QA_SKIP[data] = "mount-configured"
5774
5775      .. note::
5776
5777         Although the :ref:`ref-classes-overlayfs` class is
5778         inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP`
5779         should be set in your machine configuration.
5780
5781   :term:`OVERLAYFS_WRITABLE_PATHS`
5782      When inheriting the :ref:`ref-classes-overlayfs` class,
5783      specifies writable paths used at runtime for the recipe. For
5784      example::
5785
5786         OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
5787
5788   :term:`OVERRIDES`
5789      A colon-separated list of overrides that currently apply. Overrides
5790      are a BitBake mechanism that allows variables to be selectively
5791      overridden at the end of parsing. The set of overrides in
5792      :term:`OVERRIDES` represents the "state" during building, which includes
5793      the current recipe being built, the machine for which it is being
5794      built, and so forth.
5795
5796      As an example, if the string "an-override" appears as an element in
5797      the colon-separated list in :term:`OVERRIDES`, then the following
5798      assignment will override ``FOO`` with the value "overridden" at the
5799      end of parsing::
5800
5801         FOO:an-override = "overridden"
5802
5803      See the
5804      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
5805      section in the BitBake User Manual for more information on the
5806      overrides mechanism.
5807
5808      The default value of :term:`OVERRIDES` includes the values of the
5809      :term:`CLASSOVERRIDE`,
5810      :term:`MACHINEOVERRIDES`, and
5811      :term:`DISTROOVERRIDES` variables. Another
5812      important override included by default is ``pn-${PN}``. This override
5813      allows variables to be set for a single recipe within configuration
5814      (``.conf``) files. Here is an example::
5815
5816         FOO:pn-myrecipe = "myrecipe-specific value"
5817
5818      .. note::
5819
5820         An easy way to see what overrides apply is to search for :term:`OVERRIDES`
5821         in the output of the ``bitbake -e`` command. See the
5822         ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto
5823         Project Development Tasks Manual for more information.
5824
5825   :term:`P`
5826      The recipe name and version. :term:`P` is comprised of the following::
5827
5828         ${PN}-${PV}
5829
5830   :term:`P4DIR`
5831      See :term:`bitbake:P4DIR` in the BitBake manual.
5832
5833   :term:`PACKAGE_ADD_METADATA`
5834      This variable defines additional metadata to add to packages.
5835
5836      You may find you need to inject additional metadata into packages.
5837      This variable allows you to do that by setting the injected data as
5838      the value. Multiple fields can be added by splitting the content with
5839      the literal separator "\n".
5840
5841      The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
5842      to do package type specific settings. It can also be made package
5843      specific by using the package name as a suffix.
5844
5845      You can find out more about applying this variable in the
5846      ":ref:`dev-manual/packages:adding custom metadata to packages`"
5847      section in the Yocto Project Development Tasks Manual.
5848
5849   :term:`PACKAGE_ARCH`
5850      The architecture of the resulting package or packages.
5851
5852      By default, the value of this variable is set to
5853      :term:`TUNE_PKGARCH` when building for the
5854      target, :term:`BUILD_ARCH` when building for the
5855      build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
5856      SDK.
5857
5858      .. note::
5859
5860         See :term:`SDK_ARCH` for more information.
5861
5862      However, if your recipe's output packages are built specific to the
5863      target machine rather than generally for the architecture of the
5864      machine, you should set :term:`PACKAGE_ARCH` to the value of
5865      :term:`MACHINE_ARCH` in the recipe as follows::
5866
5867         PACKAGE_ARCH = "${MACHINE_ARCH}"
5868
5869   :term:`PACKAGE_ARCHS`
5870      Specifies a list of architectures compatible with the target machine.
5871      This variable is set automatically and should not normally be
5872      hand-edited. Entries are separated using spaces and listed in order
5873      of priority. The default value for :term:`PACKAGE_ARCHS` is "all any
5874      noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5875
5876   :term:`PACKAGE_BEFORE_PN`
5877      Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so
5878      that those added packages can pick up files that would normally be
5879      included in the default package.
5880
5881   :term:`PACKAGE_CLASSES`
5882      This variable, which is set in the ``local.conf`` configuration file
5883      found in the ``conf`` folder of the
5884      :term:`Build Directory`, specifies the package manager the
5885      OpenEmbedded build system uses when packaging data.
5886
5887      You can provide one or more of the following arguments for the
5888      variable::
5889
5890         PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
5891
5892      The build system uses only the first argument in the list as the
5893      package manager when creating your image or SDK. However, packages
5894      will be created using any additional packaging classes you specify.
5895      For example, if you use the following in your ``local.conf`` file::
5896
5897         PACKAGE_CLASSES ?= "package_ipk"
5898
5899      The OpenEmbedded build system uses
5900      the IPK package manager to create your image or SDK.
5901
5902      For information on packaging and build performance effects as a
5903      result of the package manager in use, see the
5904      ":ref:`ref-classes-package`" section.
5905
5906   :term:`PACKAGE_DEBUG_SPLIT_STYLE`
5907      Determines how to split up and package debug and source information
5908      when creating debugging packages to be used with the GNU Project
5909      Debugger (GDB). In general, based on the value of this variable,
5910      you can combine the source and debug info in a single package,
5911      you can break out the source into a separate package that can be
5912      installed independently, or you can choose to not have the source
5913      packaged at all.
5914
5915      The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
5916
5917      -  "``.debug``": All debugging and source info is placed in a single
5918         ``*-dbg`` package; debug symbol files are placed next to the
5919         binary in a ``.debug`` directory so that, if a binary is installed
5920         into ``/bin``, the corresponding debug symbol file is installed
5921         in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
5922         package under ``/usr/src/debug``.
5923
5924      -  "``debug-file-directory``": As above, all debugging and source info
5925         is placed in a single ``*-dbg`` package; debug symbol files are
5926         placed entirely under the directory ``/usr/lib/debug`` and separated
5927         by the path from where the binary is installed, so that if a binary
5928         is installed in ``/bin``, the corresponding debug symbols are installed
5929         in ``/usr/lib/debug/bin``, and so on. As above, source is installed
5930         in the same package under ``/usr/src/debug``.
5931
5932      -  "``debug-with-srcpkg``": Debugging info is placed in the standard
5933         ``*-dbg`` package as with the ``.debug`` value, while source is
5934         placed in a separate ``*-src`` package, which can be installed
5935         independently.  This is the default setting for this variable,
5936         as defined in Poky's ``bitbake.conf`` file.
5937
5938      -  "``debug-without-src``": The same behavior as with the ``.debug``
5939         setting, but no source is packaged at all.
5940
5941      .. note::
5942
5943         Much of the above package splitting can be overridden via
5944         use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable.
5945
5946      You can find out more about debugging using GDB by reading the
5947      ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section
5948      in the Yocto Project Development Tasks Manual.
5949
5950   :term:`PACKAGE_EXCLUDE`
5951      Lists packages that should not be installed into an image. For
5952      example::
5953
5954         PACKAGE_EXCLUDE = "package_name package_name package_name ..."
5955
5956      You can set this variable globally in your ``local.conf`` file or you
5957      can attach it to a specific image recipe by using the recipe name
5958      override::
5959
5960         PACKAGE_EXCLUDE:pn-target_image = "package_name"
5961
5962      If you choose to not install a package using this variable and some
5963      other package is dependent on it (i.e. listed in a recipe's
5964      :term:`RDEPENDS` variable), the OpenEmbedded build
5965      system generates a fatal installation error. Because the build system
5966      halts the process with a fatal error, you can use the variable with
5967      an iterative development process to remove specific components from a
5968      system.
5969
5970      This variable is supported only when using the IPK and RPM
5971      packaging backends. DEB is not supported.
5972
5973      See the :term:`NO_RECOMMENDATIONS` and the
5974      :term:`BAD_RECOMMENDATIONS` variables for
5975      related information.
5976
5977   :term:`PACKAGE_EXCLUDE_COMPLEMENTARY`
5978      Prevents specific packages from being installed when you are
5979      installing complementary packages.
5980
5981      You might find that you want to prevent installing certain packages
5982      when you are installing complementary packages. For example, if you
5983      are using :term:`IMAGE_FEATURES` to install
5984      ``dev-pkgs``, you might not want to install all packages from a
5985      particular multilib. If you find yourself in this situation, you can
5986      use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular
5987      expressions to match the packages you want to exclude.
5988
5989   :term:`PACKAGE_EXTRA_ARCHS`
5990      Specifies the list of architectures compatible with the device CPU.
5991      This variable is useful when you build for several different devices
5992      that use miscellaneous processors such as XScale and ARM926-EJS.
5993
5994   :term:`PACKAGE_FEED_ARCHS`
5995      Optionally specifies the package architectures used as part of the
5996      package feed URIs during the build. When used, the
5997      :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed
5998      URI, which is constructed using the
5999      :term:`PACKAGE_FEED_URIS` and
6000      :term:`PACKAGE_FEED_BASE_PATHS`
6001      variables.
6002
6003      .. note::
6004
6005         You can use the :term:`PACKAGE_FEED_ARCHS`
6006         variable to allow specific package architectures. If you do
6007         not need to allow specific architectures, which is a common
6008         case, you can omit this variable. Omitting the variable results in
6009         all available architectures for the current machine being included
6010         into remote package feeds.
6011
6012      Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6013      :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
6014      defined in your ``local.conf`` file::
6015
6016         PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6017                              https://example.com/packagerepos/updates"
6018         PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6019         PACKAGE_FEED_ARCHS = "all core2-64"
6020
6021      Given these settings, the resulting package feeds are as follows:
6022
6023      .. code-block:: none
6024
6025         https://example.com/packagerepos/release/rpm/all
6026         https://example.com/packagerepos/release/rpm/core2-64
6027         https://example.com/packagerepos/release/rpm-dev/all
6028         https://example.com/packagerepos/release/rpm-dev/core2-64
6029         https://example.com/packagerepos/updates/rpm/all
6030         https://example.com/packagerepos/updates/rpm/core2-64
6031         https://example.com/packagerepos/updates/rpm-dev/all
6032         https://example.com/packagerepos/updates/rpm-dev/core2-64
6033
6034   :term:`PACKAGE_FEED_BASE_PATHS`
6035      Specifies the base path used when constructing package feed URIs. The
6036      :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a
6037      package feed URI used by the OpenEmbedded build system. The base path
6038      lies between the :term:`PACKAGE_FEED_URIS`
6039      and :term:`PACKAGE_FEED_ARCHS` variables.
6040
6041      Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6042      :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
6043      defined in your ``local.conf`` file::
6044
6045         PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6046                              https://example.com/packagerepos/updates"
6047         PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6048         PACKAGE_FEED_ARCHS = "all core2-64"
6049
6050      Given these settings, the resulting package feeds are as follows:
6051
6052      .. code-block:: none
6053
6054         https://example.com/packagerepos/release/rpm/all
6055         https://example.com/packagerepos/release/rpm/core2-64
6056         https://example.com/packagerepos/release/rpm-dev/all
6057         https://example.com/packagerepos/release/rpm-dev/core2-64
6058         https://example.com/packagerepos/updates/rpm/all
6059         https://example.com/packagerepos/updates/rpm/core2-64
6060         https://example.com/packagerepos/updates/rpm-dev/all
6061         https://example.com/packagerepos/updates/rpm-dev/core2-64
6062
6063   :term:`PACKAGE_FEED_URIS`
6064      Specifies the front portion of the package feed URI used by the
6065      OpenEmbedded build system. Each final package feed URI is comprised
6066      of :term:`PACKAGE_FEED_URIS`,
6067      :term:`PACKAGE_FEED_BASE_PATHS`, and
6068      :term:`PACKAGE_FEED_ARCHS` variables.
6069
6070      Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6071      :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
6072      defined in your ``local.conf`` file::
6073
6074         PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6075                              https://example.com/packagerepos/updates"
6076         PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6077         PACKAGE_FEED_ARCHS = "all core2-64"
6078
6079      Given these settings, the resulting package feeds are as follows:
6080
6081      .. code-block:: none
6082
6083         https://example.com/packagerepos/release/rpm/all
6084         https://example.com/packagerepos/release/rpm/core2-64
6085         https://example.com/packagerepos/release/rpm-dev/all
6086         https://example.com/packagerepos/release/rpm-dev/core2-64
6087         https://example.com/packagerepos/updates/rpm/all
6088         https://example.com/packagerepos/updates/rpm/core2-64
6089         https://example.com/packagerepos/updates/rpm-dev/all
6090         https://example.com/packagerepos/updates/rpm-dev/core2-64
6091
6092   :term:`PACKAGE_INSTALL`
6093      The final list of packages passed to the package manager for
6094      installation into the image.
6095
6096      Because the package manager controls actual installation of all
6097      packages, the list of packages passed using :term:`PACKAGE_INSTALL` is
6098      not the final list of packages that are actually installed. This
6099      variable is internal to the image construction code. Consequently, in
6100      general, you should use the
6101      :term:`IMAGE_INSTALL` variable to specify
6102      packages for installation. The exception to this is when working with
6103      the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
6104      image. When working with an initial RAM filesystem (:term:`Initramfs`) image,
6105      use the :term:`PACKAGE_INSTALL` variable. For information on creating an
6106      :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
6107      in the Yocto Project Development Tasks Manual.
6108
6109   :term:`PACKAGE_INSTALL_ATTEMPTONLY`
6110      Specifies a list of packages the OpenEmbedded build system attempts
6111      to install when creating an image. If a listed package fails to
6112      install, the build system does not generate an error. This variable
6113      is generally not user-defined.
6114
6115   :term:`PACKAGE_PREPROCESS_FUNCS`
6116      Specifies a list of functions run to pre-process the
6117      :term:`PKGD` directory prior to splitting the files out
6118      to individual packages.
6119
6120   :term:`PACKAGE_WRITE_DEPS`
6121      Specifies a list of dependencies for post-installation and
6122      pre-installation scripts on native/cross tools. If your
6123      post-installation or pre-installation script can execute at root filesystem
6124      creation time rather than on the target but depends on a native tool
6125      in order to execute, you need to list the tools in
6126      :term:`PACKAGE_WRITE_DEPS`.
6127
6128      For information on running post-installation scripts, see the
6129      ":ref:`dev-manual/new-recipe:post-installation scripts`"
6130      section in the Yocto Project Development Tasks Manual.
6131
6132   :term:`PACKAGECONFIG`
6133      This variable provides a means of enabling or disabling features of a
6134      recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
6135      recipes when you specify features and then arguments that define
6136      feature behaviors. Here is the basic block structure (broken over
6137      multiple lines for readability)::
6138
6139         PACKAGECONFIG ??= "f1 f2 f3 ..."
6140         PACKAGECONFIG[f1] = "\
6141             --with-f1, \
6142             --without-f1, \
6143             build-deps-for-f1, \
6144             runtime-deps-for-f1, \
6145             runtime-recommends-for-f1, \
6146             packageconfig-conflicts-for-f1"
6147         PACKAGECONFIG[f2] = "\
6148              ... and so on and so on ...
6149
6150      The :term:`PACKAGECONFIG` variable itself specifies a space-separated
6151      list of the features to enable. Following the features, you can
6152      determine the behavior of each feature by providing up to six
6153      order-dependent arguments, which are separated by commas. You can
6154      omit any argument you like but must retain the separating commas. The
6155      order is important and specifies the following:
6156
6157      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
6158         if the feature is enabled.
6159
6160      #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
6161         if the feature is disabled.
6162
6163      #. Additional build dependencies (:term:`DEPENDS`)
6164         that should be added if the feature is enabled.
6165
6166      #. Additional runtime dependencies (:term:`RDEPENDS`)
6167         that should be added if the feature is enabled.
6168
6169      #. Additional runtime recommendations
6170         (:term:`RRECOMMENDS`) that should be added if
6171         the feature is enabled.
6172
6173      #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
6174         settings for this feature.
6175
6176      Consider the following :term:`PACKAGECONFIG` block taken from the
6177      ``librsvg`` recipe. In this example the feature is ``gtk``, which has
6178      three arguments that determine the feature's behavior::
6179
6180         PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
6181
6182      The
6183      ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
6184      enabled. In this case, ``--with-gtk3`` is added to the configure
6185      script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the
6186      other hand, if the feature is disabled say through a ``.bbappend``
6187      file in another layer, then the second argument ``--without-gtk3`` is
6188      added to the configure script instead.
6189
6190      The basic :term:`PACKAGECONFIG` structure previously described holds true
6191      regardless of whether you are creating a block or changing a block.
6192      When creating a block, use the structure inside your recipe.
6193
6194      If you want to change an existing :term:`PACKAGECONFIG` block, you can do
6195      so one of two ways:
6196
6197      -  *Append file:* Create an append file named
6198         ``recipename.bbappend`` in your layer and override the value of
6199         :term:`PACKAGECONFIG`. You can either completely override the
6200         variable::
6201
6202            PACKAGECONFIG = "f4 f5"
6203
6204         Or, you can just append the variable::
6205
6206            PACKAGECONFIG:append = " f4"
6207
6208      -  *Configuration file:* This method is identical to changing the
6209         block through an append file except you edit your ``local.conf``
6210         or ``mydistro.conf`` file. As with append files previously
6211         described, you can either completely override the variable::
6212
6213            PACKAGECONFIG:pn-recipename = "f4 f5"
6214
6215         Or, you can just amend the variable::
6216
6217            PACKAGECONFIG:append:pn-recipename = " f4"
6218
6219      Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service
6220      in which :term:`PACKAGECONFIG` is used to transform the systemd service
6221      into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`::
6222
6223         example.c
6224         example.service
6225         CMakeLists.txt
6226
6227      The ``CMakeLists.txt`` file contains::
6228
6229         if(WITH_SYSTEMD)
6230            install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
6231         endif(WITH_SYSTEMD)
6232
6233      In order to enable the installation of ``example.service`` we need to
6234      ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command
6235      execution.  Recipes that have ``CMakeLists.txt`` generally inherit the
6236      :ref:`ref-classes-cmake` class, that runs ``cmake`` with
6237      :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be
6238      appended to.  Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is
6239      automatically filled with either the first or second element of
6240      :term:`PACKAGECONFIG` flag value, the recipe would be like::
6241
6242         inherit cmake
6243         PACKAGECONFIG = "systemd"
6244         PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
6245
6246      A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
6247      or not::
6248
6249         PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
6250
6251   :term:`PACKAGECONFIG_CONFARGS`
6252      A space-separated list of configuration options generated from the
6253      :term:`PACKAGECONFIG` setting.
6254
6255      Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake`
6256      use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options
6257      to ``configure`` and ``cmake``, respectively. If you are using
6258      :term:`PACKAGECONFIG` but not a class that handles the
6259      :ref:`ref-tasks-configure` task, then you need to use
6260      :term:`PACKAGECONFIG_CONFARGS` appropriately.
6261
6262   :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY`
6263      For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting
6264      :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the
6265      normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
6266      should not be automatically created by the ``packagegroup`` recipe,
6267      which is the default behavior.
6268
6269   :term:`PACKAGES`
6270      The list of packages the recipe creates. The default value is the
6271      following::
6272
6273         ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
6274
6275      During packaging, the :ref:`ref-tasks-package` task
6276      goes through :term:`PACKAGES` and uses the :term:`FILES`
6277      variable corresponding to each package to assign files to the
6278      package. If a file matches the :term:`FILES` variable for more than one
6279      package in :term:`PACKAGES`, it will be assigned to the earliest
6280      (leftmost) package.
6281
6282      Packages in the variable's list that are empty (i.e. where none of
6283      the patterns in ``FILES:``\ pkg match any files installed by the
6284      :ref:`ref-tasks-install` task) are not generated,
6285      unless generation is forced through the
6286      :term:`ALLOW_EMPTY` variable.
6287
6288   :term:`PACKAGES_DYNAMIC`
6289      A promise that your recipe satisfies runtime dependencies for
6290      optional modules that are found in other recipes.
6291      :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
6292      only states that they should be satisfied. For example, if a hard,
6293      runtime dependency (:term:`RDEPENDS`) of another
6294      package is satisfied at build time through the :term:`PACKAGES_DYNAMIC`
6295      variable, but a package with the module name is never actually
6296      produced, then the other package will be broken. Thus, if you attempt
6297      to include that package in an image, you will get a dependency
6298      failure from the packaging system during the
6299      :ref:`ref-tasks-rootfs` task.
6300
6301      Typically, if there is a chance that such a situation can occur and
6302      the package that is not created is valid without the dependency being
6303      satisfied, then you should use :term:`RRECOMMENDS`
6304      (a soft runtime dependency) instead of :term:`RDEPENDS`.
6305
6306      For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when
6307      you are splitting packages, see the
6308      ":ref:`dev-manual/packages:handling optional module packaging`"
6309      section in the Yocto Project Development Tasks Manual.
6310
6311   :term:`PACKAGESPLITFUNCS`
6312      Specifies a list of functions run to perform additional splitting of
6313      files into individual packages. Recipes can either prepend to this
6314      variable or prepend to the ``populate_packages`` function in order to
6315      perform additional package splitting. In either case, the function
6316      should set :term:`PACKAGES`,
6317      :term:`FILES`, :term:`RDEPENDS` and
6318      other packaging variables appropriately in order to perform the
6319      desired splitting.
6320
6321   :term:`PARALLEL_MAKE`
6322
6323      Extra options passed to the build tool command (``make``,
6324      ``ninja`` or more specific build engines, like the Go language one)
6325      during the :ref:`ref-tasks-compile` task, to specify parallel compilation
6326      on the local build host. This variable is usually in the form "-j x",
6327      where x represents the maximum number of parallel threads such engines
6328      can run.
6329
6330      .. note::
6331
6332         For software compiled by ``make``, in order for :term:`PARALLEL_MAKE`
6333         to be effective, ``make`` must be called with
6334         ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6335         way to ensure this is to use the ``oe_runmake`` function.
6336
6337      By default, the OpenEmbedded build system automatically sets this
6338      variable to be equal to the number of cores the build system uses.
6339
6340      .. note::
6341
6342         If the software being built experiences dependency issues during
6343         the :ref:`ref-tasks-compile` task that result in race conditions, you can clear
6344         the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For
6345         information on addressing race conditions, see the
6346         ":ref:`dev-manual/debugging:debugging parallel make races`"
6347         section in the Yocto Project Development Tasks Manual.
6348
6349      For single socket systems (i.e. one CPU), you should not have to
6350      override this variable to gain optimal parallelism during builds.
6351      However, if you have very large systems that employ multiple physical
6352      CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is
6353      not set higher than "-j 20".
6354
6355      For more information on speeding up builds, see the
6356      ":ref:`dev-manual/speeding-up-build:speeding up a build`"
6357      section in the Yocto Project Development Tasks Manual.
6358
6359   :term:`PARALLEL_MAKEINST`
6360      Extra options passed to the build tool install command
6361      (``make install``, ``ninja install`` or more specific ones)
6362      during the :ref:`ref-tasks-install` task in order to specify
6363      parallel installation. This variable defaults to the value of
6364      :term:`PARALLEL_MAKE`.
6365
6366      .. note::
6367
6368         For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST`
6369         to be effective, ``make`` must be called with
6370         ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6371         way to ensure this is to use the ``oe_runmake`` function.
6372
6373         If the software being built experiences dependency issues during
6374         the :ref:`ref-tasks-install` task that result in race conditions, you can
6375         clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
6376         workaround. For information on addressing race conditions, see the
6377         ":ref:`dev-manual/debugging:debugging parallel make races`"
6378         section in the Yocto Project Development Tasks Manual.
6379
6380   :term:`PATCHRESOLVE`
6381      Determines the action to take when a patch fails. You can set this
6382      variable to one of two values: "noop" and "user".
6383
6384      The default value of "noop" causes the build to simply fail when the
6385      OpenEmbedded build system cannot successfully apply a patch. Setting
6386      the value to "user" causes the build system to launch a shell and
6387      places you in the right location so that you can manually resolve the
6388      conflicts.
6389
6390      Set this variable in your ``local.conf`` file.
6391
6392   :term:`PATCHTOOL`
6393      Specifies the utility used to apply patches for a recipe during the
6394      :ref:`ref-tasks-patch` task. You can specify one of
6395      three utilities: "patch", "quilt", or "git". The default utility used
6396      is "quilt" except for the quilt-native recipe itself. Because the
6397      quilt tool is not available at the time quilt-native is being
6398      patched, it uses "patch".
6399
6400      If you wish to use an alternative patching tool, set the variable in
6401      the recipe using one of the following::
6402
6403         PATCHTOOL = "patch"
6404         PATCHTOOL = "quilt"
6405         PATCHTOOL = "git"
6406
6407   :term:`PE`
6408      The epoch of the recipe. By default, this variable is unset. The
6409      variable is used to make upgrades possible when the versioning scheme
6410      changes in some backwards incompatible way.
6411
6412      :term:`PE` is the default value of the :term:`PKGE` variable.
6413
6414   :term:`PEP517_WHEEL_PATH`
6415      When used by recipes that inherit the :ref:`ref-classes-python_pep517`
6416      class, denotes the path to ``dist/`` (short for distribution) where the
6417      binary archive ``wheel`` is built.
6418
6419   :term:`PERSISTENT_DIR`
6420      See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual.
6421
6422   :term:`PF`
6423      Specifies the recipe or package name and includes all version and
6424      revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
6425      ``bash-4.2-r1/``). This variable is comprised of the following:
6426      ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
6427
6428   :term:`PIXBUF_PACKAGES`
6429      When inheriting the :ref:`ref-classes-pixbufcache`
6430      class, this variable identifies packages that contain the pixbuf
6431      loaders used with ``gdk-pixbuf``. By default, the
6432      :ref:`ref-classes-pixbufcache` class assumes that
6433      the loaders are in the recipe's main package (i.e.
6434      ``${``\ :term:`PN`\ ``}``). Use this variable if the
6435      loaders you need are in a package other than that main package.
6436
6437   :term:`PKG`
6438      The name of the resulting package created by the OpenEmbedded build
6439      system.
6440
6441      .. note::
6442
6443         When using the :term:`PKG` variable, you must use a package name override.
6444
6445      For example, when the :ref:`ref-classes-debian` class renames the output
6446      package, it does so by setting ``PKG:packagename``.
6447
6448   :term:`PKG_CONFIG_PATH`
6449      The path to ``pkg-config`` files for the current build context.
6450      ``pkg-config`` reads this variable from the environment.
6451
6452   :term:`PKGD`
6453      Points to the destination directory for files to be packaged before
6454      they are split into individual packages. This directory defaults to
6455      the following::
6456
6457         ${WORKDIR}/package
6458
6459      Do not change this default.
6460
6461   :term:`PKGDATA_DIR`
6462      Points to a shared, global-state directory that holds data generated
6463      during the packaging process. During the packaging process, the
6464      :ref:`ref-tasks-packagedata` task packages data
6465      for each recipe and installs it into this temporary, shared area.
6466      This directory defaults to the following, which you should not
6467      change::
6468
6469         ${STAGING_DIR_HOST}/pkgdata
6470
6471      For examples of how this data is used, see the
6472      ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
6473      section in the Yocto Project Overview and Concepts Manual and the
6474      ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``"
6475      section in the Yocto Project Development Tasks Manual. For more
6476      information on the shared, global-state directory, see
6477      :term:`STAGING_DIR_HOST`.
6478
6479   :term:`PKGDEST`
6480      Points to the parent directory for files to be packaged after they
6481      have been split into individual packages. This directory defaults to
6482      the following::
6483
6484         ${WORKDIR}/packages-split
6485
6486      Under this directory, the build system creates directories for each
6487      package specified in :term:`PACKAGES`. Do not change
6488      this default.
6489
6490   :term:`PKGDESTWORK`
6491      Points to a temporary work area where the
6492      :ref:`ref-tasks-package` task saves package metadata.
6493      The :term:`PKGDESTWORK` location defaults to the following::
6494
6495         ${WORKDIR}/pkgdata
6496
6497      Do not change this default.
6498
6499      The :ref:`ref-tasks-packagedata` task copies the
6500      package metadata from :term:`PKGDESTWORK` to
6501      :term:`PKGDATA_DIR` to make it available globally.
6502
6503   :term:`PKGE`
6504      The epoch of the package(s) built by the recipe. By default, :term:`PKGE`
6505      is set to :term:`PE`.
6506
6507   :term:`PKGR`
6508      The revision of the package(s) built by the recipe. By default,
6509      :term:`PKGR` is set to :term:`PR`.
6510
6511   :term:`PKGV`
6512      The version of the package(s) built by the recipe. By default,
6513      :term:`PKGV` is set to :term:`PV`.
6514
6515   :term:`PN`
6516      This variable can have two separate functions depending on the
6517      context: a recipe name or a resulting package name.
6518
6519      :term:`PN` refers to a recipe name in the context of a file used by the
6520      OpenEmbedded build system as input to create a package. The name is
6521      normally extracted from the recipe file name. For example, if the
6522      recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN`
6523      will be "expat".
6524
6525      The variable refers to a package name in the context of a file
6526      created or produced by the OpenEmbedded build system.
6527
6528      If applicable, the :term:`PN` variable also contains any special suffix
6529      or prefix. For example, using ``bash`` to build packages for the
6530      native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build
6531      packages for the target and for Multilib, :term:`PN` would be ``bash``
6532      and ``lib64-bash``, respectively.
6533
6534   :term:`POPULATE_SDK_POST_HOST_COMMAND`
6535      Specifies a list of functions to call once the OpenEmbedded build
6536      system has created the host part of the SDK. You can specify
6537      functions separated by spaces::
6538
6539          POPULATE_SDK_POST_HOST_COMMAND += "function"
6540
6541      If you need to pass the SDK path to a command within a function, you
6542      can use ``${SDK_DIR}``, which points to the parent directory used by
6543      the OpenEmbedded build system when creating SDK output. See the
6544      :term:`SDK_DIR` variable for more information.
6545
6546   :term:`POPULATE_SDK_POST_TARGET_COMMAND`
6547      Specifies a list of functions to call once the OpenEmbedded build
6548      system has created the target part of the SDK. You can specify
6549      functions separated by spaces::
6550
6551         POPULATE_SDK_POST_TARGET_COMMAND += "function"
6552
6553      If you need to pass the SDK path to a command within a function, you
6554      can use ``${SDK_DIR}``, which points to the parent directory used by
6555      the OpenEmbedded build system when creating SDK output. See the
6556      :term:`SDK_DIR` variable for more information.
6557
6558   :term:`PR`
6559      The revision of the recipe. The default value for this variable is
6560      "r0". Subsequent revisions of the recipe conventionally have the
6561      values "r1", "r2", and so forth. When :term:`PV` increases,
6562      :term:`PR` is conventionally reset to "r0".
6563
6564      .. note::
6565
6566         The OpenEmbedded build system does not need the aid of :term:`PR`
6567         to know when to rebuild a recipe. The build system uses the task
6568         :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the
6569         :ref:`stamp <structure-build-tmp-stamps>` and
6570         :ref:`overview-manual/concepts:shared state cache`
6571         mechanisms.
6572
6573      The :term:`PR` variable primarily becomes significant when a package
6574      manager dynamically installs packages on an already built image. In
6575      this case, :term:`PR`, which is the default value of
6576      :term:`PKGR`, helps the package manager distinguish which
6577      package is the most recent one in cases where many packages have the
6578      same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with
6579      the same :term:`PV` usually means that the packages all install the same
6580      upstream version, but with later (:term:`PR`) version packages including
6581      packaging fixes.
6582
6583      .. note::
6584
6585         :term:`PR` does not need to be increased for changes that do not change the
6586         package contents or metadata.
6587
6588      Because manually managing :term:`PR` can be cumbersome and error-prone,
6589      an automated solution exists. See the
6590      ":ref:`dev-manual/packages:working with a pr service`" section
6591      in the Yocto Project Development Tasks Manual for more information.
6592
6593   :term:`PREFERRED_PROVIDER`
6594      If multiple recipes provide the same item, this variable determines
6595      which recipe is preferred and thus provides the item (i.e. the
6596      preferred provider). You should always suffix this variable with the
6597      name of the provided item. And, you should define the variable using
6598      the preferred recipe's name (:term:`PN`). Here is a common
6599      example::
6600
6601         PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
6602
6603      In the previous example, multiple recipes are providing "virtual/kernel".
6604      The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of
6605      the recipe you prefer to provide "virtual/kernel".
6606
6607      Here are more examples::
6608
6609         PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
6610         PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
6611
6612      For more
6613      information, see the ":ref:`dev-manual/new-recipe:using virtual providers`"
6614      section in the Yocto Project Development Tasks Manual.
6615
6616      .. note::
6617
6618         If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any
6619         recipe that :term:`PROVIDES` that item but is not selected (defined)
6620         by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually
6621         desirable since this mechanism is designed to select between mutually
6622         exclusive alternative providers.
6623
6624   :term:`PREFERRED_PROVIDERS`
6625      See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual.
6626
6627   :term:`PREFERRED_VERSION`
6628      If there are multiple versions of a recipe available, this variable
6629      determines which version should be given preference. You must always
6630      suffix the variable with the :term:`PN` you want to select (`python` in
6631      the first example below), and you should specify the :term:`PV`
6632      accordingly (`3.4.0` in the example).
6633
6634      The :term:`PREFERRED_VERSION` variable supports limited wildcard use
6635      through the "``%``" character. You can use the character to match any
6636      number of characters, which can be useful when specifying versions
6637      that contain long revision numbers that potentially change. Here are
6638      two examples::
6639
6640         PREFERRED_VERSION_python = "3.4.0"
6641         PREFERRED_VERSION_linux-yocto = "5.0%"
6642
6643      .. note::
6644
6645         The use of the "%" character is limited in that it only works at the end of the
6646         string. You cannot use the wildcard character in any other
6647         location of the string.
6648
6649      The specified version is matched against :term:`PV`, which
6650      does not necessarily match the version part of the recipe's filename.
6651      For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
6652      where ``foo_git.bb`` contains the following assignment::
6653
6654         PV = "1.1+git${SRCPV}"
6655
6656      In this case, the correct way to select
6657      ``foo_git.bb`` is by using an assignment such as the following::
6658
6659         PREFERRED_VERSION_foo = "1.1+git%"
6660
6661      Compare that previous example
6662      against the following incorrect example, which does not work::
6663
6664         PREFERRED_VERSION_foo = "git"
6665
6666      Sometimes the :term:`PREFERRED_VERSION` variable can be set by
6667      configuration files in a way that is hard to change. You can use
6668      :term:`OVERRIDES` to set a machine-specific
6669      override. Here is an example::
6670
6671         PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
6672
6673      Although not recommended, worst case, you can also use the
6674      "forcevariable" override, which is the strongest override possible.
6675      Here is an example::
6676
6677         PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
6678
6679      .. note::
6680
6681         The ``:forcevariable`` override is not handled specially. This override
6682         only works because the default value of :term:`OVERRIDES` includes "forcevariable".
6683
6684      If a recipe with the specified version is not available, a warning
6685      message will be shown. See :term:`REQUIRED_VERSION` if you want this
6686      to be an error instead.
6687
6688   :term:`PREMIRRORS`
6689      Specifies additional paths from which the OpenEmbedded build system
6690      gets source code. When the build system searches for source code, it
6691      first tries the local download directory. If that location fails, the
6692      build system tries locations defined by :term:`PREMIRRORS`, the upstream
6693      source, and then locations specified by
6694      :term:`MIRRORS` in that order.
6695
6696      The default value for :term:`PREMIRRORS` is defined in the
6697      ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
6698
6699      Typically, you could add a specific server for the build system to
6700      attempt before any others by adding something like the following to
6701      the ``local.conf`` configuration file in the
6702      :term:`Build Directory`::
6703
6704         PREMIRRORS:prepend = "\
6705             git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6706             ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6707             http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6708             https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
6709
6710      These changes cause the
6711      build system to intercept Git, FTP, HTTP, and HTTPS requests and
6712      direct them to the ``http://`` sources mirror. You can use
6713      ``file://`` URLs to point to local directories or network shares as
6714      well.
6715
6716   :term:`PRIORITY`
6717      Indicates the importance of a package.
6718
6719      :term:`PRIORITY` is considered to be part of the distribution policy
6720      because the importance of any given recipe depends on the purpose for
6721      which the distribution is being produced. Thus, :term:`PRIORITY` is not
6722      normally set within recipes.
6723
6724      You can set :term:`PRIORITY` to "required", "standard", "extra", and
6725      "optional", which is the default.
6726
6727   :term:`PRIVATE_LIBS`
6728      Specifies libraries installed within a recipe that should be ignored
6729      by the OpenEmbedded build system's shared library resolver. This
6730      variable is typically used when software being built by a recipe has
6731      its own private versions of a library normally provided by another
6732      recipe. In this case, you would not want the package containing the
6733      private libraries to be set as a dependency on other unrelated
6734      packages that should instead depend on the package providing the
6735      standard version of the library.
6736
6737      Libraries specified in this variable should be specified by their
6738      file name. For example, from the Firefox recipe in meta-browser::
6739
6740         PRIVATE_LIBS = "libmozjs.so \
6741                         libxpcom.so \
6742                         libnspr4.so \
6743                         libxul.so \
6744                         libmozalloc.so \
6745                         libplc4.so \
6746                         libplds4.so"
6747
6748      For more information, see the
6749      ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
6750      section in the Yocto Project Overview and Concepts Manual.
6751
6752   :term:`PROVIDES`
6753      A list of aliases by which a particular recipe can be known. By
6754      default, a recipe's own :term:`PN` is implicitly already in its
6755      :term:`PROVIDES` list and therefore does not need to mention that it
6756      provides itself. If a recipe uses :term:`PROVIDES`, the additional
6757      aliases are synonyms for the recipe and can be useful for satisfying
6758      dependencies of other recipes during the build as specified by
6759      :term:`DEPENDS`.
6760
6761      Consider the following example :term:`PROVIDES` statement from the recipe
6762      file ``eudev_3.2.9.bb``::
6763
6764         PROVIDES += "udev"
6765
6766      The :term:`PROVIDES` statement
6767      results in the "eudev" recipe also being available as simply "udev".
6768
6769      .. note::
6770
6771         A recipe's own recipe name (:term:`PN`) is always implicitly prepended
6772         to :term:`PROVIDES`, so while using "+=" in the above example may not be
6773         strictly necessary it is recommended to avoid confusion.
6774
6775      In addition to providing recipes under alternate names, the
6776      :term:`PROVIDES` mechanism is also used to implement virtual targets. A
6777      virtual target is a name that corresponds to some particular
6778      functionality (e.g. a Linux kernel). Recipes that provide the
6779      functionality in question list the virtual target in :term:`PROVIDES`.
6780      Recipes that depend on the functionality in question can include the
6781      virtual target in :term:`DEPENDS` to leave the choice of provider open.
6782
6783      Conventionally, virtual targets have names on the form
6784      "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
6785      of the name and has no syntactical significance.
6786
6787      The :term:`PREFERRED_PROVIDER` variable is
6788      used to select which particular recipe provides a virtual target.
6789
6790      .. note::
6791
6792         A corresponding mechanism for virtual runtime dependencies (packages)
6793         exists. However, the mechanism does not depend on any special
6794         functionality beyond ordinary variable assignments. For example,
6795         :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the
6796         package of the component that manages the ``/dev`` directory.
6797
6798         Setting the "preferred provider" for runtime dependencies is as
6799         simple as using the following assignment in a configuration file::
6800
6801                 VIRTUAL-RUNTIME_dev_manager = "udev"
6802
6803
6804   :term:`PRSERV_HOST`
6805      The network based :term:`PR` service host and port.
6806
6807      The ``conf/templates/default/local.conf.sample.extended`` configuration
6808      file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST`
6809      variable is set::
6810
6811         PRSERV_HOST = "localhost:0"
6812
6813      You must
6814      set the variable if you want to automatically start a local :ref:`PR
6815      service <dev-manual/packages:working with a pr service>`. You can
6816      set :term:`PRSERV_HOST` to other values to use a remote PR service.
6817
6818
6819   :term:`PSEUDO_IGNORE_PATHS`
6820      A comma-separated (without spaces) list of path prefixes that should be ignored
6821      by pseudo when monitoring and recording file operations, in order to avoid
6822      problems with files being written to outside of the pseudo context and
6823      reduce pseudo's overhead. A path is ignored if it matches any prefix in the list
6824      and can include partial directory (or file) names.
6825
6826
6827   :term:`PTEST_ENABLED`
6828      Specifies whether or not :ref:`Package
6829      Test <dev-manual/packages:testing packages with ptest>` (ptest)
6830      functionality is enabled when building a recipe. You should not set
6831      this variable directly. Enabling and disabling building Package Tests
6832      at build time should be done by adding "ptest" to (or removing it
6833      from) :term:`DISTRO_FEATURES`.
6834
6835   :term:`PV`
6836      The version of the recipe. The version is normally extracted from the
6837      recipe filename. For example, if the recipe is named
6838      ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1".
6839      :term:`PV` is generally not overridden within a recipe unless it is
6840      building an unstable (i.e. development) version from a source code
6841      repository (e.g. Git or Subversion).
6842
6843      :term:`PV` is the default value of the :term:`PKGV` variable.
6844
6845   :term:`PYPI_PACKAGE`
6846      When inheriting the :ref:`ref-classes-pypi` class, specifies the
6847      `PyPI <https://pypi.org/>`__ package name to be built. The default value
6848      is set based upon :term:`BPN` (stripping any "python-" or "python3-"
6849      prefix off if present), however for some packages it will need to be set
6850      explicitly if that will not match the package name (e.g. where the
6851      package name has a prefix, underscores, uppercase letters etc.)
6852
6853   :term:`PYPI_PACKAGE_EXT`
6854      When inheriting the :ref:`ref-classes-pypi` class, specifies the
6855      file extension to use when fetching a package from `PyPI
6856      <https://pypi.org/>`__. Default is ``tar.gz``.
6857
6858   :term:`PYPI_SRC_URI`
6859      When inheriting the :ref:`ref-classes-pypi` class, specifies the
6860      full `pythonhosted <https://files.pythonhosted.org/>`__ URI for
6861      fetching the package to be built. The default value is constructed
6862      based upon :term:`PYPI_PACKAGE`, :term:`PYPI_PACKAGE_EXT`, and
6863      :term:`PV`. Most recipes will not need to set this variable unless
6864      they are building an unstable (i.e. development) version.
6865
6866   :term:`PYTHON_ABI`
6867      When used by recipes that inherit the :ref:`ref-classes-setuptools3`
6868      class, denotes the Application Binary Interface (ABI) currently in use
6869      for Python. By default, the ABI is "m". You do not have to set this
6870      variable as the OpenEmbedded build system sets it for you.
6871
6872      The OpenEmbedded build system uses the ABI to construct directory
6873      names used when installing the Python headers and libraries in
6874      sysroot (e.g. ``.../python3.3m/...``).
6875
6876   :term:`QA_EMPTY_DIRS`
6877      Specifies a list of directories that are expected to be empty when
6878      packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or
6879      :term:`WARN_QA` these will be checked and an error or warning
6880      (respectively) will be produced.
6881
6882      The default :term:`QA_EMPTY_DIRS` value is set in
6883      :ref:`insane.bbclass <ref-classes-insane>`.
6884
6885   :term:`QA_EMPTY_DIRS_RECOMMENDATION`
6886      Specifies a recommendation for why a directory must be empty,
6887      which will be included in the error message if a specific directory
6888      is found to contain files. Must be overridden with the directory
6889      path to match on.
6890
6891      If no recommendation is specified for a directory, then the default
6892      "but it is expected to be empty" will be used.
6893
6894      An example message shows if files were present in '/dev'::
6895
6896         QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"
6897
6898   :term:`RANLIB`
6899      The minimal command and arguments to run ``ranlib``.
6900
6901   :term:`RCONFLICTS`
6902      The list of packages that conflict with packages. Note that packages
6903      will not be installed if conflicting packages are not first removed.
6904
6905      Like all package-controlling variables, you must always use them in
6906      conjunction with a package name override. Here is an example::
6907
6908         RCONFLICTS:${PN} = "another_conflicting_package_name"
6909
6910      BitBake, which the OpenEmbedded build system uses, supports
6911      specifying versioned dependencies. Although the syntax varies
6912      depending on the packaging format, BitBake hides these differences
6913      from you. Here is the general syntax to specify versions with the
6914      :term:`RCONFLICTS` variable::
6915
6916         RCONFLICTS:${PN} = "package (operator version)"
6917
6918      For ``operator``, you can specify the following:
6919
6920      - =
6921      - <
6922      - >
6923      - <=
6924      - >=
6925
6926      For example, the following sets up a dependency on version 1.2 or
6927      greater of the package ``foo``::
6928
6929         RCONFLICTS:${PN} = "foo (>= 1.2)"
6930
6931   :term:`RDEPENDS`
6932      Lists runtime dependencies of a package. These dependencies are other
6933      packages that must be installed in order for the package to function
6934      correctly. As an example, the following assignment declares that the
6935      package ``foo`` needs the packages ``bar`` and ``baz`` to be
6936      installed::
6937
6938         RDEPENDS:foo = "bar baz"
6939
6940      The most common types of package
6941      runtime dependencies are automatically detected and added. Therefore,
6942      most recipes do not need to set :term:`RDEPENDS`. For more information,
6943      see the
6944      ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
6945      section in the Yocto Project Overview and Concepts Manual.
6946
6947      The practical effect of the above :term:`RDEPENDS` assignment is that
6948      ``bar`` and ``baz`` will be declared as dependencies inside the
6949      package ``foo`` when it is written out by one of the
6950      :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks.
6951      Exactly how this is done depends on which package format is used,
6952      which is determined by
6953      :term:`PACKAGE_CLASSES`. When the
6954      corresponding package manager installs the package, it will know to
6955      also install the packages on which it depends.
6956
6957      To ensure that the packages ``bar`` and ``baz`` get built, the
6958      previous :term:`RDEPENDS` assignment also causes a task dependency to be
6959      added. This dependency is from the recipe's
6960      :ref:`ref-tasks-build` (not to be confused with
6961      :ref:`ref-tasks-compile`) task to the
6962      :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and
6963      ``baz``.
6964
6965      The names of the packages you list within :term:`RDEPENDS` must be the
6966      names of other packages --- they cannot be recipe names. Although
6967      package names and recipe names usually match, the important point
6968      here is that you are providing package names within the :term:`RDEPENDS`
6969      variable. For an example of the default list of packages created from
6970      a recipe, see the :term:`PACKAGES` variable.
6971
6972      Because the :term:`RDEPENDS` variable applies to packages being built,
6973      you should always use the variable in a form with an attached package
6974      name (remember that a single recipe can build multiple packages). For
6975      example, suppose you are building a development package that depends
6976      on the ``perl`` package. In this case, you would use the following
6977      :term:`RDEPENDS` statement::
6978
6979         RDEPENDS:${PN}-dev += "perl"
6980
6981      In the example,
6982      the development package depends on the ``perl`` package. Thus, the
6983      :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of
6984      the variable.
6985
6986      .. note::
6987
6988         ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}``
6989         by default. This default is set in the BitBake configuration file
6990         (``meta/conf/bitbake.conf``). Be careful not to accidentally remove
6991         ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator
6992         rather than the "=" operator.
6993
6994      The package names you use with :term:`RDEPENDS` must appear as they would
6995      in the :term:`PACKAGES` variable. The :term:`PKG` variable
6996      allows a different name to be used for the final package (e.g. the
6997      :ref:`ref-classes-debian` class uses this to rename
6998      packages), but this final package name cannot be used with
6999      :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be
7000      independent of the package format used.
7001
7002      BitBake, which the OpenEmbedded build system uses, supports
7003      specifying versioned dependencies. Although the syntax varies
7004      depending on the packaging format, BitBake hides these differences
7005      from you. Here is the general syntax to specify versions with the
7006      :term:`RDEPENDS` variable::
7007
7008         RDEPENDS:${PN} = "package (operator version)"
7009
7010      For ``operator``, you can specify the following:
7011
7012      - =
7013      - <
7014      - >
7015      - <=
7016      - >=
7017
7018      For version, provide the version number.
7019
7020      .. note::
7021
7022         You can use :term:`EXTENDPKGV` to provide a full package version
7023         specification.
7024
7025      For example, the following sets up a dependency on version 1.2 or
7026      greater of the package ``foo``::
7027
7028         RDEPENDS:${PN} = "foo (>= 1.2)"
7029
7030      For information on build-time dependencies, see the :term:`DEPENDS`
7031      variable. You can also see the
7032      ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
7033      ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
7034      BitBake User Manual for additional information on tasks and dependencies.
7035
7036   :term:`RECIPE_MAINTAINER`
7037      This variable defines the name and e-mail address of the maintainer of a
7038      recipe. Such information can be used by human users submitted changes,
7039      and by automated tools to send notifications, for example about
7040      vulnerabilities or source updates.
7041
7042      The variable can be defined in a global distribution :oe_git:`maintainers.inc
7043      </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file::
7044
7045          meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>"
7046
7047      It can also be directly defined in a recipe,
7048      for example in the ``libgpiod`` one::
7049
7050          RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>"
7051
7052   :term:`RECIPE_NO_UPDATE_REASON`
7053      If a recipe should not be replaced by a more recent upstream version,
7054      putting the reason why in this variable in a recipe allows
7055      ``devtool check-upgrade-status`` command to display it, as explained
7056      in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`"
7057      section.
7058
7059   :term:`RECIPE_SYSROOT`
7060      This variable points to the directory that holds all files populated from
7061      recipes specified in :term:`DEPENDS`. As the name indicates,
7062      think of this variable as a custom root (``/``) for the recipe that will be
7063      used by the compiler in order to find headers and other files needed to complete
7064      its job.
7065
7066      This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
7067      according to the type of the recipe and the build target.
7068
7069      To better understand this variable, consider the following examples:
7070
7071      -  For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"``
7072
7073      -  For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"``
7074         or other library sysroot directories.
7075
7076      The default value is ``"${WORKDIR}/recipe-sysroot"``.
7077      Do not modify it.
7078
7079   :term:`RECIPE_SYSROOT_NATIVE`
7080      This is similar to :term:`RECIPE_SYSROOT` but the populated files are from
7081      ``-native`` recipes. This allows a recipe built for the target machine to
7082      use ``native`` tools.
7083
7084      This variable is related to :term:`STAGING_DIR_NATIVE`.
7085
7086      The default value is ``"${WORKDIR}/recipe-sysroot-native"``.
7087      Do not modify it.
7088
7089   :term:`RECIPE_UPDATE_EXTRA_TASKS`
7090      For some recipes, after the new source has been unpacked, additional tasks
7091      may need to be run during an upgrade. A good example of this is recipes
7092      which inherit :ref:`ref-classes-cargo-update-recipe-crates`, where the
7093      `do_update_crates` task needs to be run whenever Cargo.toml/Cargo.lock have
7094      changed in the source.
7095
7096   :term:`REPODIR`
7097      See :term:`bitbake:REPODIR` in the BitBake manual.
7098
7099   :term:`REQUIRED_DISTRO_FEATURES`
7100      When inheriting the :ref:`ref-classes-features_check`
7101      class, this variable identifies distribution features that must exist
7102      in the current configuration in order for the OpenEmbedded build
7103      system to build the recipe. In other words, if the
7104      :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not
7105      appear in :term:`DISTRO_FEATURES` within the current configuration, then
7106      the recipe will be skipped, and if the build system attempts to build
7107      the recipe then an error will be triggered.
7108
7109   :term:`REQUIRED_VERSION`
7110      If there are multiple versions of a recipe available, this variable
7111      determines which version should be given preference.
7112      :term:`REQUIRED_VERSION` works in exactly the same manner as
7113      :term:`PREFERRED_VERSION`, except that if the specified version is not
7114      available then an error message is shown and the build fails
7115      immediately.
7116
7117      If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
7118      for the same recipe, the :term:`REQUIRED_VERSION` value applies.
7119
7120   :term:`RM_WORK_EXCLUDE`
7121      With :ref:`ref-classes-rm-work` enabled, this variable
7122      specifies a list of recipes whose work directories should not be removed.
7123      See the ":ref:`ref-classes-rm-work`" section for more details.
7124
7125   :term:`ROOT_HOME`
7126      Defines the root home directory. By default, this directory is set as
7127      follows in the BitBake configuration file::
7128
7129         ROOT_HOME ??= "/home/root"
7130
7131      .. note::
7132
7133         This default value is likely used because some embedded solutions
7134         prefer to have a read-only root filesystem and prefer to keep
7135         writeable data in one place.
7136
7137      You can override the default by setting the variable in any layer or
7138      in the ``local.conf`` file. Because the default is set using a "weak"
7139      assignment (i.e. "??="), you can use either of the following forms to
7140      define your override::
7141
7142         ROOT_HOME = "/root"
7143         ROOT_HOME ?= "/root"
7144
7145      These
7146      override examples use ``/root``, which is probably the most commonly
7147      used override.
7148
7149   :term:`ROOTFS`
7150      Indicates a filesystem image to include as the root filesystem.
7151
7152      The :term:`ROOTFS` variable is an optional variable used with the
7153      :ref:`ref-classes-image-live` class.
7154
7155   :term:`ROOTFS_POSTINSTALL_COMMAND`
7156      Specifies a list of functions to call after the OpenEmbedded build
7157      system has installed packages. You can specify functions separated by
7158      spaces::
7159
7160         ROOTFS_POSTINSTALL_COMMAND += "function"
7161
7162      If you need to pass the root filesystem path to a command within a
7163      function, you can use ``${IMAGE_ROOTFS}``, which points to the
7164      directory that becomes the root filesystem image. See the
7165      :term:`IMAGE_ROOTFS` variable for more
7166      information.
7167
7168   :term:`ROOTFS_POSTPROCESS_COMMAND`
7169      Specifies a list of functions to call once the OpenEmbedded build
7170      system has created the root filesystem. You can specify functions
7171      separated by spaces::
7172
7173         ROOTFS_POSTPROCESS_COMMAND += "function"
7174
7175      If you need to pass the root filesystem path to a command within a
7176      function, you can use ``${IMAGE_ROOTFS}``, which points to the
7177      directory that becomes the root filesystem image. See the
7178      :term:`IMAGE_ROOTFS` variable for more
7179      information.
7180
7181   :term:`ROOTFS_POSTUNINSTALL_COMMAND`
7182      Specifies a list of functions to call after the OpenEmbedded build
7183      system has removed unnecessary packages. When runtime package
7184      management is disabled in the image, several packages are removed
7185      including ``base-passwd``, ``shadow``, and ``update-alternatives``.
7186      You can specify functions separated by spaces::
7187
7188         ROOTFS_POSTUNINSTALL_COMMAND += "function"
7189
7190      If you need to pass the root filesystem path to a command within a
7191      function, you can use ``${IMAGE_ROOTFS}``, which points to the
7192      directory that becomes the root filesystem image. See the
7193      :term:`IMAGE_ROOTFS` variable for more
7194      information.
7195
7196   :term:`ROOTFS_PREPROCESS_COMMAND`
7197      Specifies a list of functions to call before the OpenEmbedded build
7198      system has created the root filesystem. You can specify functions
7199      separated by spaces::
7200
7201         ROOTFS_PREPROCESS_COMMAND += "function"
7202
7203      If you need to pass the root filesystem path to a command within a
7204      function, you can use ``${IMAGE_ROOTFS}``, which points to the
7205      directory that becomes the root filesystem image. See the
7206      :term:`IMAGE_ROOTFS` variable for more
7207      information.
7208
7209   :term:`RPMBUILD_EXTRA_PARAMS`
7210      Specifies extra user-defined parameters for the ``rpmbuild`` command.
7211
7212   :term:`RPROVIDES`
7213      A list of package name aliases that a package also provides. These
7214      aliases are useful for satisfying runtime dependencies of other
7215      packages both during the build and on the target (as specified by
7216      :term:`RDEPENDS`).
7217
7218      .. note::
7219
7220         A package's own name is implicitly already in its :term:`RPROVIDES` list.
7221
7222      As with all package-controlling variables, you must always use the
7223      variable in conjunction with a package name override. Here is an
7224      example::
7225
7226         RPROVIDES:${PN} = "widget-abi-2"
7227
7228   :term:`RRECOMMENDS`
7229      A list of packages that extends the usability of a package being
7230      built. The package being built does not depend on this list of
7231      packages in order to successfully build, but rather uses them for
7232      extended usability. To specify runtime dependencies for packages, see
7233      the :term:`RDEPENDS` variable.
7234
7235      The package manager will automatically install the :term:`RRECOMMENDS`
7236      list of packages when installing the built package. However, you can
7237      prevent listed packages from being installed by using the
7238      :term:`BAD_RECOMMENDATIONS`,
7239      :term:`NO_RECOMMENDATIONS`, and
7240      :term:`PACKAGE_EXCLUDE` variables.
7241
7242      Packages specified in :term:`RRECOMMENDS` need not actually be produced.
7243      However, there must be a recipe providing each package, either
7244      through the :term:`PACKAGES` or
7245      :term:`PACKAGES_DYNAMIC` variables or the
7246      :term:`RPROVIDES` variable, or an error will occur
7247      during the build. If such a recipe does exist and the package is not
7248      produced, the build continues without error.
7249
7250      Because the :term:`RRECOMMENDS` variable applies to packages being built,
7251      you should always attach an override to the variable to specify the
7252      particular package whose usability is being extended. For example,
7253      suppose you are building a development package that is extended to
7254      support wireless functionality. In this case, you would use the
7255      following::
7256
7257         RRECOMMENDS:${PN}-dev += "wireless_package_name"
7258
7259      In the
7260      example, the package name (``${PN}-dev``) must appear as it would in
7261      the :term:`PACKAGES` namespace before any renaming of the output package
7262      by classes such as :ref:`ref-classes-debian`.
7263
7264      BitBake, which the OpenEmbedded build system uses, supports
7265      specifying versioned recommends. Although the syntax varies depending
7266      on the packaging format, BitBake hides these differences from you.
7267      Here is the general syntax to specify versions with the
7268      :term:`RRECOMMENDS` variable::
7269
7270         RRECOMMENDS:${PN} = "package (operator version)"
7271
7272      For ``operator``, you can specify the following:
7273
7274      - =
7275      - <
7276      - >
7277      - <=
7278      - >=
7279
7280      For example, the following sets up a recommend on version 1.2 or
7281      greater of the package ``foo``::
7282
7283         RRECOMMENDS:${PN} = "foo (>= 1.2)"
7284
7285   :term:`RREPLACES`
7286      A list of packages replaced by a package. The package manager uses
7287      this variable to determine which package should be installed to
7288      replace other package(s) during an upgrade. In order to also have the
7289      other package(s) removed at the same time, you must add the name of
7290      the other package to the :term:`RCONFLICTS` variable.
7291
7292      As with all package-controlling variables, you must use this variable
7293      in conjunction with a package name override. Here is an example::
7294
7295         RREPLACES:${PN} = "other_package_being_replaced"
7296
7297      BitBake, which the OpenEmbedded build system uses, supports
7298      specifying versioned replacements. Although the syntax varies
7299      depending on the packaging format, BitBake hides these differences
7300      from you. Here is the general syntax to specify versions with the
7301      :term:`RREPLACES` variable::
7302
7303         RREPLACES:${PN} = "package (operator version)"
7304
7305      For ``operator``, you can specify the following:
7306
7307      - =
7308      - <
7309      - >
7310      - <=
7311      - >=
7312
7313      For example, the following sets up a replacement using version 1.2
7314      or greater of the package ``foo``::
7315
7316          RREPLACES:${PN} = "foo (>= 1.2)"
7317
7318   :term:`RSUGGESTS`
7319      A list of additional packages that you can suggest for installation
7320      by the package manager at the time a package is installed. Not all
7321      package managers support this functionality.
7322
7323      As with all package-controlling variables, you must always use this
7324      variable in conjunction with a package name override. Here is an
7325      example::
7326
7327         RSUGGESTS:${PN} = "useful_package another_package"
7328
7329   :term:`RUST_CHANNEL`
7330      Specifies which version of Rust to build - "stable", "beta" or "nightly".
7331      The default value is "stable". Set this at your own risk, as values other
7332      than "stable" are not guaranteed to work at a given time.
7333
7334   :term:`S`
7335      The location in the :term:`Build Directory` where
7336      unpacked recipe source code resides. By default, this directory is
7337      ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
7338      where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
7339      version. If the source tarball extracts the code to a directory named
7340      anything other than ``${BPN}-${PV}``, or if the source code is
7341      fetched from an SCM such as Git or Subversion, then you must set
7342      :term:`S` in the recipe so that the OpenEmbedded build system knows where
7343      to find the unpacked source.
7344
7345      As an example, assume a :term:`Source Directory`
7346      top-level folder named ``poky`` and a default :term:`Build Directory` at
7347      ``poky/build``. In this case, the work directory the build system
7348      uses to keep the unpacked recipe for ``db`` is the following::
7349
7350         poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
7351
7352      The unpacked source code resides in the ``db-5.1.19`` folder.
7353
7354      This next example assumes a Git repository. By default, Git
7355      repositories are cloned to ``${WORKDIR}/git`` during
7356      :ref:`ref-tasks-fetch`. Since this path is different
7357      from the default value of :term:`S`, you must set it specifically so the
7358      source can be located::
7359
7360         SRC_URI = "git://path/to/repo.git;branch=main"
7361         S = "${WORKDIR}/git"
7362
7363   :term:`SANITY_REQUIRED_UTILITIES`
7364      Specifies a list of command-line utilities that should be checked for
7365      during the initial sanity checking process when running BitBake. If
7366      any of the utilities are not installed on the build host, then
7367      BitBake immediately exits with an error.
7368
7369   :term:`SANITY_TESTED_DISTROS`
7370      A list of the host distribution identifiers that the build system has
7371      been tested against. Identifiers consist of the host distributor ID
7372      followed by the release, as reported by the ``lsb_release`` tool or
7373      as read from ``/etc/lsb-release``. Separate the list items with
7374      explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is
7375      not empty and the current value of
7376      :term:`NATIVELSBSTRING` does not appear in the
7377      list, then the build system reports a warning that indicates the
7378      current host distribution has not been tested as a build host.
7379
7380   :term:`SDK_ARCH`
7381      The target architecture for the SDK. Typically, you do not directly
7382      set this variable. Instead, use :term:`SDKMACHINE`.
7383
7384   :term:`SDK_ARCHIVE_TYPE`
7385      Specifies the type of archive to create for the SDK. Valid values:
7386
7387      - ``tar.xz`` (default)
7388      - ``zip``
7389
7390      Only one archive type can be specified.
7391
7392   :term:`SDK_BUILDINFO_FILE`
7393      When using the :ref:`ref-classes-image-buildinfo` class,
7394      specifies the file in the SDK to write the build information into. The
7395      default value is "``/buildinfo``".
7396
7397   :term:`SDK_CUSTOM_TEMPLATECONF`
7398      When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
7399      "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory`
7400      (:term:`TOPDIR`) then this will be copied into the SDK.
7401
7402   :term:`SDK_DEPLOY`
7403      The directory set up and used by the
7404      :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the
7405      SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>`
7406      class defines :term:`SDK_DEPLOY` as follows::
7407
7408         SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
7409
7410   :term:`SDK_DIR`
7411      The parent directory used by the OpenEmbedded build system when
7412      creating SDK output. The
7413      :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
7414      the variable as follows::
7415
7416         SDK_DIR = "${WORKDIR}/sdk"
7417
7418      .. note::
7419
7420         The :term:`SDK_DIR` directory is a temporary directory as it is part of
7421         :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`.
7422
7423   :term:`SDK_EXT_TYPE`
7424      Controls whether or not shared state artifacts are copied into the
7425      extensible SDK. The default value of "full" copies all of the
7426      required shared state artifacts into the extensible SDK. The value
7427      "minimal" leaves these artifacts out of the SDK.
7428
7429      .. note::
7430
7431         If you set the variable to "minimal", you need to ensure
7432         :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the
7433         artifacts to be fetched as needed.
7434
7435   :term:`SDK_HOST_MANIFEST`
7436      The manifest file for the host part of the SDK. This file lists all
7437      the installed packages that make up the host part of the SDK. The
7438      file contains package information on a line-per-package basis as
7439      follows::
7440
7441         packagename packagearch version
7442
7443      The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
7444      defines the manifest file as follows::
7445
7446         SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
7447
7448      The location is derived using the :term:`SDK_DEPLOY` and
7449      :term:`TOOLCHAIN_OUTPUTNAME` variables.
7450
7451   :term:`SDK_INCLUDE_PKGDATA`
7452      When set to "1", specifies to include the packagedata for all recipes
7453      in the "world" target in the extensible SDK. Including this data
7454      allows the ``devtool search`` command to find these recipes in search
7455      results, as well as allows the ``devtool add`` command to map
7456      dependencies more effectively.
7457
7458      .. note::
7459
7460         Enabling the :term:`SDK_INCLUDE_PKGDATA`
7461         variable significantly increases build time because all of world
7462         needs to be built. Enabling the variable also slightly increases
7463         the size of the extensible SDK.
7464
7465   :term:`SDK_INCLUDE_TOOLCHAIN`
7466      When set to "1", specifies to include the toolchain in the extensible
7467      SDK. Including the toolchain is useful particularly when
7468      :term:`SDK_EXT_TYPE` is set to "minimal" to keep
7469      the SDK reasonably small but you still want to provide a usable
7470      toolchain. For example, suppose you want to use the toolchain from an
7471      IDE or from other tools and you do not want to perform additional
7472      steps to install the toolchain.
7473
7474      The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if
7475      :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
7476      :term:`SDK_EXT_TYPE` is set to "full".
7477
7478   :term:`SDK_NAME`
7479      The base name for SDK output files. The default value (as set in
7480      ``meta-poky/conf/distro/poky.conf``) is derived from the
7481      :term:`DISTRO`,
7482      :term:`TCLIBC`,
7483      :term:`SDKMACHINE`,
7484      :term:`IMAGE_BASENAME`,
7485      :term:`TUNE_PKGARCH`, and
7486      :term:`MACHINE` variables::
7487
7488         SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"
7489
7490   :term:`SDK_OS`
7491      Specifies the operating system for which the SDK will be built. The
7492      default value is the value of :term:`BUILD_OS`.
7493
7494   :term:`SDK_OUTPUT`
7495      The location used by the OpenEmbedded build system when creating SDK
7496      output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
7497      class defines the variable as follows::
7498
7499         SDK_DIR = "${WORKDIR}/sdk"
7500         SDK_OUTPUT = "${SDK_DIR}/image"
7501         SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
7502
7503      .. note::
7504
7505         The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of
7506         :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is
7507         :term:`SDK_DEPLOY`.
7508
7509   :term:`SDK_PACKAGE_ARCHS`
7510      Specifies a list of architectures compatible with the SDK machine.
7511      This variable is set automatically and should not normally be
7512      hand-edited. Entries are separated using spaces and listed in order
7513      of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any
7514      noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
7515
7516   :term:`SDK_POSTPROCESS_COMMAND`
7517      Specifies a list of functions to call once the OpenEmbedded build
7518      system creates the SDK. You can specify functions separated by
7519      spaces:
7520
7521         SDK_POSTPROCESS_COMMAND += "function"
7522
7523      If you need to pass an SDK path to a command within a function, you
7524      can use ``${SDK_DIR}``, which points to the parent directory used by
7525      the OpenEmbedded build system when creating SDK output. See the
7526      :term:`SDK_DIR` variable for more information.
7527
7528   :term:`SDK_PREFIX`
7529      The toolchain binary prefix used for
7530      :ref:`ref-classes-nativesdk` recipes. The
7531      OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the
7532      :term:`TARGET_PREFIX` when building
7533      ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
7534
7535   :term:`SDK_RECRDEP_TASKS`
7536      A list of shared state tasks added to the extensible SDK. By default,
7537      the following tasks are added:
7538
7539      - :ref:`ref-tasks-populate_lic`
7540      - :ref:`ref-tasks-package_qa`
7541      - :ref:`ref-tasks-populate_sysroot`
7542      - :ref:`ref-tasks-deploy`
7543
7544      Despite the default value of "" for the
7545      :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added
7546      to the SDK. To specify tasks beyond these four, you need to use the
7547      :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional
7548      tasks that are needed in order to build
7549      :term:`SDK_TARGETS`).
7550
7551   :term:`SDK_SYS`
7552      Specifies the system, including the architecture and the operating
7553      system, for which the SDK will be built.
7554
7555      The OpenEmbedded build system automatically sets this variable based
7556      on :term:`SDK_ARCH`,
7557      :term:`SDK_VENDOR`, and
7558      :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS`
7559      variable yourself.
7560
7561   :term:`SDK_TARGET_MANIFEST`
7562      The manifest file for the target part of the SDK. This file lists all
7563      the installed packages that make up the target part of the SDK. The
7564      file contains package information on a line-per-package basis as
7565      follows::
7566
7567         packagename packagearch version
7568
7569      The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
7570      defines the manifest file as follows::
7571
7572         SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
7573
7574      The location is derived using the :term:`SDK_DEPLOY` and
7575      :term:`TOOLCHAIN_OUTPUTNAME` variables.
7576
7577   :term:`SDK_TARGETS`
7578      A list of targets to install from shared state as part of the
7579      standard or extensible SDK installation. The default value is "${PN}"
7580      (i.e. the image from which the SDK is built).
7581
7582      The :term:`SDK_TARGETS` variable is an internal variable and typically
7583      would not be changed.
7584
7585   :term:`SDK_TITLE`
7586      The title to be printed when running the SDK installer. By default,
7587      this title is based on the :term:`DISTRO_NAME` or
7588      :term:`DISTRO` variable and is set in the
7589      :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
7590      follows::
7591
7592         SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
7593
7594      For the default distribution "poky",
7595      :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)".
7596
7597      For information on how to change this default title, see the
7598      ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`"
7599      section in the Yocto Project Application Development and the
7600      Extensible Software Development Kit (eSDK) manual.
7601
7602   :term:`SDK_TOOLCHAIN_LANGS`
7603      Specifies programming languages to support in the SDK, as a
7604      space-separated list. Currently supported items are ``rust`` and ``go``.
7605
7606   :term:`SDK_UPDATE_URL`
7607      An optional URL for an update server for the extensible SDK. If set,
7608      the value is used as the default update server when running
7609      ``devtool sdk-update`` within the extensible SDK.
7610
7611   :term:`SDK_VENDOR`
7612      Specifies the name of the SDK vendor.
7613
7614   :term:`SDK_VERSION`
7615      Specifies the version of the SDK. The Poky distribution configuration file
7616      (``/meta-poky/conf/distro/poky.conf``) sets the default
7617      :term:`SDK_VERSION` as follows::
7618
7619         SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
7620
7621      For additional information, see the
7622      :term:`DISTRO_VERSION` and
7623      :term:`METADATA_REVISION` variables.
7624
7625   :term:`SDK_ZIP_OPTIONS`
7626      Specifies extra options to pass to the ``zip`` command when zipping the SDK
7627      (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is
7628      "-y".
7629
7630   :term:`SDKEXTPATH`
7631      The default installation directory for the Extensible SDK. By
7632      default, this directory is based on the :term:`DISTRO`
7633      variable and is set in the
7634      :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
7635      follows::
7636
7637         SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
7638
7639      For the
7640      default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk".
7641
7642      For information on how to change this default directory, see the
7643      ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`"
7644      section in the Yocto Project Application Development and the
7645      Extensible Software Development Kit (eSDK) manual.
7646
7647   :term:`SDKIMAGE_FEATURES`
7648      Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to
7649      the SDK generated from an image using the following command::
7650
7651         $ bitbake -c populate_sdk imagename
7652
7653   :term:`SDKMACHINE`
7654      The machine for which the SDK is built. In other words, the SDK is built
7655      such that it runs on the target you specify with the :term:`SDKMACHINE`
7656      value. The value points to a corresponding ``.conf`` file under
7657      ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``,
7658      ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are
7659      :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`.
7660
7661      The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the
7662      architecture of the build machine.
7663
7664      .. note::
7665
7666         You cannot set the :term:`SDKMACHINE`
7667         variable in your distribution configuration file. If you do, the
7668         configuration will not take effect.
7669
7670   :term:`SDKPATH`
7671      Defines the path used to collect the SDK components and build the
7672      installer.
7673
7674   :term:`SDKPATHINSTALL`
7675      Defines the path offered to the user for installation of the SDK that
7676      is generated by the OpenEmbedded build system. The path appears as
7677      the default location for installing the SDK when you run the SDK's
7678      installation script. You can override the offered path when you run
7679      the script.
7680
7681   :term:`SDKTARGETSYSROOT`
7682      The full path to the sysroot used for cross-compilation within an SDK
7683      as it will be when installed into the default
7684      :term:`SDKPATHINSTALL`.
7685
7686   :term:`SECTION`
7687      The section in which packages should be categorized. Package
7688      management utilities can make use of this variable.
7689
7690   :term:`SELECTED_OPTIMIZATION`
7691      Specifies the optimization flags passed to the C compiler when
7692      building for the target. The flags are passed through the default
7693      value of the :term:`TARGET_CFLAGS` variable.
7694
7695      The :term:`SELECTED_OPTIMIZATION` variable takes the value of
7696      :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which
7697      case the value of :term:`DEBUG_OPTIMIZATION` is used.
7698
7699   :term:`SERIAL_CONSOLES`
7700      Defines a serial console (TTY) to enable using
7701      :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the
7702      baud rate followed by the TTY device name separated by a semicolon.
7703      Use spaces to separate multiple devices::
7704
7705         SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
7706
7707   :term:`SETUPTOOLS_BUILD_ARGS`
7708      When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7709      class, this variable can be used to specify additional arguments to be
7710      passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task.
7711
7712   :term:`SETUPTOOLS_INSTALL_ARGS`
7713      When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7714      class, this variable can be used to specify additional arguments to be
7715      passed to ``setup.py install`` in the ``setuptools3_do_install()`` task.
7716
7717   :term:`SETUPTOOLS_SETUP_PATH`
7718      When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7719      class, this variable should be used to specify the directory in which
7720      the ``setup.py`` file is located if it is not at the root of the source
7721      tree (as specified by :term:`S`). For example, in a recipe where the
7722      sources are fetched from a Git repository and ``setup.py`` is in a
7723      ``python/pythonmodule`` subdirectory, you would have this::
7724
7725         S = "${WORKDIR}/git"
7726         SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule"
7727
7728   :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
7729      A list of recipe dependencies that should not be used to determine
7730      signatures of tasks from one recipe when they depend on tasks from
7731      another recipe. For example::
7732
7733         SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
7734
7735      In the previous example, ``intone`` depends on ``mplayer2``.
7736
7737      You can use the special token ``"*"`` on the left-hand side of the
7738      dependency to match all recipes except the one on the right-hand
7739      side. Here is an example::
7740
7741         SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
7742
7743      In the previous example, all recipes except ``quilt-native`` ignore
7744      task signatures from the ``quilt-native`` recipe when determining
7745      their task signatures.
7746
7747      Use of this variable is one mechanism to remove dependencies that
7748      affect task signatures and thus force rebuilds when a recipe changes.
7749
7750      .. note::
7751
7752         If you add an inappropriate dependency for a recipe relationship,
7753         the software might break during runtime if the interface of the
7754         second recipe was changed after the first recipe had been built.
7755
7756   :term:`SIGGEN_EXCLUDERECIPES_ABISAFE`
7757      A list of recipes that are completely stable and will never change.
7758      The ABI for the recipes in the list are presented by output from the
7759      tasks run to build the recipe. Use of this variable is one way to
7760      remove dependencies from one recipe on another that affect task
7761      signatures and thus force rebuilds when the recipe changes.
7762
7763      .. note::
7764
7765         If you add an inappropriate variable to this list, the software
7766         might break at runtime if the interface of the recipe was changed
7767         after the other had been built.
7768
7769   :term:`SITEINFO_BITS`
7770      Specifies the number of bits for the target system CPU. The value
7771      should be either "32" or "64".
7772
7773   :term:`SITEINFO_ENDIANNESS`
7774      Specifies the endian byte order of the target system. The value
7775      should be either "le" for little-endian or "be" for big-endian.
7776
7777   :term:`SKIP_FILEDEPS`
7778      Enables removal of all files from the "Provides" section of an RPM
7779      package. Removal of these files is required for packages containing
7780      prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
7781
7782      To enable file removal, set the variable to "1" in your
7783      ``conf/local.conf`` configuration file in your:
7784      :term:`Build Directory`::
7785
7786         SKIP_FILEDEPS = "1"
7787
7788   :term:`SKIP_RECIPE`
7789      Used to prevent the OpenEmbedded build system from building a given
7790      recipe. Specify the :term:`PN` value as a variable flag (``varflag``)
7791      and provide a reason, which will be reported when attempting to
7792      build the recipe.
7793
7794      To prevent a recipe from being built, use the :term:`SKIP_RECIPE`
7795      variable in your ``local.conf`` file or distribution configuration.
7796      Here is an example which prevents ``myrecipe`` from being built::
7797
7798         SKIP_RECIPE[myrecipe] = "Not supported by our organization."
7799
7800   :term:`SOC_FAMILY`
7801      A colon-separated list grouping together machines based upon the same
7802      family of SoC (System On Chip). You typically set this variable in a
7803      common ``.inc`` file that you include in the configuration files of all
7804      the machines.
7805
7806      .. note::
7807
7808         You must include ``conf/machine/include/soc-family.inc`` for this
7809         variable to appear in :term:`MACHINEOVERRIDES`.
7810
7811   :term:`SOLIBS`
7812      Defines the suffix for shared libraries used on the target platform.
7813      By default, this suffix is ".so.*" for all Linux-based systems and is
7814      defined in the ``meta/conf/bitbake.conf`` configuration file.
7815
7816      You will see this variable referenced in the default values of
7817      ``FILES:${PN}``.
7818
7819   :term:`SOLIBSDEV`
7820      Defines the suffix for the development symbolic link (symlink) for
7821      shared libraries on the target platform. By default, this suffix is
7822      ".so" for Linux-based systems and is defined in the
7823      ``meta/conf/bitbake.conf`` configuration file.
7824
7825      You will see this variable referenced in the default values of
7826      ``FILES:${PN}-dev``.
7827
7828   :term:`SOURCE_DATE_EPOCH`
7829      This defines a date expressed in number of seconds since
7830      the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by
7831      multiple build systems to force a timestamp in built binaries.
7832      Many upstream projects already support this variable.
7833
7834      You will find more details in the `official specifications
7835      <https://reproducible-builds.org/specs/source-date-epoch/>`__.
7836
7837      A value for each recipe is computed from the sources by
7838      :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`.
7839
7840      If a recipe wishes to override the default behavior, it should set its
7841      own :term:`SOURCE_DATE_EPOCH` value::
7842
7843          SOURCE_DATE_EPOCH = "1613559011"
7844
7845   :term:`SOURCE_MIRROR_FETCH`
7846      When you are fetching files to create a mirror of sources (i.e.
7847      creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in
7848      your ``local.conf`` configuration file ensures the source for all
7849      recipes are fetched regardless of whether or not a recipe is
7850      compatible with the configuration. A recipe is considered
7851      incompatible with the currently configured machine when either or
7852      both the :term:`COMPATIBLE_MACHINE`
7853      variable and :term:`COMPATIBLE_HOST` variables
7854      specify compatibility with a machine other than that of the current
7855      machine or host.
7856
7857      .. note::
7858
7859         Do not set the :term:`SOURCE_MIRROR_FETCH`
7860         variable unless you are creating a source mirror. In other words,
7861         do not set the variable during a normal build.
7862
7863   :term:`SOURCE_MIRROR_URL`
7864      Defines your own :term:`PREMIRRORS` from which to
7865      first fetch source before attempting to fetch from the upstream
7866      specified in :term:`SRC_URI`.
7867
7868      To use this variable, you must globally inherit the
7869      :ref:`ref-classes-own-mirrors` class and then provide
7870      the URL to your mirrors. Here is the general syntax::
7871
7872         INHERIT += "own-mirrors"
7873         SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
7874
7875      .. note::
7876
7877         You can specify only a single URL in :term:`SOURCE_MIRROR_URL`.
7878
7879   :term:`SPDX_ARCHIVE_PACKAGED`
7880      This option allows to add to :term:`SPDX` output compressed archives
7881      of the files in the generated target packages.
7882
7883      Such archives are available in
7884      ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst``
7885      under the :term:`Build Directory`.
7886
7887      Enable this option as follows::
7888
7889         SPDX_ARCHIVE_PACKAGED = "1"
7890
7891      According to our tests on release 4.1 "langdale", building
7892      ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this
7893      option multiplied the size of the ``tmp/deploy/spdx`` directory by a
7894      factor of 13 (+1.6 GiB for this image), compared to just using the
7895      :ref:`ref-classes-create-spdx` class with no option.
7896
7897      Note that this option doesn't increase the size of :term:`SPDX`
7898      files in ``tmp/deploy/images/MACHINE``.
7899
7900   :term:`SPDX_ARCHIVE_SOURCES`
7901      This option allows to add to :term:`SPDX` output compressed archives
7902      of the sources for packages installed on the target. It currently
7903      only works when :term:`SPDX_INCLUDE_SOURCES` is set.
7904
7905      This is one way of fulfilling "source code access" license
7906      requirements.
7907
7908      Such source archives are available in
7909      ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst``
7910      under the :term:`Build Directory`.
7911
7912      Enable this option as follows::
7913
7914         SPDX_INCLUDE_SOURCES = "1"
7915         SPDX_ARCHIVE_SOURCES = "1"
7916
7917      According to our tests on release 4.1 "langdale", building
7918      ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
7919      these options multiplied the size of the ``tmp/deploy/spdx``
7920      directory by a factor of 11 (+1.4 GiB for this image),
7921      compared to just using the :ref:`ref-classes-create-spdx`
7922      class with no option.
7923
7924      Note that using this option only marginally increases the size
7925      of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/``
7926      (+ 0.07\% with the tested image), compared to just enabling
7927      :term:`SPDX_INCLUDE_SOURCES`.
7928
7929   :term:`SPDX_CUSTOM_ANNOTATION_VARS`
7930      This option allows to associate `SPDX annotations
7931      <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
7932      using the values of variables in the recipe::
7933
7934         ANNOTATION1 = "First annotation for recipe"
7935         ANNOTATION2 = "Second annotation for recipe"
7936         SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"
7937
7938      This will add a new block to the recipe ``.sdpx.json`` output::
7939
7940         "annotations": [
7941           {
7942             "annotationDate": "2023-04-18T08:32:12Z",
7943             "annotationType": "OTHER",
7944             "annotator": "Tool: oe-spdx-creator - 1.0",
7945             "comment": "ANNOTATION1=First annotation for recipe"
7946           },
7947           {
7948             "annotationDate": "2023-04-18T08:32:12Z",
7949             "annotationType": "OTHER",
7950             "annotator": "Tool: oe-spdx-creator - 1.0",
7951             "comment": "ANNOTATION2=Second annotation for recipe"
7952           }
7953         ],
7954
7955   :term:`SPDX_INCLUDE_SOURCES`
7956      This option allows to add a description of the source files used to build
7957      the host tools and the target packages, to the ``spdx.json`` files in
7958      ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`.
7959      As a consequence, the ``spdx.json`` files under the ``by-namespace`` and
7960      ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also
7961      modified to include references to such source file descriptions.
7962
7963      Enable this option as follows::
7964
7965         SPDX_INCLUDE_SOURCES = "1"
7966
7967      According to our tests on release 4.1 "langdale", building
7968      ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
7969      this option multiplied the total size of the ``tmp/deploy/spdx``
7970      directory by a factor of 3  (+291 MiB for this image),
7971      and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in
7972      ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this
7973      image), compared to just using the :ref:`ref-classes-create-spdx` class
7974      with no option.
7975
7976   :term:`SPDX_NAMESPACE_PREFIX`
7977      This option could be used in order to change the prefix of ``spdxDocument``
7978      and the prefix of ``documentNamespace``. It is set by default to
7979      ``http://spdx.org/spdxdoc``.
7980
7981   :term:`SPDX_PRETTY`
7982      This option makes the SPDX output more human-readable, using
7983      identation and newlines, instead of the default output in a
7984      single line::
7985
7986         SPDX_PRETTY = "1"
7987
7988      The generated SPDX files are approximately 20% bigger, but
7989      this option is recommended if you want to inspect the SPDX
7990      output files with a text editor.
7991
7992   :term:`SPDXLICENSEMAP`
7993      Maps commonly used license names to their SPDX counterparts found in
7994      ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
7995      mappings, see the ``meta/conf/licenses.conf`` file.
7996
7997      For additional information, see the :term:`LICENSE`
7998      variable.
7999
8000   :term:`SPECIAL_PKGSUFFIX`
8001      A list of prefixes for :term:`PN` used by the OpenEmbedded
8002      build system to create variants of recipes or packages. The list
8003      specifies the prefixes to strip off during certain circumstances such
8004      as the generation of the :term:`BPN` variable.
8005
8006   :term:`SPL_BINARY`
8007      The file type for the Secondary Program Loader (SPL). Some devices
8008      use an SPL from which to boot (e.g. the BeagleBone development
8009      board). For such cases, you can declare the file type of the SPL
8010      binary in the ``u-boot.inc`` include file, which is used in the
8011      U-Boot recipe.
8012
8013      The SPL file type is set to "null" by default in the ``u-boot.inc``
8014      file as follows::
8015
8016         # Some versions of u-boot build an SPL (Second Program Loader) image that
8017         # should be packaged along with the u-boot binary as well as placed in the
8018         # deploy directory. For those versions they can set the following variables
8019         # to allow packaging the SPL.
8020         SPL_BINARY ?= ""
8021         SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
8022         SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
8023         SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
8024
8025      The :term:`SPL_BINARY` variable helps form
8026      various ``SPL_*`` variables used by the OpenEmbedded build system.
8027
8028      See the BeagleBone machine configuration example in the
8029      ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`"
8030      section in the Yocto Project Board Support Package Developer's Guide
8031      for additional information.
8032
8033   :term:`SPL_MKIMAGE_DTCOPTS`
8034      Options for the device tree compiler passed to ``mkimage -D`` feature
8035      while creating a FIT image with the :ref:`ref-classes-uboot-sign`
8036      class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the
8037      :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option
8038      to ``mkimage``.
8039
8040      The default value is set to "" by the :ref:`ref-classes-uboot-config`
8041      class.
8042
8043   :term:`SPL_SIGN_ENABLE`
8044      Enable signing of the U-Boot FIT image. The default value is "0".
8045      This variable is used by the :ref:`ref-classes-uboot-sign` class.
8046
8047   :term:`SPL_SIGN_KEYDIR`
8048      Location of the directory containing the RSA key and certificate used for
8049      signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign`
8050      class.
8051
8052   :term:`SPL_SIGN_KEYNAME`
8053      The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
8054      for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR`
8055      directory. If we have for example a ``dev.key`` key and a ``dev.crt``
8056      certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will
8057      have to set :term:`SPL_SIGN_KEYNAME` to ``dev``.
8058
8059   :term:`SPLASH`
8060      This variable, used by the :ref:`ref-classes-image` class, allows
8061      to choose splashscreen applications. Set it to the names of packages
8062      for such applications to use. This variable is set by default to
8063      ``psplash``.
8064
8065   :term:`SPLASH_IMAGES`
8066      This variable, used by the ``psplash`` recipe, allows to customize
8067      the default splashscreen image.
8068
8069      Specified images in PNG format are converted to ``.h`` files by the recipe,
8070      and are included in the ``psplash`` binary, so you won't find them in
8071      the root filesystem.
8072
8073      To make such a change, it is recommended to customize the
8074      ``psplash`` recipe in a custom layer. Here is an example structure for
8075      an ``ACME`` board::
8076
8077          meta-acme/recipes-core/psplash
8078          ├── files
8079          │   └── logo-acme.png
8080          └── psplash_%.bbappend
8081
8082      And here are the contents of the ``psplash_%.bbappend`` file in
8083      this example::
8084
8085          SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
8086          FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
8087
8088      You could even add specific configuration options for ``psplash``,
8089      for example::
8090
8091          EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"
8092
8093      For information on append files, see the
8094      ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
8095      section.
8096
8097   :term:`SRCREV_FORMAT`
8098      See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual.
8099
8100   :term:`SRC_URI`
8101
8102      See the BitBake manual for the initial description for this variable:
8103      :term:`bitbake:SRC_URI`.
8104
8105      The following features are added by OpenEmbedded and the Yocto Project.
8106
8107      There are standard and recipe-specific options. Here are standard ones:
8108
8109      -  ``apply`` --- whether to apply the patch or not. The default
8110         action is to apply the patch.
8111
8112      -  ``striplevel`` --- which striplevel to use when applying the
8113         patch. The default level is 1.
8114
8115      -  ``patchdir`` --- specifies the directory in which the patch should
8116         be applied. The default is ``${``\ :term:`S`\ ``}``.
8117
8118      Here are options specific to recipes building code from a revision
8119      control system:
8120
8121      -  ``mindate`` --- apply the patch only if
8122         :term:`SRCDATE` is equal to or greater than
8123         ``mindate``.
8124
8125      -  ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later
8126         than ``maxdate``.
8127
8128      -  ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or
8129         greater than ``minrev``.
8130
8131      -  ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later
8132         than ``maxrev``.
8133
8134      -  ``rev`` --- apply the patch only if :term:`SRCREV` is equal to
8135         ``rev``.
8136
8137      -  ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to
8138         ``rev``.
8139
8140      .. note::
8141
8142         If you want the build system to pick up files specified through
8143         a :term:`SRC_URI` statement from your append file, you need to be
8144         sure to extend the :term:`FILESPATH` variable by also using the
8145         :term:`FILESEXTRAPATHS` variable from within your append file.
8146
8147   :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
8148      By default, the OpenEmbedded build system automatically detects
8149      whether :term:`SRC_URI` contains files that are machine-specific. If so,
8150      the build system automatically changes :term:`PACKAGE_ARCH`. Setting this
8151      variable to "0" disables this behavior.
8152
8153   :term:`SRCDATE`
8154      The date of the source code used to build the package. This variable
8155      applies only if the source was fetched from a Source Code Manager
8156      (SCM).
8157
8158   :term:`SRCPV`
8159      Returns the version string of the current package. This string is
8160      used to help define the value of :term:`PV`.
8161
8162      The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf``
8163      configuration file in the :term:`Source Directory` as
8164      follows::
8165
8166         SRCPV = "${@bb.fetch2.get_srcrev(d)}"
8167
8168      Recipes that need to define :term:`PV` do so with the help of the
8169      :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``)
8170      located in ``meta/recipes-connectivity`` in the Source Directory
8171      defines :term:`PV` as follows::
8172
8173         PV = "0.12-git${SRCPV}"
8174
8175   :term:`SRCREV`
8176      The revision of the source code used to build the package. This
8177      variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
8178      that if you want to build a fixed revision and you want to avoid
8179      performing a query on the remote repository every time BitBake parses
8180      your recipe, you should specify a :term:`SRCREV` that is a full revision
8181      identifier (e.g. the full SHA hash in git) and not just a tag.
8182
8183      .. note::
8184
8185         For information on limitations when inheriting the latest revision
8186         of software using :term:`SRCREV`, see the :term:`AUTOREV` variable
8187         description and the
8188         ":ref:`dev-manual/packages:automatically incrementing a package version number`"
8189         section, which is in the Yocto Project Development Tasks Manual.
8190
8191   :term:`SRCTREECOVEREDTASKS`
8192      A list of tasks that are typically not relevant (and therefore skipped)
8193      when building using the :ref:`ref-classes-externalsrc`
8194      class. The default value as set in that class file is the set of tasks
8195      that are rarely needed when using external source::
8196
8197         SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
8198
8199      The notable exception is when processing external kernel source as
8200      defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for
8201      aesthetics)::
8202
8203         SRCTREECOVEREDTASKS += "\
8204           do_validate_branches \
8205           do_kernel_configcheck \
8206           do_kernel_checkout \
8207           do_fetch \
8208           do_unpack \
8209           do_patch \
8210         "
8211
8212      See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD`
8213      variables for more information.
8214
8215   :term:`SSTATE_DIR`
8216      The directory for the shared state cache.
8217
8218   :term:`SSTATE_EXCLUDEDEPS_SYSROOT`
8219      This variable allows to specify indirect dependencies to exclude
8220      from sysroots, for example to avoid the situations when a dependency on
8221      any ``-native`` recipe will pull in all dependencies of that recipe
8222      in the recipe sysroot. This behaviour might not always be wanted,
8223      for example when that ``-native`` recipe depends on build tools
8224      that are not relevant for the current recipe.
8225
8226      This way, irrelevant dependencies are ignored, which could have
8227      prevented the reuse of prebuilt artifacts stored in the Shared
8228      State Cache.
8229
8230      :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular
8231      expressions of recipe and dependency to ignore. An example
8232      is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`::
8233
8234         # Nothing needs to depend on libc-initial
8235         # base-passwd/shadow-sysroot don't need their dependencies
8236         SSTATE_EXCLUDEDEPS_SYSROOT += "\
8237             .*->.*-initial.* \
8238             .*(base-passwd|shadow-sysroot)->.* \
8239         "
8240
8241      The ``->`` substring represents the dependency between
8242      the two regular expressions.
8243
8244   :term:`SSTATE_MIRROR_ALLOW_NETWORK`
8245      If set to "1", allows fetches from mirrors that are specified in
8246      :term:`SSTATE_MIRRORS` to work even when
8247      fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to
8248      "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if
8249      you have set :term:`SSTATE_MIRRORS` to point to an internal server for
8250      your shared state cache, but you want to disable any other fetching
8251      from the network.
8252
8253   :term:`SSTATE_MIRRORS`
8254      Configures the OpenEmbedded build system to search other mirror
8255      locations for prebuilt cache data objects before building out the
8256      data. This variable works like fetcher :term:`MIRRORS`
8257      and :term:`PREMIRRORS` and points to the cache
8258      locations to check for the shared state (sstate) objects.
8259
8260      You can specify a filesystem directory or a remote URL such as HTTP
8261      or FTP. The locations you specify need to contain the shared state
8262      cache (sstate-cache) results from previous builds. The sstate-cache
8263      you point to can also be from builds on other machines.
8264
8265      When pointing to sstate build artifacts on another machine that uses
8266      a different GCC version for native builds, you must configure
8267      :term:`SSTATE_MIRRORS` with a regular expression that maps local search
8268      paths to server paths. The paths need to take into account
8269      :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class.
8270      For example, the following maps the local search path ``universal-4.9``
8271      to the server-provided path server_url_sstate_path::
8272
8273         SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1"
8274
8275      If a mirror uses the same structure as
8276      :term:`SSTATE_DIR`, you need to add "PATH" at the
8277      end as shown in the examples below. The build system substitutes the
8278      correct path within the directory structure::
8279
8280         SSTATE_MIRRORS ?= "\
8281             file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \
8282             file://.* file:///some-local-dir/sstate/PATH"
8283
8284      The Yocto Project actually shares the cache data objects built by its
8285      autobuilder::
8286
8287         SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH"
8288
8289      As such binary artifacts are built for the generic QEMU machines
8290      supported by the various Poky releases, they are less likely to be
8291      reusable in real projects building binaries optimized for a specific
8292      CPU family.
8293
8294   :term:`SSTATE_SCAN_FILES`
8295      Controls the list of files the OpenEmbedded build system scans for
8296      hardcoded installation paths. The variable uses a space-separated
8297      list of filenames (not paths) with standard wildcard characters
8298      allowed.
8299
8300      During a build, the OpenEmbedded build system creates a shared state
8301      (sstate) object during the first stage of preparing the sysroots.
8302      That object is scanned for hardcoded paths for original installation
8303      locations. The list of files that are scanned for paths is controlled
8304      by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files
8305      they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather
8306      than the variable being comprehensively set. The
8307      :ref:`ref-classes-sstate` class specifies the default list of files.
8308
8309      For details on the process, see the :ref:`ref-classes-staging` class.
8310
8311   :term:`STAGING_BASE_LIBDIR_NATIVE`
8312      Specifies the path to the ``/lib`` subdirectory of the sysroot
8313      directory for the build host.
8314
8315   :term:`STAGING_BASELIBDIR`
8316      Specifies the path to the ``/lib`` subdirectory of the sysroot
8317      directory for the target for which the current recipe is being built
8318      (:term:`STAGING_DIR_HOST`).
8319
8320   :term:`STAGING_BINDIR`
8321      Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
8322      directory for the target for which the current recipe is being built
8323      (:term:`STAGING_DIR_HOST`).
8324
8325   :term:`STAGING_BINDIR_CROSS`
8326      Specifies the path to the directory containing binary configuration
8327      scripts. These scripts provide configuration information for other
8328      software that wants to make use of libraries or include files
8329      provided by the software associated with the script.
8330
8331      .. note::
8332
8333         This style of build configuration has been largely replaced by
8334         ``pkg-config``. Consequently, if ``pkg-config`` is supported by the
8335         library to which you are linking, it is recommended you use
8336         ``pkg-config`` instead of a provided configuration script.
8337
8338   :term:`STAGING_BINDIR_NATIVE`
8339      Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
8340      directory for the build host.
8341
8342   :term:`STAGING_DATADIR`
8343      Specifies the path to the ``/usr/share`` subdirectory of the sysroot
8344      directory for the target for which the current recipe is being built
8345      (:term:`STAGING_DIR_HOST`).
8346
8347   :term:`STAGING_DATADIR_NATIVE`
8348      Specifies the path to the ``/usr/share`` subdirectory of the sysroot
8349      directory for the build host.
8350
8351   :term:`STAGING_DIR`
8352      Helps construct the ``recipe-sysroots`` directory, which is used
8353      during packaging.
8354
8355      For information on how staging for recipe-specific sysroots occurs,
8356      see the :ref:`ref-tasks-populate_sysroot`
8357      task, the ":ref:`sdk-manual/extensible:sharing files between recipes`"
8358      section in the Yocto Project Development Tasks Manual, the
8359      ":ref:`overview-manual/concepts:configuration, compilation, and staging`"
8360      section in the Yocto Project Overview and Concepts Manual, and the
8361      :term:`SYSROOT_DIRS` variable.
8362
8363      .. note::
8364
8365         Recipes should never write files directly under the :term:`STAGING_DIR`
8366         directory because the OpenEmbedded build system manages the
8367         directory automatically. Instead, files should be installed to
8368         ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install`
8369         task and then the OpenEmbedded build system will stage a subset of
8370         those files into the sysroot.
8371
8372   :term:`STAGING_DIR_HOST`
8373      Specifies the path to the sysroot directory for the system on which
8374      the component is built to run (the system that hosts the component).
8375      For most recipes, this sysroot is the one in which that recipe's
8376      :ref:`ref-tasks-populate_sysroot` task copies
8377      files. Exceptions include ``-native`` recipes, where the
8378      :ref:`ref-tasks-populate_sysroot` task instead uses
8379      :term:`STAGING_DIR_NATIVE`. Depending on
8380      the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
8381      have the following values:
8382
8383      -  For recipes building for the target machine, the value is
8384         "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
8385
8386      -  For native recipes building for the build host, the value is empty
8387         given the assumption that when building for the build host, the
8388         build host's own directories should be used.
8389
8390         .. note::
8391
8392            ``-native`` recipes are not installed into host paths like such
8393            as ``/usr``. Rather, these recipes are installed into
8394            :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
8395            standard build environment variables such as
8396            :term:`CPPFLAGS` and
8397            :term:`CFLAGS` are set up so that both host paths
8398            and :term:`STAGING_DIR_NATIVE` are searched for libraries and
8399            headers using, for example, GCC's ``-isystem`` option.
8400
8401            Thus, the emphasis is that the ``STAGING_DIR*`` variables
8402            should be viewed as input variables by tasks such as
8403            :ref:`ref-tasks-configure`,
8404            :ref:`ref-tasks-compile`, and
8405            :ref:`ref-tasks-install`. Having the real system
8406            root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
8407            for ``-native`` recipes, as they make use of host headers and
8408            libraries.
8409
8410      Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`.
8411
8412   :term:`STAGING_DIR_NATIVE`
8413      Specifies the path to the sysroot directory used when building
8414      components that run on the build host itself.
8415
8416      The default value is ``"${RECIPE_SYSROOT_NATIVE}"``,
8417      check :term:`RECIPE_SYSROOT_NATIVE`.
8418
8419   :term:`STAGING_DIR_TARGET`
8420      Specifies the path to the sysroot used for the system for which the
8421      component generates code. For components that do not generate code,
8422      which is the majority, :term:`STAGING_DIR_TARGET` is set to match
8423      :term:`STAGING_DIR_HOST`.
8424
8425      Some recipes build binaries that can run on the target system but those
8426      binaries in turn generate code for another different system (e.g.
8427      :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU,
8428      the primary system is referred to as the "HOST" and the secondary, or
8429      different, system is referred to as the "TARGET". Thus, the binaries
8430      run on the "HOST" system and generate binaries for the "TARGET"
8431      system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used
8432      for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the
8433      sysroot used for the "TARGET" system.
8434
8435   :term:`STAGING_ETCDIR_NATIVE`
8436      Specifies the path to the ``/etc`` subdirectory of the sysroot
8437      directory for the build host.
8438
8439   :term:`STAGING_EXECPREFIXDIR`
8440      Specifies the path to the ``/usr`` subdirectory of the sysroot
8441      directory for the target for which the current recipe is being built
8442      (:term:`STAGING_DIR_HOST`).
8443
8444   :term:`STAGING_INCDIR`
8445      Specifies the path to the ``/usr/include`` subdirectory of the
8446      sysroot directory for the target for which the current recipe being
8447      built (:term:`STAGING_DIR_HOST`).
8448
8449   :term:`STAGING_INCDIR_NATIVE`
8450      Specifies the path to the ``/usr/include`` subdirectory of the
8451      sysroot directory for the build host.
8452
8453   :term:`STAGING_KERNEL_BUILDDIR`
8454      Points to the directory containing the kernel build artifacts.
8455      Recipes building software that needs to access kernel build artifacts
8456      (e.g. ``systemtap-uprobes``) can look in the directory specified with
8457      the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts
8458      after the kernel has been built.
8459
8460   :term:`STAGING_KERNEL_DIR`
8461      The directory with kernel headers that are required to build
8462      out-of-tree modules.
8463
8464   :term:`STAGING_LIBDIR`
8465      Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
8466      directory for the target for which the current recipe is being built
8467      (:term:`STAGING_DIR_HOST`).
8468
8469   :term:`STAGING_LIBDIR_NATIVE`
8470      Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
8471      directory for the build host.
8472
8473   :term:`STAMP`
8474      Specifies the base path used to create recipe stamp files. The path
8475      to an actual stamp file is constructed by evaluating this string and
8476      then appending additional information. Currently, the default
8477      assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
8478      file is::
8479
8480         STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
8481
8482      For information on how BitBake uses stamp files to determine if a
8483      task should be rerun, see the
8484      ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
8485      section in the Yocto Project Overview and Concepts Manual.
8486
8487      See :term:`STAMPS_DIR`,
8488      :term:`MULTIMACH_TARGET_SYS`,
8489      :term:`PN`, :term:`EXTENDPE`,
8490      :term:`PV`, and :term:`PR` for related variable
8491      information.
8492
8493   :term:`STAMPCLEAN`
8494      See :term:`bitbake:STAMPCLEAN` in the BitBake manual.
8495
8496   :term:`STAMPS_DIR`
8497      Specifies the base directory in which the OpenEmbedded build system
8498      places stamps. The default directory is ``${TMPDIR}/stamps``.
8499
8500   :term:`STRIP`
8501      The minimal command and arguments to run ``strip``, which is used to
8502      strip symbols.
8503
8504   :term:`SUMMARY`
8505      The short (72 characters or less) summary of the binary package for
8506      packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
8507      :term:`SUMMARY` is used to define the
8508      :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is
8509      not set in the recipe.
8510
8511   :term:`SVNDIR`
8512      The directory in which files checked out of a Subversion system are
8513      stored.
8514
8515   :term:`SYSLINUX_DEFAULT_CONSOLE`
8516      Specifies the kernel boot default console. If you want to use a
8517      console other than the default, set this variable in your recipe as
8518      follows where "X" is the console number you want to use::
8519
8520         SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
8521
8522      The :ref:`ref-classes-syslinux` class initially sets
8523      this variable to null but then checks for a value later.
8524
8525   :term:`SYSLINUX_OPTS`
8526      Lists additional options to add to the syslinux file. You need to set
8527      this variable in your recipe. If you want to list multiple options,
8528      separate the options with a semicolon character (``;``).
8529
8530      The :ref:`ref-classes-syslinux` class uses this variable
8531      to create a set of options.
8532
8533   :term:`SYSLINUX_SERIAL`
8534      Specifies the alternate serial port or turns it off. To turn off
8535      serial, set this variable to an empty string in your recipe. The
8536      variable's default value is set in the
8537      :ref:`ref-classes-syslinux` class as follows::
8538
8539         SYSLINUX_SERIAL ?= "0 115200"
8540
8541      The class checks for and uses the variable as needed.
8542
8543   :term:`SYSLINUX_SERIAL_TTY`
8544      Specifies the alternate console=tty... kernel boot argument. The
8545      variable's default value is set in the :ref:`ref-classes-syslinux`
8546      class as follows::
8547
8548         SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
8549
8550      The class checks for and uses the variable as needed.
8551
8552   :term:`SYSLINUX_SPLASH`
8553      An ``.LSS`` file used as the background for the VGA boot menu when
8554      you use the boot menu. You need to set this variable in your recipe.
8555
8556      The :ref:`ref-classes-syslinux` class checks for this
8557      variable and if found, the OpenEmbedded build system installs the
8558      splash screen.
8559
8560   :term:`SYSROOT_DESTDIR`
8561      Points to the temporary directory under the work directory (default
8562      "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
8563      where the files populated into the sysroot are assembled during the
8564      :ref:`ref-tasks-populate_sysroot` task.
8565
8566   :term:`SYSROOT_DIRS`
8567      Directories that are staged into the sysroot by the
8568      :ref:`ref-tasks-populate_sysroot` task. By
8569      default, the following directories are staged::
8570
8571         SYSROOT_DIRS = " \
8572             ${includedir} \
8573             ${libdir} \
8574             ${base_libdir} \
8575             ${nonarch_base_libdir} \
8576             ${datadir} \
8577             /sysroot-only \
8578             "
8579
8580   :term:`SYSROOT_DIRS_IGNORE`
8581      Directories that are not staged into the sysroot by the
8582      :ref:`ref-tasks-populate_sysroot` task. You
8583      can use this variable to exclude certain subdirectories of
8584      directories listed in :term:`SYSROOT_DIRS` from
8585      staging. By default, the following directories are not staged::
8586
8587         SYSROOT_DIRS_IGNORE = " \
8588             ${mandir} \
8589             ${docdir} \
8590             ${infodir} \
8591             ${datadir}/X11/locale \
8592             ${datadir}/applications \
8593             ${datadir}/bash-completion \
8594             ${datadir}/fonts \
8595             ${datadir}/gtk-doc/html \
8596             ${datadir}/installed-tests \
8597             ${datadir}/locale \
8598             ${datadir}/pixmaps \
8599             ${datadir}/terminfo \
8600             ${libdir}/${BPN}/ptest \
8601             "
8602
8603      Consider the following example in which you need to manipulate this variable.
8604      Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is
8605      installed into a custom folder other than "``${libdir}``"
8606      or "``${base_libdir}``", let's say "``/opt/lib``".
8607
8608      .. note::
8609
8610         This is not a recommended way to deal with shared libraries, but this
8611         is just to show the usefulness of setting :term:`SYSROOT_DIRS`.
8612
8613      When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in
8614      :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``B``
8615      into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``".
8616
8617      Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to
8618      ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So,
8619      the linking process will fail.
8620
8621      To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`::
8622
8623         SYSROOT_DIRS:append = " /opt/lib"
8624
8625      .. note::
8626         Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail
8627         because the linker does not know that location, since :term:`TARGET_LDFLAGS`
8628         doesn't contain it (if your recipe is for the target). Therefore, so you should add::
8629
8630            TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"
8631
8632   :term:`SYSROOT_DIRS_NATIVE`
8633      Extra directories staged into the sysroot by the
8634      :ref:`ref-tasks-populate_sysroot` task for
8635      ``-native`` recipes, in addition to those specified in
8636      :term:`SYSROOT_DIRS`. By default, the following
8637      extra directories are staged::
8638
8639         SYSROOT_DIRS_NATIVE = " \
8640             ${bindir} \
8641             ${sbindir} \
8642             ${base_bindir} \
8643             ${base_sbindir} \
8644             ${libexecdir} \
8645             ${sysconfdir} \
8646             ${localstatedir} \
8647             "
8648
8649      .. note::
8650
8651         Programs built by ``-native`` recipes run directly from the sysroot
8652         (:term:`STAGING_DIR_NATIVE`), which is why additional directories
8653         containing program executables and supporting files need to be staged.
8654
8655   :term:`SYSROOT_PREPROCESS_FUNCS`
8656      A list of functions to execute after files are staged into the
8657      sysroot. These functions are usually used to apply additional
8658      processing on the staged files, or to stage additional files.
8659
8660   :term:`SYSTEMD_AUTO_ENABLE`
8661      When inheriting the :ref:`ref-classes-systemd` class,
8662      this variable specifies whether the specified service in
8663      :term:`SYSTEMD_SERVICE` should start
8664      automatically or not. By default, the service is enabled to
8665      automatically start at boot time. The default setting is in the
8666      :ref:`ref-classes-systemd` class as follows::
8667
8668         SYSTEMD_AUTO_ENABLE ??= "enable"
8669
8670      You can disable the service by setting the variable to "disable".
8671
8672   :term:`SYSTEMD_BOOT_CFG`
8673      When :term:`EFI_PROVIDER` is set to
8674      "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
8675      configuration file that should be used. By default, the
8676      :ref:`ref-classes-systemd-boot` class sets the
8677      :term:`SYSTEMD_BOOT_CFG` as follows::
8678
8679         SYSTEMD_BOOT_CFG ?= "${S}/loader.conf"
8680
8681      For information on Systemd-boot, see the `Systemd-boot
8682      documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
8683
8684   :term:`SYSTEMD_BOOT_ENTRIES`
8685      When :term:`EFI_PROVIDER` is set to
8686      "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
8687      list of entry files (``*.conf``) to install that contain one boot
8688      entry per file. By default, the :ref:`ref-classes-systemd-boot` class
8689      sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows::
8690
8691          SYSTEMD_BOOT_ENTRIES ?= ""
8692
8693      For information on Systemd-boot, see the `Systemd-boot
8694      documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
8695
8696   :term:`SYSTEMD_BOOT_TIMEOUT`
8697      When :term:`EFI_PROVIDER` is set to
8698      "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
8699      boot menu timeout in seconds. By default, the
8700      :ref:`ref-classes-systemd-boot` class sets the
8701      :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
8702
8703         SYSTEMD_BOOT_TIMEOUT ?= "10"
8704
8705      For information on Systemd-boot, see the `Systemd-boot
8706      documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
8707
8708   :term:`SYSTEMD_DEFAULT_TARGET`
8709
8710      This variable allows to set the default unit that systemd starts at bootup.
8711      Usually, this is either ``multi-user.target`` or ``graphical.target``.
8712      This works by creating a ``default.target`` symbolic link to the chosen systemd
8713      target file.
8714
8715      See `systemd's documentation
8716      <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__
8717      for details.
8718
8719      For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb
8720      </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`
8721      recipe::
8722
8723          SYSTEMD_DEFAULT_TARGET = "graphical.target"
8724
8725   :term:`SYSTEMD_PACKAGES`
8726      When inheriting the :ref:`ref-classes-systemd` class,
8727      this variable locates the systemd unit files when they are not found
8728      in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
8729      variable is set such that the systemd unit files are assumed to
8730      reside in the recipes main package::
8731
8732         SYSTEMD_PACKAGES ?= "${PN}"
8733
8734      If these unit files are not in this recipe's main package, you need
8735      to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which
8736      the build system can find the systemd unit files.
8737
8738   :term:`SYSTEMD_SERVICE`
8739      When inheriting the :ref:`ref-classes-systemd` class,
8740      this variable specifies the systemd service name for a package.
8741
8742      Multiple services can be specified, each one separated by a space.
8743
8744      When you specify this file in your recipe, use a package name
8745      override to indicate the package to which the value applies. Here is
8746      an example from the connman recipe::
8747
8748         SYSTEMD_SERVICE:${PN} = "connman.service"
8749
8750      The package overrides that can be specified are directly related to the value of
8751      :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES`
8752      will be silently ignored.
8753
8754   :term:`SYSVINIT_ENABLED_GETTYS`
8755      When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
8756      specifies a space-separated list of the virtual terminals that should
8757      run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming
8758      :term:`USE_VT` is not set to "0".
8759
8760      The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only
8761      run a getty on the first virtual terminal).
8762
8763   :term:`T`
8764      This variable points to a directory were BitBake places temporary
8765      files, which consist mostly of task logs and scripts, when building a
8766      particular recipe. The variable is typically set as follows::
8767
8768         T = "${WORKDIR}/temp"
8769
8770      The :term:`WORKDIR` is the directory into which
8771      BitBake unpacks and builds the recipe. The default ``bitbake.conf``
8772      file sets this variable.
8773
8774      The :term:`T` variable is not to be confused with the
8775      :term:`TMPDIR` variable, which points to the root of
8776      the directory tree where BitBake places the output of an entire
8777      build.
8778
8779   :term:`TARGET_ARCH`
8780      The target machine's architecture. The OpenEmbedded build system
8781      supports many architectures. Here is an example list of architectures
8782      supported. This list is by no means complete as the architecture is
8783      configurable:
8784
8785      - arm
8786      - i586
8787      - x86_64
8788      - powerpc
8789      - powerpc64
8790      - mips
8791      - mipsel
8792
8793      For additional information on machine architectures, see the
8794      :term:`TUNE_ARCH` variable.
8795
8796   :term:`TARGET_AS_ARCH`
8797      Specifies architecture-specific assembler flags for the target
8798      system. :term:`TARGET_AS_ARCH` is initialized from
8799      :term:`TUNE_ASARGS` by default in the BitBake
8800      configuration file (``meta/conf/bitbake.conf``)::
8801
8802         TARGET_AS_ARCH = "${TUNE_ASARGS}"
8803
8804   :term:`TARGET_CC_ARCH`
8805      Specifies architecture-specific C compiler flags for the target
8806      system. :term:`TARGET_CC_ARCH` is initialized from
8807      :term:`TUNE_CCARGS` by default.
8808
8809      .. note::
8810
8811         It is a common workaround to append :term:`LDFLAGS` to
8812         :term:`TARGET_CC_ARCH` in recipes that build software for the target that
8813         would not otherwise respect the exported :term:`LDFLAGS` variable.
8814
8815   :term:`TARGET_CC_KERNEL_ARCH`
8816      This is a specific kernel compiler flag for a CPU or Application
8817      Binary Interface (ABI) tune. The flag is used rarely and only for
8818      cases where a userspace :term:`TUNE_CCARGS` is not
8819      compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH`
8820      variable allows the kernel (and associated modules) to use a
8821      different configuration. See the
8822      ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
8823      :term:`Source Directory` for an example.
8824
8825   :term:`TARGET_CFLAGS`
8826      Specifies the flags to pass to the C compiler when building for the
8827      target. When building in the target context,
8828      :term:`CFLAGS` is set to the value of this variable by
8829      default.
8830
8831      Additionally, the SDK's environment setup script sets the :term:`CFLAGS`
8832      variable in the environment to the :term:`TARGET_CFLAGS` value so that
8833      executables built using the SDK also have the flags applied.
8834
8835   :term:`TARGET_CPPFLAGS`
8836      Specifies the flags to pass to the C pre-processor (i.e. to both the
8837      C and the C++ compilers) when building for the target. When building
8838      in the target context, :term:`CPPFLAGS` is set to the
8839      value of this variable by default.
8840
8841      Additionally, the SDK's environment setup script sets the
8842      :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS`
8843      value so that executables built using the SDK also have the flags
8844      applied.
8845
8846   :term:`TARGET_CXXFLAGS`
8847      Specifies the flags to pass to the C++ compiler when building for the
8848      target. When building in the target context,
8849      :term:`CXXFLAGS` is set to the value of this variable
8850      by default.
8851
8852      Additionally, the SDK's environment setup script sets the
8853      :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS`
8854      value so that executables built using the SDK also have the flags
8855      applied.
8856
8857   :term:`TARGET_DBGSRC_DIR`
8858      Specifies the target path to debug source files. The default is
8859      ``/usr/src/debug/${PN}/${PV}``.
8860
8861   :term:`TARGET_FPU`
8862      Specifies the method for handling FPU code. For FPU-less targets,
8863      which include most ARM CPUs, the variable must be set to "soft". If
8864      not, the kernel emulation gets used, which results in a performance
8865      penalty.
8866
8867   :term:`TARGET_LD_ARCH`
8868      Specifies architecture-specific linker flags for the target system.
8869      :term:`TARGET_LD_ARCH` is initialized from
8870      :term:`TUNE_LDARGS` by default in the BitBake
8871      configuration file (``meta/conf/bitbake.conf``)::
8872
8873         TARGET_LD_ARCH = "${TUNE_LDARGS}"
8874
8875   :term:`TARGET_LDFLAGS`
8876      Specifies the flags to pass to the linker when building for the
8877      target. When building in the target context,
8878      :term:`LDFLAGS` is set to the value of this variable
8879      by default.
8880
8881      Additionally, the SDK's environment setup script sets the
8882      :term:`LDFLAGS` variable in the environment to the
8883      :term:`TARGET_LDFLAGS` value so that executables built using the SDK also
8884      have the flags applied.
8885
8886   :term:`TARGET_OS`
8887      Specifies the target's operating system. The variable can be set to
8888      "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
8889      for musl libc. For ARM/EABI targets, the possible values are
8890      "linux-gnueabi" and "linux-musleabi".
8891
8892   :term:`TARGET_PREFIX`
8893      Specifies the prefix used for the toolchain binary target tools.
8894
8895      Depending on the type of recipe and the build target,
8896      :term:`TARGET_PREFIX` is set as follows:
8897
8898      -  For recipes building for the target machine, the value is
8899         "${:term:`TARGET_SYS`}-".
8900
8901      -  For native recipes, the build system sets the variable to the
8902         value of :term:`BUILD_PREFIX`.
8903
8904      -  For native SDK recipes (:ref:`ref-classes-nativesdk`),
8905         the build system sets the variable to the value of :term:`SDK_PREFIX`.
8906
8907   :term:`TARGET_SYS`
8908      Specifies the system, including the architecture and the operating
8909      system, for which the build is occurring in the context of the
8910      current recipe.
8911
8912      The OpenEmbedded build system automatically sets this variable based
8913      on :term:`TARGET_ARCH`,
8914      :term:`TARGET_VENDOR`, and
8915      :term:`TARGET_OS` variables.
8916
8917      .. note::
8918
8919         You do not need to set the :term:`TARGET_SYS` variable yourself.
8920
8921      Consider these two examples:
8922
8923      -  Given a native recipe on a 32-bit, x86 machine running Linux, the
8924         value is "i686-linux".
8925
8926      -  Given a recipe being built for a little-endian, MIPS target
8927         running Linux, the value might be "mipsel-linux".
8928
8929   :term:`TARGET_VENDOR`
8930      Specifies the name of the target vendor.
8931
8932   :term:`TCLIBC`
8933      Specifies the GNU standard C library (``libc``) variant to use during
8934      the build process.
8935
8936      You can select "glibc", "musl", "newlib", or "baremetal".
8937
8938   :term:`TCLIBCAPPEND`
8939      Specifies a suffix to be appended onto the :term:`TMPDIR` value. The
8940      suffix identifies the ``libc`` variant for building. When you are
8941      building for multiple variants with the same :term:`Build Directory`,
8942      this mechanism ensures that output for different ``libc`` variants is
8943      kept separate to avoid potential conflicts.
8944
8945      In the ``defaultsetup.conf`` file, the default value of
8946      :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky,
8947      which normally only support one ``libc`` variant, set
8948      :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting
8949      in no suffix being applied.
8950
8951   :term:`TCMODE`
8952      Specifies the toolchain selector. :term:`TCMODE` controls the
8953      characteristics of the generated packages and images by telling the
8954      OpenEmbedded build system which toolchain profile to use. By default,
8955      the OpenEmbedded build system builds its own internal toolchain. The
8956      variable's default value is "default", which uses that internal
8957      toolchain.
8958
8959      .. note::
8960
8961         If :term:`TCMODE` is set to a value other than "default", then it is your
8962         responsibility to ensure that the toolchain is compatible with the
8963         default toolchain. Using older or newer versions of these
8964         components might cause build problems. See
8965         :doc:`Release Information </migration-guides/index>` for your
8966         version of the Yocto Project, to find the specific components with
8967         which the toolchain must be compatible.
8968
8969      The :term:`TCMODE` variable is similar to :term:`TCLIBC`,
8970      which controls the variant of the GNU standard C library (``libc``)
8971      used during the build process: ``glibc`` or ``musl``.
8972
8973      With additional layers, it is possible to use a pre-compiled external
8974      toolchain. One example is the Sourcery G++ Toolchain. The support for
8975      this toolchain resides in the separate Mentor Graphics
8976      ``meta-sourcery`` layer at
8977      https://github.com/MentorEmbedded/meta-sourcery/.
8978
8979      The layer's ``README`` file contains information on how to use the
8980      Sourcery G++ Toolchain as an external toolchain. You will have to
8981      add the layer to your ``bblayers.conf`` file and then set the
8982      :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to
8983      the location of the toolchain.
8984
8985      The fundamentals used for this example apply to any external
8986      toolchain. You can use ``meta-sourcery`` as a template for adding
8987      support for other external toolchains.
8988
8989      In addition to toolchain configuration, you will also need a
8990      corresponding toolchain recipe file. This recipe file needs to package
8991      up any pre-built objects in the toolchain such as ``libgcc``,
8992      ``libstdcc++``, any locales, and ``libc``.
8993
8994   :term:`TC_CXX_RUNTIME`
8995      Specifies the C/C++ STL and runtime variant to use during
8996      the build process. Default value is 'gnu'
8997
8998      You can select "gnu", "llvm", or "android".
8999
9000   :term:`TEMPLATECONF`
9001      Specifies the directory used by the build system to find templates
9002      from which to build the ``bblayers.conf`` and ``local.conf`` files.
9003      Use this variable if you wish to customize such files, and the default
9004      BitBake targets shown when sourcing the ``oe-init-build-env`` script.
9005
9006      For details, see the
9007      :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`
9008      section in the Yocto Project Development Tasks manual.
9009
9010      .. note::
9011
9012         You must set this variable in the external environment in order
9013         for it to work.
9014
9015   :term:`TEST_EXPORT_DIR`
9016      The location the OpenEmbedded build system uses to export tests when
9017      the :term:`TEST_EXPORT_ONLY` variable is set
9018      to "1".
9019
9020      The :term:`TEST_EXPORT_DIR` variable defaults to
9021      ``"${TMPDIR}/testimage/${PN}"``.
9022
9023   :term:`TEST_EXPORT_ONLY`
9024      Specifies to export the tests only. Set this variable to "1" if you
9025      do not want to run the tests but you want them to be exported in a
9026      manner that you to run them outside of the build system.
9027
9028   :term:`TEST_LOG_DIR`
9029      Holds the SSH log and the boot log for QEMU machines. The
9030      :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``.
9031
9032      .. note::
9033
9034         Actual test results reside in the task log (``log.do_testimage``),
9035         which is in the ``${WORKDIR}/temp/`` directory.
9036
9037   :term:`TEST_POWERCONTROL_CMD`
9038      For automated hardware testing, specifies the command to use to
9039      control the power of the target machine under test. Typically, this
9040      command would point to a script that performs the appropriate action
9041      (e.g. interacting with a web-enabled power strip). The specified
9042      command should expect to receive as the last argument "off", "on" or
9043      "cycle" specifying to power off, on, or cycle (power off and then
9044      power on) the device, respectively.
9045
9046   :term:`TEST_POWERCONTROL_EXTRA_ARGS`
9047      For automated hardware testing, specifies additional arguments to
9048      pass through to the command specified in
9049      :term:`TEST_POWERCONTROL_CMD`. Setting
9050      :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you
9051      wish, for example, to separate the machine-specific and
9052      non-machine-specific parts of the arguments.
9053
9054   :term:`TEST_QEMUBOOT_TIMEOUT`
9055      The time in seconds allowed for an image to boot before automated
9056      runtime tests begin to run against an image. The default timeout
9057      period to allow the boot process to reach the login prompt is 500
9058      seconds. You can specify a different value in the ``local.conf``
9059      file.
9060
9061      For more information on testing images, see the
9062      ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
9063      section in the Yocto Project Development Tasks Manual.
9064
9065   :term:`TEST_SERIALCONTROL_CMD`
9066      For automated hardware testing, specifies the command to use to
9067      connect to the serial console of the target machine under test. This
9068      command simply needs to connect to the serial console and forward
9069      that connection to standard input and output as any normal terminal
9070      program does.
9071
9072      For example, to use the Picocom terminal program on serial device
9073      ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
9074
9075         TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
9076
9077   :term:`TEST_SERIALCONTROL_EXTRA_ARGS`
9078      For automated hardware testing, specifies additional arguments to
9079      pass through to the command specified in
9080      :term:`TEST_SERIALCONTROL_CMD`. Setting
9081      :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you
9082      wish, for example, to separate the machine-specific and
9083      non-machine-specific parts of the command.
9084
9085   :term:`TEST_SERVER_IP`
9086      The IP address of the build machine (host machine). This IP address
9087      is usually automatically detected. However, if detection fails, this
9088      variable needs to be set to the IP address of the build machine (i.e.
9089      where the build is taking place).
9090
9091      .. note::
9092
9093         The :term:`TEST_SERVER_IP` variable is only used for a small number of
9094         tests such as the "dnf" test suite, which needs to download packages
9095         from ``WORKDIR/oe-rootfs-repo``.
9096
9097   :term:`TEST_SUITES`
9098      An ordered list of tests (modules) to run against an image when
9099      performing automated runtime testing.
9100
9101      The OpenEmbedded build system provides a core set of tests that can
9102      be used against images.
9103
9104      .. note::
9105
9106         Currently, there is only support for running these tests under
9107         QEMU.
9108
9109      Tests include ``ping``, ``ssh``, ``df`` among others. You can add
9110      your own tests to the list of tests by appending :term:`TEST_SUITES` as
9111      follows::
9112
9113         TEST_SUITES:append = " mytest"
9114
9115      Alternatively, you can
9116      provide the "auto" option to have all applicable tests run against
9117      the image::
9118
9119         TEST_SUITES:append = " auto"
9120
9121      Using this option causes the
9122      build system to automatically run tests that are applicable to the
9123      image. Tests that are not applicable are skipped.
9124
9125      The order in which tests are run is important. Tests that depend on
9126      another test must appear later in the list than the test on which
9127      they depend. For example, if you append the list of tests with two
9128      tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
9129      ``test_A``, then you must order the tests as follows::
9130
9131         TEST_SUITES = "test_A test_B"
9132
9133      For more information on testing images, see the
9134      ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
9135      section in the Yocto Project Development Tasks Manual.
9136
9137   :term:`TEST_TARGET`
9138      Specifies the target controller to use when running tests against a
9139      test image. The default controller to use is "qemu"::
9140
9141         TEST_TARGET = "qemu"
9142
9143      A target controller is a class that defines how an image gets
9144      deployed on a target and how a target is started. A layer can extend
9145      the controllers by adding a module in the layer's
9146      ``/lib/oeqa/controllers`` directory and by inheriting the
9147      ``BaseTarget`` class, which is an abstract class that cannot be used
9148      as a value of :term:`TEST_TARGET`.
9149
9150      You can provide the following arguments with :term:`TEST_TARGET`:
9151
9152      -  *"qemu":* Boots a QEMU image and runs the tests. See the
9153         ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section
9154         in the Yocto Project Development Tasks Manual for more
9155         information.
9156
9157      -  *"simpleremote":* Runs the tests on target hardware that is
9158         already up and running. The hardware can be on the network or it
9159         can be a device running an image on QEMU. You must also set
9160         :term:`TEST_TARGET_IP` when you use
9161         "simpleremote".
9162
9163         .. note::
9164
9165            This argument is defined in
9166            ``meta/lib/oeqa/controllers/simpleremote.py``.
9167
9168      For information on running tests on hardware, see the
9169      ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`"
9170      section in the Yocto Project Development Tasks Manual.
9171
9172   :term:`TEST_TARGET_IP`
9173      The IP address of your hardware under test. The :term:`TEST_TARGET_IP`
9174      variable has no effect when :term:`TEST_TARGET` is
9175      set to "qemu".
9176
9177      When you specify the IP address, you can also include a port. Here is
9178      an example::
9179
9180         TEST_TARGET_IP = "192.168.1.4:2201"
9181
9182      Specifying a port is
9183      useful when SSH is started on a non-standard port or in cases when
9184      your hardware under test is behind a firewall or network that is not
9185      directly accessible from your host and you need to do port address
9186      translation.
9187
9188   :term:`TESTIMAGE_AUTO`
9189      Automatically runs the series of automated tests for images when an
9190      image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes
9191      any image that successfully builds to automatically boot under QEMU.
9192      Using the variable also adds in dependencies so that any SDK for
9193      which testing is requested is automatically built first.
9194
9195      These tests are written in Python making use of the ``unittest``
9196      module, and the majority of them run commands on the target system
9197      over ``ssh``. You can set this variable to "1" in your ``local.conf``
9198      file in the :term:`Build Directory` to have the
9199      OpenEmbedded build system automatically run these tests after an
9200      image successfully builds:
9201
9202         TESTIMAGE_AUTO = "1"
9203
9204      For more information
9205      on enabling, running, and writing these tests, see the
9206      ":ref:`dev-manual/runtime-testing:performing automated runtime testing`"
9207      section in the Yocto Project Development Tasks Manual and the
9208      ":ref:`ref-classes-testimage`" section.
9209
9210   :term:`THISDIR`
9211      The directory in which the file BitBake is currently parsing is
9212      located. Do not manually set this variable.
9213
9214   :term:`TIME`
9215      The time the build was started. Times appear using the hour, minute,
9216      and second (HMS) format (e.g. "140159" for one minute and fifty-nine
9217      seconds past 1400 hours).
9218
9219   :term:`TMPDIR`
9220      This variable is the base directory the OpenEmbedded build system
9221      uses for all build output and intermediate files (other than the
9222      shared state cache). By default, the :term:`TMPDIR` variable points to
9223      ``tmp`` within the :term:`Build Directory`.
9224
9225      If you want to establish this directory in a location other than the
9226      default, you can uncomment and edit the following statement in the
9227      ``conf/local.conf`` file in the :term:`Source Directory`::
9228
9229         #TMPDIR = "${TOPDIR}/tmp"
9230
9231      An example use for this scenario is to set :term:`TMPDIR` to a local disk,
9232      which does not use NFS, while having the :term:`Build Directory` use NFS.
9233
9234      The filesystem used by :term:`TMPDIR` must have standard filesystem
9235      semantics (i.e. mixed-case files are unique, POSIX file locking, and
9236      persistent inodes). Due to various issues with NFS and bugs in some
9237      implementations, NFS does not meet this minimum requirement.
9238      Consequently, :term:`TMPDIR` cannot be on NFS.
9239
9240   :term:`TOOLCHAIN_HOST_TASK`
9241      This variable lists packages the OpenEmbedded build system uses when
9242      building an SDK, which contains a cross-development environment. The
9243      packages specified by this variable are part of the toolchain set
9244      that runs on the :term:`SDKMACHINE`, and each
9245      package should usually have the prefix ``nativesdk-``. For example,
9246      consider the following command when building an SDK::
9247
9248         $ bitbake -c populate_sdk imagename
9249
9250      In this case, a default list of packages is
9251      set in this variable, but you can add additional packages to the
9252      list. See the
9253      ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
9254      in the Yocto Project Application Development and the Extensible
9255      Software Development Kit (eSDK) manual for more information.
9256
9257      For background information on cross-development toolchains in the
9258      Yocto Project development environment, see the
9259      ":ref:`sdk-manual/intro:the cross-development toolchain`"
9260      section in the Yocto Project Overview and Concepts Manual. For
9261      information on setting up a cross-development environment, see the
9262      :doc:`/sdk-manual/index` manual.
9263
9264      Note that this variable applies to building an SDK, not an eSDK,
9265      in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be
9266      used instead.
9267
9268   :term:`TOOLCHAIN_HOST_TASK_ESDK`
9269      This variable allows to extend what is installed in the host
9270      portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
9271      applying to SDKs.
9272
9273   :term:`TOOLCHAIN_OPTIONS`
9274      This variable holds extra options passed to the compiler and the linker
9275      for non ``-native`` recipes as they have to point to their custom
9276      ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`::
9277
9278         TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"
9279
9280      Native recipes don't need this variable to be set, as they are
9281      built for the host machine with the native compiler.
9282
9283   :term:`TOOLCHAIN_OUTPUTNAME`
9284      This variable defines the name used for the toolchain output. The
9285      :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
9286      the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
9287
9288         TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
9289
9290      See
9291      the :term:`SDK_NAME` and
9292      :term:`SDK_VERSION` variables for additional
9293      information.
9294
9295   :term:`TOOLCHAIN_TARGET_TASK`
9296      This variable lists packages the OpenEmbedded build system uses when
9297      it creates the target part of an SDK (i.e. the part built for the
9298      target hardware), which includes libraries and headers. Use this
9299      variable to add individual packages to the part of the SDK that runs
9300      on the target. See the
9301      ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
9302      in the Yocto Project Application Development and the Extensible
9303      Software Development Kit (eSDK) manual for more information.
9304
9305      For background information on cross-development toolchains in the
9306      Yocto Project development environment, see the
9307      ":ref:`sdk-manual/intro:the cross-development toolchain`"
9308      section in the Yocto Project Overview and Concepts Manual. For
9309      information on setting up a cross-development environment, see the
9310      :doc:`/sdk-manual/index` manual.
9311
9312   :term:`TOPDIR`
9313      See :term:`bitbake:TOPDIR` in the BitBake manual.
9314
9315   :term:`TRANSLATED_TARGET_ARCH`
9316      A sanitized version of :term:`TARGET_ARCH`. This
9317      variable is used where the architecture is needed in a value where
9318      underscores are not allowed, for example within package filenames. In
9319      this case, dash characters replace any underscore characters used in
9320      :term:`TARGET_ARCH`.
9321
9322      Do not edit this variable.
9323
9324   :term:`TUNE_ARCH`
9325      The GNU canonical architecture for a specific architecture (i.e.
9326      ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
9327      this value to setup configuration.
9328
9329      :term:`TUNE_ARCH` definitions are specific to a given architecture. The
9330      definitions can be a single static definition, or can be dynamically
9331      adjusted. You can see details for a given CPU family by looking at
9332      the architecture's ``README`` file. For example, the
9333      ``meta/conf/machine/include/mips/README`` file in the
9334      :term:`Source Directory` provides information for
9335      :term:`TUNE_ARCH` specific to the ``mips`` architecture.
9336
9337      :term:`TUNE_ARCH` is tied closely to
9338      :term:`TARGET_ARCH`, which defines the target
9339      machine's architecture. The BitBake configuration file
9340      (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
9341
9342         TARGET_ARCH = "${TUNE_ARCH}"
9343
9344      The following list, which is by no means complete since architectures
9345      are configurable, shows supported machine architectures:
9346
9347      - arm
9348      - i586
9349      - x86_64
9350      - powerpc
9351      - powerpc64
9352      - mips
9353      - mipsel
9354
9355   :term:`TUNE_ASARGS`
9356      Specifies architecture-specific assembler flags for the target
9357      system. The set of flags is based on the selected tune features.
9358      :term:`TUNE_ASARGS` is set using the tune include files, which are
9359      typically under ``meta/conf/machine/include/`` and are influenced
9360      through :term:`TUNE_FEATURES`. For example, the
9361      ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
9362      for the x86 architecture as follows::
9363
9364         TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
9365
9366      .. note::
9367
9368         Board Support Packages (BSPs) select the tune. The selected tune,
9369         in turn, affects the tune variables themselves (i.e. the tune can
9370         supply its own set of flags).
9371
9372   :term:`TUNE_CCARGS`
9373      Specifies architecture-specific C compiler flags for the target
9374      system. The set of flags is based on the selected tune features.
9375      :term:`TUNE_CCARGS` is set using the tune include files, which are
9376      typically under ``meta/conf/machine/include/`` and are influenced
9377      through :term:`TUNE_FEATURES`.
9378
9379      .. note::
9380
9381         Board Support Packages (BSPs) select the tune. The selected tune,
9382         in turn, affects the tune variables themselves (i.e. the tune can
9383         supply its own set of flags).
9384
9385   :term:`TUNE_FEATURES`
9386      Features used to "tune" a compiler for optimal use given a specific
9387      processor. The features are defined within the tune files and allow
9388      arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
9389      the features.
9390
9391      The OpenEmbedded build system verifies the features to be sure they
9392      are not conflicting and that they are supported.
9393
9394      The BitBake configuration file (``meta/conf/bitbake.conf``) defines
9395      :term:`TUNE_FEATURES` as follows::
9396
9397         TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"
9398
9399      See the :term:`DEFAULTTUNE` variable for more information.
9400
9401   :term:`TUNE_LDARGS`
9402      Specifies architecture-specific linker flags for the target system.
9403      The set of flags is based on the selected tune features.
9404      :term:`TUNE_LDARGS` is set using the tune include files, which are
9405      typically under ``meta/conf/machine/include/`` and are influenced
9406      through :term:`TUNE_FEATURES`. For example, the
9407      ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
9408      for the x86 architecture as follows::
9409
9410         TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
9411
9412      .. note::
9413
9414         Board Support Packages (BSPs) select the tune. The selected tune,
9415         in turn, affects the tune variables themselves (i.e. the tune can
9416         supply its own set of flags).
9417
9418   :term:`TUNE_PKGARCH`
9419      The package architecture understood by the packaging system to define
9420      the architecture, ABI, and tuning of output packages. The specific
9421      tune is defined using the "_tune" override as follows::
9422
9423         TUNE_PKGARCH:tune-tune = "tune"
9424
9425      These tune-specific package architectures are defined in the machine
9426      include files. Here is an example of the "core2-32" tuning as used in
9427      the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
9428
9429         TUNE_PKGARCH:tune-core2-32 = "core2-32"
9430
9431   :term:`TUNECONFLICTS[feature]`
9432      Specifies CPU or Application Binary Interface (ABI) tuning features
9433      that conflict with feature.
9434
9435      Known tuning conflicts are specified in the machine include files in
9436      the :term:`Source Directory`. Here is an example from
9437      the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
9438      that lists the "o32" and "n64" features as conflicting with the "n32"
9439      feature::
9440
9441         TUNECONFLICTS[n32] = "o32 n64"
9442
9443   :term:`TUNEVALID[feature]`
9444      Specifies a valid CPU or Application Binary Interface (ABI) tuning
9445      feature. The specified feature is stored as a flag. Valid features
9446      are specified in the machine include files (e.g.
9447      ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
9448      from that file::
9449
9450         TUNEVALID[bigendian] = "Enable big-endian mode."
9451
9452      See the machine include files in the :term:`Source Directory`
9453      for these features.
9454
9455   :term:`UBOOT_BINARY`
9456      Specifies the name of the binary build by U-Boot.
9457
9458   :term:`UBOOT_CONFIG`
9459      Configures one or more U-Boot configurations to build. Each
9460      configuration can define the :term:`UBOOT_MACHINE` and optionally the
9461      :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`.
9462
9463      Here is an example from the ``meta-freescale`` layer. ::
9464
9465         UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"
9466         UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig"
9467         UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin"
9468         UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin"
9469         UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig"
9470         UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig"
9471         UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig"
9472         UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin"
9473
9474      In this example, all possible seven configurations are selected. Each
9475      configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and
9476      the "sd..." configurations define an individual name for
9477      :term:`UBOOT_BINARY`. No configuration defines a second parameter for
9478      :term:`IMAGE_FSTYPES` to use for the U-Boot image.
9479
9480      For more information on how the :term:`UBOOT_CONFIG` is handled, see the
9481      :ref:`ref-classes-uboot-config` class.
9482
9483   :term:`UBOOT_DTB_LOADADDRESS`
9484      Specifies the load address for the dtb image used by U-Boot. During FIT
9485      image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in
9486      :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
9487      used in creating the dtb sections of Image Tree Source for the FIT image.
9488
9489   :term:`UBOOT_DTBO_LOADADDRESS`
9490      Specifies the load address for the dtbo image used by U-Boot.  During FIT
9491      image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in
9492      :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
9493      used in creating the dtbo sections of Image Tree Source for the FIT image.
9494
9495   :term:`UBOOT_ENTRYPOINT`
9496      Specifies the entry point for the U-Boot image. During U-Boot image
9497      creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a
9498      command-line parameter to the ``uboot-mkimage`` utility.
9499
9500      To pass a 64 bit address for FIT image creation, you will need to set:
9501      -  The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9502      -  The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
9503
9504      This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9505      :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9506      :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9507      classes.
9508
9509   :term:`UBOOT_FIT_ADDRESS_CELLS`
9510      Specifies the value of the ``#address-cells`` value for the
9511      description of the U-Boot FIT image.
9512
9513      The default value is set to "1" by the :ref:`ref-classes-uboot-sign`
9514      class, which corresponds to 32 bit addresses.
9515
9516      For platforms that need to set 64 bit addresses in
9517      :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
9518      set this value to "2", as two 32 bit values (cells) will be needed
9519      to represent such addresses.
9520
9521      Here is an example setting "0x400000000" as a load address::
9522
9523         UBOOT_FIT_ADDRESS_CELLS = "2"
9524         UBOOT_LOADADDRESS= "0x04 0x00000000"
9525
9526      See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
9527
9528   :term:`UBOOT_FIT_DESC`
9529      Specifies the description string encoded into a U-Boot fitImage. The default
9530      value is set by the :ref:`ref-classes-uboot-sign` class as follows::
9531
9532         UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
9533
9534   :term:`UBOOT_FIT_GENERATE_KEYS`
9535      Decides whether to generate the keys for signing the U-Boot fitImage if
9536      they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`.
9537      The default value is "0".
9538
9539      Enable this as follows::
9540
9541         UBOOT_FIT_GENERATE_KEYS = "1"
9542
9543      This variable is used in the :ref:`ref-classes-uboot-sign` class.
9544
9545   :term:`UBOOT_FIT_HASH_ALG`
9546      Specifies the hash algorithm used in creating the U-Boot FIT Image.
9547      It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign`
9548      class.
9549
9550   :term:`UBOOT_FIT_KEY_GENRSA_ARGS`
9551      Arguments to ``openssl genrsa`` for generating a RSA private key for
9552      signing the U-Boot FIT image. The default value of this variable
9553      is set to "-F4" by the :ref:`ref-classes-uboot-sign` class.
9554
9555   :term:`UBOOT_FIT_KEY_REQ_ARGS`
9556      Arguments to ``openssl req`` for generating a certificate for signing
9557      the U-Boot FIT image. The default value is "-batch -new" by the
9558      :ref:`ref-classes-uboot-sign` class, "batch" for
9559      non interactive mode and "new" for generating new keys.
9560
9561   :term:`UBOOT_FIT_KEY_SIGN_PKCS`
9562      Format for the public key certificate used for signing the U-Boot FIT
9563      image. The default value is set to "x509" by the
9564      :ref:`ref-classes-uboot-sign` class.
9565
9566   :term:`UBOOT_FIT_SIGN_ALG`
9567      Specifies the signature algorithm used in creating the U-Boot FIT Image.
9568      This variable is set by default to "rsa2048" by the
9569      :ref:`ref-classes-uboot-sign` class.
9570
9571   :term:`UBOOT_FIT_SIGN_NUMBITS`
9572      Size of the private key used in signing the U-Boot FIT image, in number
9573      of bits. The default value for this variable is set to "2048"
9574      by the :ref:`ref-classes-uboot-sign` class.
9575
9576   :term:`UBOOT_FITIMAGE_ENABLE`
9577      This variable allows to generate a FIT image for U-Boot, which is one
9578      of the ways to implement a verified boot process.
9579
9580      Its default value is "0", so set it to "1" to enable this functionality::
9581
9582         UBOOT_FITIMAGE_ENABLE = "1"
9583
9584      See the :ref:`ref-classes-uboot-sign` class for details.
9585
9586   :term:`UBOOT_LOADADDRESS`
9587      Specifies the load address for the U-Boot image. During U-Boot image
9588      creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a
9589      command-line parameter to the ``uboot-mkimage`` utility.
9590
9591      To pass a 64 bit address, you will also need to set:
9592
9593      -  The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9594      -  The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
9595
9596      This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9597      :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9598      :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9599      classes.
9600
9601   :term:`UBOOT_LOCALVERSION`
9602      Appends a string to the name of the local version of the U-Boot
9603      image. For example, assuming the version of the U-Boot image built
9604      was "2013.10", the full version string reported by U-Boot would be
9605      "2013.10-yocto" given the following statement::
9606
9607         UBOOT_LOCALVERSION = "-yocto"
9608
9609   :term:`UBOOT_MACHINE`
9610      Specifies the value passed on the ``make`` command line when building
9611      a U-Boot image. The value indicates the target platform
9612      configuration. You typically set this variable from the machine
9613      configuration file (i.e. ``conf/machine/machine_name.conf``).
9614
9615      Please see the "Selection of Processor Architecture and Board Type"
9616      section in the U-Boot README for valid values for this variable.
9617
9618   :term:`UBOOT_MAKE_TARGET`
9619      Specifies the target called in the ``Makefile``. The default target
9620      is "all".
9621
9622   :term:`UBOOT_MKIMAGE`
9623      Specifies the name of the mkimage command as used by the
9624      :ref:`ref-classes-kernel-fitimage` class to assemble
9625      the FIT image. This can be used to substitute an alternative command, wrapper
9626      script or function if desired. The default is "uboot-mkimage".
9627
9628   :term:`UBOOT_MKIMAGE_DTCOPTS`
9629      Options for the device tree compiler passed to ``mkimage -D`` feature
9630      while creating a FIT image with the :ref:`ref-classes-kernel-fitimage`
9631      class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the
9632      :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option
9633      to ``mkimage``.
9634
9635      This variable is also used by the :ref:`ref-classes-uboot-sign` class.
9636
9637   :term:`UBOOT_MKIMAGE_KERNEL_TYPE`
9638      Specifies the type argument for the kernel as passed to ``uboot-mkimage``.
9639      The default value is "kernel".
9640
9641   :term:`UBOOT_MKIMAGE_SIGN`
9642      Specifies the name of the mkimage command as used by the
9643      :ref:`ref-classes-kernel-fitimage` class to sign
9644      the FIT image after it has been assembled (if enabled). This can be used
9645      to substitute an alternative command, wrapper script or function if
9646      desired. The default is "${:term:`UBOOT_MKIMAGE`}".
9647
9648   :term:`UBOOT_MKIMAGE_SIGN_ARGS`
9649      Optionally specifies additional arguments for the
9650      :ref:`ref-classes-kernel-fitimage` class to pass to the
9651      mkimage command when signing the FIT image.
9652
9653   :term:`UBOOT_RD_ENTRYPOINT`
9654      Specifies the entrypoint for the RAM disk image. During FIT image
9655      creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in
9656      :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be
9657      used in creating the Image Tree Source for the FIT image.
9658
9659   :term:`UBOOT_RD_LOADADDRESS`
9660      Specifies the load address for the RAM disk image. During FIT image
9661      creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in
9662      :ref:`ref-classes-kernel-fitimage` class to specify the load address to
9663      be used in creating the Image Tree Source for the FIT image.
9664
9665   :term:`UBOOT_SIGN_ENABLE`
9666      Enable signing of FIT image. The default value is "0".
9667
9668      This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9669      :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9670      classes.
9671
9672   :term:`UBOOT_SIGN_KEYDIR`
9673      Location of the directory containing the RSA key and certificate used for
9674      signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and
9675      :ref:`ref-classes-uboot-sign` classes.
9676
9677   :term:`UBOOT_SIGN_KEYNAME`
9678      The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
9679      for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR`
9680      directory. If we have for example a ``dev.key`` key and a ``dev.crt``
9681      certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will
9682      have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``.
9683
9684   :term:`UBOOT_SUFFIX`
9685      Points to the generated U-Boot extension. For example, ``u-boot.sb``
9686      has a ``.sb`` extension.
9687
9688      The default U-Boot extension is ``.bin``
9689
9690   :term:`UBOOT_TARGET`
9691      Specifies the target used for building U-Boot. The target is passed
9692      directly as part of the "make" command (e.g. SPL and AIS). If you do
9693      not specifically set this variable, the OpenEmbedded build process
9694      passes and uses "all" for the target during the U-Boot building
9695      process.
9696
9697   :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
9698      Specifies a list of options that, if reported by the configure script
9699      as being invalid, should not generate a warning during the
9700      :ref:`ref-tasks-configure` task. Normally, invalid
9701      configure options are simply not passed to the configure script (e.g.
9702      should be removed from :term:`EXTRA_OECONF` or
9703      :term:`PACKAGECONFIG_CONFARGS`).
9704      However, there are common options that are passed to all
9705      configure scripts at a class level, but might not be valid for some
9706      configure scripts. Therefore warnings about these options are useless.
9707      For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`.
9708
9709      The configure arguments check that uses
9710      :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the
9711      :ref:`ref-classes-insane` class and is only enabled if the
9712      recipe inherits the :ref:`ref-classes-autotools` class.
9713
9714   :term:`UNPACKDIR`
9715      This variable, used by the :ref:`ref-classes-base` class,
9716      specifies where fetches sources should be unpacked by the
9717      :ref:`ref-tasks-unpack` task.
9718
9719   :term:`UPDATERCPN`
9720      For recipes inheriting the
9721      :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN`
9722      specifies the package that contains the initscript that is enabled.
9723
9724      The default value is "${PN}". Given that almost all recipes that
9725      install initscripts package them in the main package for the recipe,
9726      you rarely need to set this variable in individual recipes.
9727
9728   :term:`UPSTREAM_CHECK_COMMITS`
9729      You can perform a per-recipe check for what the latest upstream
9730      source code version is by calling ``devtool latest-version recipe``. If
9731      the recipe source code is provided from Git repositories, but
9732      releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS`
9733      to ``1`` in the recipe, and the OpenEmbedded build system
9734      will compare the latest commit with the one currently specified
9735      by the recipe (:term:`SRCREV`)::
9736
9737         UPSTREAM_CHECK_COMMITS = "1"
9738
9739   :term:`UPSTREAM_CHECK_GITTAGREGEX`
9740      You can perform a per-recipe check for what the latest upstream
9741      source code version is by calling ``devtool latest-version recipe``. If
9742      the recipe source code is provided from Git repositories, the
9743      OpenEmbedded build system determines the latest upstream version by
9744      picking the latest tag from the list of all repository tags.
9745
9746      You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
9747      regular expression to filter only the relevant tags should the
9748      default filter not work correctly::
9749
9750         UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
9751
9752   :term:`UPSTREAM_CHECK_REGEX`
9753      Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
9754      regular expression instead of the default one when the package
9755      checking system is parsing the page found using
9756      :term:`UPSTREAM_CHECK_URI`::
9757
9758         UPSTREAM_CHECK_REGEX = "package_regex"
9759
9760   :term:`UPSTREAM_CHECK_URI`
9761      You can perform a per-recipe check for what the latest upstream
9762      source code version is by calling ``devtool latest-version recipe``. If
9763      the source code is provided from tarballs, the latest version is
9764      determined by fetching the directory listing where the tarball is and
9765      attempting to find a later tarball. When this approach does not work,
9766      you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
9767      contains the link to the latest tarball::
9768
9769         UPSTREAM_CHECK_URI = "recipe_url"
9770
9771   :term:`UPSTREAM_VERSION_UNKNOWN`
9772      You can perform a per-recipe check for what the latest upstream
9773      source code version is by calling ``devtool latest-version recipe``.
9774      If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`,
9775      :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
9776      the recipe allows to determine what the latest upstream version is,
9777      you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe
9778      to acknowledge that the check cannot be performed::
9779
9780         UPSTREAM_VERSION_UNKNOWN = "1"
9781
9782   :term:`USE_DEVFS`
9783      Determines if ``devtmpfs`` is used for ``/dev`` population. The
9784      default value used for :term:`USE_DEVFS` is "1" when no value is
9785      specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a
9786      statically populated ``/dev`` directory.
9787
9788      See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in
9789      the Yocto Project Development Tasks Manual for information on how to
9790      use this variable.
9791
9792   :term:`USE_VT`
9793      When using
9794      :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
9795      determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>`
9796      on any virtual terminals in order to enable logging in through those
9797      terminals.
9798
9799      The default value used for :term:`USE_VT` is "1" when no default value is
9800      specifically set. Typically, you would set :term:`USE_VT` to "0" in the
9801      machine configuration file for machines that do not have a graphical
9802      display attached and therefore do not need virtual terminal
9803      functionality.
9804
9805   :term:`USER_CLASSES`
9806      A list of classes to globally inherit. These classes are used by the
9807      OpenEmbedded build system to enable extra features.
9808
9809      Classes inherited using :term:`USER_CLASSES` must be located in the
9810      ``classes-global/`` or ``classes/`` subdirectories.
9811
9812      The default list is set in your ``local.conf`` file::
9813
9814         USER_CLASSES ?= "buildstats"
9815
9816      For more information, see
9817      ``meta-poky/conf/templates/default/local.conf.sample`` in the
9818      :term:`Source Directory`.
9819
9820   :term:`USERADD_DEPENDS`
9821      Specifies a list of recipes that create users / groups (via
9822      :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe
9823      depends upon. This ensures that those users / groups are available
9824      when building a recipe.
9825
9826   :term:`USERADD_ERROR_DYNAMIC`
9827      If set to ``error``, forces the OpenEmbedded build system to produce
9828      an error if the user identification (``uid``) and group
9829      identification (``gid``) values are not defined in any of the files
9830      listed in :term:`USERADD_UID_TABLES` and
9831      :term:`USERADD_GID_TABLES`. If set to
9832      ``warn``, a warning will be issued instead.
9833
9834      The default behavior for the build system is to dynamically apply
9835      ``uid`` and ``gid`` values. Consequently, the
9836      :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
9837      on using statically assigned ``gid`` and ``uid`` values, you should
9838      set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
9839      file as follows::
9840
9841         USERADD_ERROR_DYNAMIC = "error"
9842
9843      Overriding the
9844      default behavior implies you are going to also take steps to set
9845      static ``uid`` and ``gid`` values through use of the
9846      :term:`USERADDEXTENSION`,
9847      :term:`USERADD_UID_TABLES`, and
9848      :term:`USERADD_GID_TABLES` variables.
9849
9850      .. note::
9851
9852         There is a difference in behavior between setting
9853         :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``.
9854         When it is set to ``warn``, the build system will report a warning for
9855         every undefined ``uid`` and ``gid`` in any recipe. But when it is set
9856         to ``error``, it will only report errors for recipes that are actually
9857         built.
9858         This saves you from having to add static IDs for recipes that you
9859         know will never be built.
9860
9861   :term:`USERADD_GID_TABLES`
9862      Specifies a password file to use for obtaining static group
9863      identification (``gid``) values when the OpenEmbedded build system
9864      adds a group to the system during package installation.
9865
9866      When applying static group identification (``gid``) values, the
9867      OpenEmbedded build system looks in :term:`BBPATH` for a
9868      ``files/group`` file and then applies those ``uid`` values. Set the
9869      variable as follows in your ``local.conf`` file::
9870
9871
9872         USERADD_GID_TABLES = "files/group"
9873
9874      .. note::
9875
9876         Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
9877         causes the build system to use static ``gid`` values.
9878
9879   :term:`USERADD_PACKAGES`
9880      When inheriting the :ref:`ref-classes-useradd` class,
9881      this variable specifies the individual packages within the recipe
9882      that require users and/or groups to be added.
9883
9884      You must set this variable if the recipe inherits the class. For
9885      example, the following enables adding a user for the main package in
9886      a recipe::
9887
9888         USERADD_PACKAGES = "${PN}"
9889
9890      .. note::
9891
9892         It follows that if you are going to use the :term:`USERADD_PACKAGES`
9893         variable, you need to set one or more of the :term:`USERADD_PARAM`,
9894         :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables.
9895
9896   :term:`USERADD_PARAM`
9897      When inheriting the :ref:`ref-classes-useradd` class,
9898      this variable specifies for a package what parameters should pass to
9899      the ``useradd`` command if you add a user to the system when the
9900      package is installed.
9901
9902      Here is an example from the ``dbus`` recipe::
9903
9904         USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
9905                                --no-create-home --shell /bin/false \
9906                                --user-group messagebus"
9907
9908      For information on the
9909      standard Linux shell command ``useradd``, see
9910      https://linux.die.net/man/8/useradd.
9911
9912   :term:`USERADD_UID_TABLES`
9913      Specifies a password file to use for obtaining static user
9914      identification (``uid``) values when the OpenEmbedded build system
9915      adds a user to the system during package installation.
9916
9917      When applying static user identification (``uid``) values, the
9918      OpenEmbedded build system looks in :term:`BBPATH` for a
9919      ``files/passwd`` file and then applies those ``uid`` values. Set the
9920      variable as follows in your ``local.conf`` file::
9921
9922         USERADD_UID_TABLES = "files/passwd"
9923
9924      .. note::
9925
9926         Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
9927         causes the build system to use static ``uid`` values.
9928
9929   :term:`USERADDEXTENSION`
9930      When set to "useradd-staticids", causes the OpenEmbedded build system
9931      to base all user and group additions on a static ``passwd`` and
9932      ``group`` files found in :term:`BBPATH`.
9933
9934      To use static user identification (``uid``) and group identification
9935      (``gid``) values, set the variable as follows in your ``local.conf``
9936      file: USERADDEXTENSION = "useradd-staticids"
9937
9938      .. note::
9939
9940         Setting this variable to use static ``uid`` and ``gid``
9941         values causes the OpenEmbedded build system to employ the
9942         :ref:`ref-classes-useradd` class.
9943
9944      If you use static ``uid`` and ``gid`` information, you must also
9945      specify the ``files/passwd`` and ``files/group`` files by setting the
9946      :term:`USERADD_UID_TABLES` and
9947      :term:`USERADD_GID_TABLES` variables.
9948      Additionally, you should also set the
9949      :term:`USERADD_ERROR_DYNAMIC` variable.
9950
9951   :term:`VIRTUAL-RUNTIME`
9952      :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual
9953      packages for runtime usage, typically for use in :term:`RDEPENDS`
9954      or in image definitions.
9955
9956      An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible
9957      to either use BusyBox based utilities::
9958
9959         VIRTUAL-RUNTIME_base-utils = "busybox"
9960
9961      or their full featured implementations from GNU Coreutils
9962      and other projects::
9963
9964         VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"
9965
9966      Here are two examples using this virtual runtime package. The
9967      first one is in :yocto_git:`initramfs-framework_1.0.bb
9968      </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`::
9969
9970         RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"
9971
9972      The second example is in the :yocto_git:`core-image-initramfs-boot
9973      </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>`
9974      image definition::
9975
9976         PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
9977
9978   :term:`VOLATILE_LOG_DIR`
9979      Specifies the persistence of the target's ``/var/log`` directory,
9980      which is used to house postinstall target log files.
9981
9982      By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the
9983      file is not persistent. You can override this setting by setting the
9984      variable to "no" to make the log directory persistent.
9985
9986   :term:`VOLATILE_TMP_DIR`
9987      Specifies the persistence of the target's ``/tmp`` directory.
9988
9989      By default, :term:`VOLATILE_TMP_DIR` is set to "yes", in which case
9990      ``/tmp`` links to a directory which resides in RAM in a ``tmpfs``
9991      filesystem.
9992
9993      If instead, you want the ``/tmp`` directory to be persistent, set the
9994      variable to "no" to make it a regular directory in the root filesystem.
9995
9996      This supports both sysvinit and systemd based systems.
9997
9998   :term:`WARN_QA`
9999      Specifies the quality assurance checks whose failures are reported as
10000      warnings by the OpenEmbedded build system. You set this variable in
10001      your distribution configuration file. For a list of the checks you
10002      can control with this variable, see the
10003      ":ref:`ref-classes-insane`" section.
10004
10005   :term:`WATCHDOG_TIMEOUT`
10006      Specifies the timeout in seconds used by the ``watchdog`` recipe and
10007      also by ``systemd`` during reboot. The default is 60 seconds.
10008
10009   :term:`WIRELESS_DAEMON`
10010      For ``connman`` and ``packagegroup-base``, specifies the wireless
10011      daemon to use. The default is "wpa-supplicant" (note that the value
10012      uses a dash and not an underscore).
10013
10014   :term:`WKS_FILE`
10015      Specifies the location of the Wic kickstart file that is used by the
10016      OpenEmbedded build system to create a partitioned image
10017      (``image.wic``). For information on how to create a partitioned
10018      image, see the
10019      ":ref:`dev-manual/wic:creating partitioned images using wic`"
10020      section in the Yocto Project Development Tasks Manual. For details on
10021      the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter.
10022
10023   :term:`WKS_FILE_DEPENDS`
10024      When placed in the recipe that builds your image, this variable lists
10025      build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only
10026      applicable when Wic images are active (i.e. when
10027      :term:`IMAGE_FSTYPES` contains entries related
10028      to Wic). If your recipe does not create Wic images, the variable has
10029      no effect.
10030
10031      The :term:`WKS_FILE_DEPENDS` variable is similar to the
10032      :term:`DEPENDS` variable. When you use the variable in
10033      your recipe that builds the Wic image, dependencies you list in the
10034      :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable.
10035
10036      With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
10037      specify a list of additional dependencies (e.g. native tools,
10038      bootloaders, and so forth), that are required to build Wic images.
10039      Here is an example::
10040
10041         WKS_FILE_DEPENDS = "some-native-tool"
10042
10043      In the
10044      previous example, some-native-tool would be replaced with an actual
10045      native tool on which the build would depend.
10046
10047   :term:`WKS_FILES`
10048      Specifies a list of candidate Wic kickstart files to be used by the
10049      OpenEmbedded build system to create a partitioned image. Only the
10050      first one that is found, from left to right, will be used.
10051
10052      This is only useful when there are multiple ``.wks`` files that can be
10053      used to produce an image. A typical case is when multiple layers are
10054      used for different hardware platforms, each supplying a different
10055      ``.wks`` file. In this case, you specify all possible ones through
10056      :term:`WKS_FILES`.
10057
10058      If only one ``.wks`` file is used, set :term:`WKS_FILE` instead.
10059
10060   :term:`WORKDIR`
10061      The pathname of the work directory in which the OpenEmbedded build
10062      system builds a recipe. This directory is located within the
10063      :term:`TMPDIR` directory structure and is specific to
10064      the recipe being built and the system for which it is being built.
10065
10066      The :term:`WORKDIR` directory is defined as follows::
10067
10068         ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
10069
10070      The actual directory depends on several things:
10071
10072      -  :term:`TMPDIR`: The top-level build output directory
10073      -  :term:`MULTIMACH_TARGET_SYS`: The target system identifier
10074      -  :term:`PN`: The recipe name
10075      -  :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which
10076         is usually the case for most recipes, then :term:`EXTENDPE` is blank.
10077      -  :term:`PV`: The recipe version
10078      -  :term:`PR`: The recipe revision
10079
10080      As an example, assume a Source Directory top-level folder name
10081      ``poky``, a default :term:`Build Directory` at ``poky/build``, and a
10082      ``qemux86-poky-linux`` machine target system. Furthermore, suppose
10083      your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
10084      directory the build system uses to build the package would be as
10085      follows::
10086
10087         poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
10088
10089   :term:`XSERVER`
10090      Specifies the packages that should be installed to provide an X
10091      server and drivers for the current machine, assuming your image
10092      directly includes ``packagegroup-core-x11-xserver`` or, perhaps
10093      indirectly, includes "x11-base" in
10094      :term:`IMAGE_FEATURES`.
10095
10096      The default value of :term:`XSERVER`, if not specified in the machine
10097      configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
10098
10099   :term:`XZ_THREADS`
10100      Specifies the number of parallel threads that should be used when
10101      using xz compression.
10102
10103      By default this scales with core count, but is never set less than 2
10104      to ensure that multi-threaded mode is always used so that the output
10105      file contents are deterministic. Builds will work with a value of 1
10106      but the output will differ compared to the output from the compression
10107      generated when more than one thread is used.
10108
10109      On systems where many tasks run in parallel, setting a limit to this
10110      can be helpful in controlling system resource usage.
10111
10112   :term:`XZ_MEMLIMIT`
10113      Specifies the maximum memory the xz compression should use as a percentage
10114      of system memory. If unconstrained the xz compressor can use large amounts of
10115      memory and become problematic with parallelism elsewhere in the build.
10116      "50%" has been found to be a good value.
10117
10118   :term:`ZSTD_THREADS`
10119      Specifies the number of parallel threads that should be used when
10120      using ZStandard compression.
10121
10122      By default this scales with core count, but is never set less than 2
10123      to ensure that multi-threaded mode is always used so that the output
10124      file contents are deterministic. Builds will work with a value of 1
10125      but the output will differ compared to the output from the compression
10126      generated when more than one thread is used.
10127
10128      On systems where many tasks run in parallel, setting a limit to this
10129      can be helpful in controlling system resource usage.
10130