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