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