blob: adbef69d8f39d33be87c5db6688a807156540410 [file] [log] [blame]
Andrew Geisslerf0343792020-11-18 10:42:21 -06001.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002
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
Andrew Geisslerf0343792020-11-18 10:42:21 -060010:term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>`
Patrick Williams84603582024-12-14 08:00:57 -050011:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FAKEROOT>`
12:term:`G <GCCPIE>` :term:`H <HGDIR>` :term:`I <ICECC_CLASS_DISABLE>`
Andrew Geisslerf0343792020-11-18 10:42:21 -060013:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
Patrick Williams84603582024-12-14 08:00:57 -050015:term:`Q <QA_EMPTY_DIRS>` :term:`R <RANLIB>` :term:`S` :term:`T`
16:term:`U <UBOOT_BINARY>` :term:`V <VIRTUAL-RUNTIME>`
17:term:`W <WARN_QA>` :term:`X <XSERVER>` :term:`Z <ZSTD_THREADS>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050018
19.. glossary::
Andrew Geissler9aee5002022-03-30 16:27:02 +000020 :sorted:
Andrew Geisslerc9f78652020-09-18 14:11:35 -050021
Andrew Geisslerf0343792020-11-18 10:42:21 -060022 :term:`ABIEXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050023 Extension to the Application Binary Interface (ABI) field of the GNU
24 canonical architecture name (e.g. "eabi").
25
26 ABI extensions are set in the machine include files. For example, the
27 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
Andrew Geisslerc926e172021-05-07 16:11:35 -050028 following extension::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050029
30 ABIEXTENSION = "eabi"
31
Andrew Geisslerf0343792020-11-18 10:42:21 -060032 :term:`ALLOW_EMPTY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050033 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
Andrew Geisslerc926e172021-05-07 16:11:35 -050040 conjunction with a package name override, as in::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050041
Patrick Williams0ca19cc2021-08-16 14:03:13 -050042 ALLOW_EMPTY:${PN} = "1"
43 ALLOW_EMPTY:${PN}-dev = "1"
44 ALLOW_EMPTY:${PN}-staticdev = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050045
Andrew Geisslerf0343792020-11-18 10:42:21 -060046 :term:`ALTERNATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047 Lists commands in a package that need an alternative binary naming
48 scheme. Sometimes the same command is provided in multiple packages.
49 When this occurs, the OpenEmbedded build system needs to use the
50 alternatives system to create a different binary naming scheme so the
51 commands can co-exist.
52
William A. Kennington IIIac69b482021-06-02 12:28:27 -070053 To use the variable, list out the package's commands that are also
54 provided by another package. For example, if the ``busybox`` package
55 has four such commands, you identify them as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050056
Patrick Williams0ca19cc2021-08-16 14:03:13 -050057 ALTERNATIVE:busybox = "sh sed test bracket"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050058
59 For more information on the alternatives system, see the
Andrew Geissler595f6302022-01-24 19:11:47 +000060 ":ref:`ref-classes-update-alternatives`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050061 section.
62
Andrew Geisslerf0343792020-11-18 10:42:21 -060063 :term:`ALTERNATIVE_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050064 Used by the alternatives system to map duplicated commands to actual
65 locations. For example, if the ``bracket`` command provided by the
66 ``busybox`` package is duplicated through another package, you must
Andrew Geissler09036742021-06-25 14:25:14 -050067 use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
Andrew Geisslerc926e172021-05-07 16:11:35 -050068 location::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050069
70 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
71
72 In this example, the binary for the ``bracket`` command (i.e. ``[``)
73 from the ``busybox`` package resides in ``/usr/bin/``.
74
75 .. note::
76
Andrew Geissler09036742021-06-25 14:25:14 -050077 If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050078
79 For more information on the alternatives system, see the
Andrew Geissler595f6302022-01-24 19:11:47 +000080 ":ref:`ref-classes-update-alternatives`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050081 section.
82
Andrew Geisslerf0343792020-11-18 10:42:21 -060083 :term:`ALTERNATIVE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050084 Used by the alternatives system to create default priorities for
85 duplicated commands. You can use the variable to create a single
86 default regardless of the command name or package, a default for
87 specific duplicated commands regardless of the package, or a default
88 for specific commands tied to particular packages. Here are the
Andrew Geisslerc926e172021-05-07 16:11:35 -050089 available syntax forms::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050090
91 ALTERNATIVE_PRIORITY = "priority"
92 ALTERNATIVE_PRIORITY[name] = "priority"
93 ALTERNATIVE_PRIORITY_pkg[name] = "priority"
94
95 For more information on the alternatives system, see the
Andrew Geissler595f6302022-01-24 19:11:47 +000096 ":ref:`ref-classes-update-alternatives`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050097 section.
98
Andrew Geisslerf0343792020-11-18 10:42:21 -060099 :term:`ALTERNATIVE_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500100 Used by the alternatives system to create default link locations for
101 duplicated commands. You can use the variable to create a single
102 default location for all duplicated commands regardless of the
103 command name or package, a default for specific duplicated commands
104 regardless of the package, or a default for specific commands tied to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500105 particular packages. Here are the available syntax forms::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500106
107 ALTERNATIVE_TARGET = "target"
108 ALTERNATIVE_TARGET[name] = "target"
109 ALTERNATIVE_TARGET_pkg[name] = "target"
110
111 .. note::
112
Andrew Geissler09036742021-06-25 14:25:14 -0500113 If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500114 from the :term:`ALTERNATIVE_LINK_NAME` variable.
115
Andrew Geissler09036742021-06-25 14:25:14 -0500116 If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the
117 same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500118 appended to it.
119
120 Finally, if the file referenced has not been renamed, the
121 alternatives system will rename it to avoid the need to rename
122 alternative files in the :ref:`ref-tasks-install`
123 task while retaining support for the command if necessary.
124
125 For more information on the alternatives system, see the
Andrew Geissler595f6302022-01-24 19:11:47 +0000126 ":ref:`ref-classes-update-alternatives`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500127
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600128 :term:`ANY_OF_DISTRO_FEATURES`
Andrew Geissler517393d2023-01-13 08:55:19 -0600129 When inheriting the :ref:`ref-classes-features_check`
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600130 class, this variable identifies a list of distribution features where
131 at least one must be enabled in the current configuration in order
132 for the OpenEmbedded build system to build the recipe. In other words,
Andrew Geissler09036742021-06-25 14:25:14 -0500133 if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES`
134 appear in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600135 the recipe will be skipped, and if the build system attempts to build
136 the recipe then an error will be triggered.
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600137
Andrew Geisslerf0343792020-11-18 10:42:21 -0600138 :term:`APPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500139 An override list of append strings for each target specified with
140 :term:`LABELS`.
141
Andrew Geissler517393d2023-01-13 08:55:19 -0600142 See the :ref:`ref-classes-grub-efi` class for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500143 information on how this variable is used.
144
Andrew Geisslerf0343792020-11-18 10:42:21 -0600145 :term:`AR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500146 The minimal command and arguments used to run ``ar``.
147
Andrew Geisslerf0343792020-11-18 10:42:21 -0600148 :term:`ARCHIVER_MODE`
Andrew Geissler517393d2023-01-13 08:55:19 -0600149 When used with the :ref:`ref-classes-archiver` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500150 determines the type of information used to create a released archive.
151 You can use this variable to create archives of patched source,
152 original source, configured source, and so forth by employing the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500153 following variable flags (varflags)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500154
155 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
156 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
157 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
158 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
159 ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
160 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
161 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
162 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
163
164 For information on how the variable works, see the
165 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
166
Andrew Geisslerf0343792020-11-18 10:42:21 -0600167 :term:`AS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500168 Minimal command and arguments needed to run the assembler.
169
Andrew Geisslerf0343792020-11-18 10:42:21 -0600170 :term:`ASSUME_PROVIDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500171 Lists recipe names (:term:`PN` values) BitBake does not
172 attempt to build. Instead, BitBake assumes these recipes have already
173 been built.
174
Andrew Geissler09036742021-06-25 14:25:14 -0500175 In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500176 tools that should not be built. An example is ``git-native``, which
177 when specified, allows for the Git binary from the host to be used
178 rather than building ``git-native``.
179
Andrew Geisslerf0343792020-11-18 10:42:21 -0600180 :term:`ASSUME_SHLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500181 Provides additional ``shlibs`` provider mapping information, which
182 adds to or overwrites the information provided automatically by the
183 system. Separate multiple entries using spaces.
184
185 As an example, use the following form to add an ``shlib`` provider of
Andrew Geisslerc926e172021-05-07 16:11:35 -0500186 shlibname in packagename with the optional version::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500187
188 shlibname:packagename[_version]
189
190 Here is an example that adds a shared library named ``libEGL.so.1``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500191 as being provided by the ``libegl-implementation`` package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500192
193 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
194
Andrew Geisslerf0343792020-11-18 10:42:21 -0600195 :term:`AUTO_LIBNAME_PKGS`
Andrew Geissler517393d2023-01-13 08:55:19 -0600196 When the :ref:`ref-classes-debian` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -0500197 which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198 packages should be checked for libraries and renamed according to
199 Debian library package naming.
200
Andrew Geissler517393d2023-01-13 08:55:19 -0600201 The default value is "${PACKAGES}", which causes the
202 :ref:`ref-classes-debian` class to act on all packages that are
203 explicitly generated by the recipe.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500204
Andrew Geisslerf0343792020-11-18 10:42:21 -0600205 :term:`AUTOREV`
Andrew Geissler09036742021-06-25 14:25:14 -0500206 When :term:`SRCREV` is set to the value of this variable, it specifies to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500207 use the latest source revision in the repository. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500208
209 SRCREV = "${AUTOREV}"
210
211 If you use the previous statement to retrieve the latest version of
Patrick Williams96e4b4e2025-02-03 15:49:15 -0500212 software, you need to make sure :term:`PV` contains the ``+`` sign so
213 :term:`bitbake` includes source control information to :term:`PKGV` when
214 packaging the recipe. For example::
215
216 PV = "6.10.y+git"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500217
218 For more information see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600219 ":ref:`dev-manual/packages:automatically incrementing a package version number`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500220 section in the Yocto Project Development Tasks Manual.
221
Andrew Geissler9aee5002022-03-30 16:27:02 +0000222 :term:`AUTO_SYSLINUXMENU`
223 Enables creating an automatic menu for the syslinux bootloader. You
224 must set this variable in your recipe. The
Andrew Geissler517393d2023-01-13 08:55:19 -0600225 :ref:`ref-classes-syslinux` class checks this variable.
Andrew Geissler9aee5002022-03-30 16:27:02 +0000226
Andrew Geisslerf0343792020-11-18 10:42:21 -0600227 :term:`AVAILTUNES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228 The list of defined CPU and Application Binary Interface (ABI)
229 tunings (i.e. "tunes") available for use by the OpenEmbedded build
230 system.
231
232 The list simply presents the tunes that are available. Not all tunes
233 may be compatible with a particular machine configuration, or with
234 each other in a
Andrew Geissler517393d2023-01-13 08:55:19 -0600235 :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500236 configuration.
237
238 To add a tune to the list, be sure to append it with spaces using the
239 "+=" BitBake operator. Do not simply replace the list by using the
240 "=" operator. See the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500241 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500242 User Manual for more information.
243
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500244 :term:`AZ_SAS`
245 Azure Storage Shared Access Signature, when using the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -0500246 :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500247 This variable can be defined to be used by the fetcher to authenticate
Andrew Geissler517393d2023-01-13 08:55:19 -0600248 and gain access to non-public artifacts::
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500249
250 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
251
252 For more information see Microsoft's Azure Storage documentation at
253 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
254
Andrew Geisslerf0343792020-11-18 10:42:21 -0600255 :term:`B`
Patrick Williams2390b1b2022-11-03 13:47:49 -0500256 The directory within the :term:`Build Directory` in which the
257 OpenEmbedded build system places generated objects during a recipe's
258 build process. By default, this directory is the same as the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500259 :term:`S` directory, which is defined as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260
261 S = "${WORKDIR}/${BP}"
262
Andrew Geissler09036742021-06-25 14:25:14 -0500263 You can separate the (:term:`S`) directory and the directory pointed to
Andrew Geissler5f350902021-07-23 13:09:54 -0400264 by the :term:`B` variable. Most Autotools-based recipes support
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500265 separating these directories. The build system defaults to using
266 separate directories for ``gcc`` and some kernel recipes.
267
Andrew Geisslerf0343792020-11-18 10:42:21 -0600268 :term:`BAD_RECOMMENDATIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500269 Lists "recommended-only" packages to not install. Recommended-only
270 packages are packages installed only through the
271 :term:`RRECOMMENDS` variable. You can prevent any
272 of these "recommended" packages from being installed by listing them
Andrew Geissler09036742021-06-25 14:25:14 -0500273 with the :term:`BAD_RECOMMENDATIONS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500274
275 BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
276
277 You can set this variable globally in your ``local.conf`` file or you
278 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -0500279 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500280
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500281 BAD_RECOMMENDATIONS:pn-target_image = "package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500282
283 It is important to realize that if you choose to not install packages
284 using this variable and some other packages are dependent on them
285 (i.e. listed in a recipe's :term:`RDEPENDS`
286 variable), the OpenEmbedded build system ignores your request and
287 will install the packages to avoid dependency errors.
288
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700289 This variable is supported only when using the IPK and RPM
290 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500291
292 See the :term:`NO_RECOMMENDATIONS` and the
293 :term:`PACKAGE_EXCLUDE` variables for related
294 information.
295
Patrick Williams96e4b4e2025-02-03 15:49:15 -0500296 :term:`BAREBOX_BINARY`
297 When using the :ref:`ref-classes-barebox` class, this variable allows you
298 to specify a particular binary that should be deployed and installed.
299
300 The barebox build system can build multiple barebox binaries at once.
301 By default, all built binaries will be deployed and installed under their
302 original name.
303
304 Here is an example usage of this variable::
305
306 BAREBOX_BINARY = "barebox-boundarydevices-imx6dl-nitrogen6x-1g.img"
307
308 :term:`BAREBOX_CONFIG`
309 When using the :ref:`ref-classes-barebox` class, this variable allows you
310 to specify the name of the barebox defconfig to build.
311 The name must be a defconfig file known to the barebox build environment.
312 This variable is mainly useful for generic use cases where a dedicated
313 configuration is not required.
314 The :ref:`ref-classes-barebox` class itself already sets it for some QEMU
315 machines::
316
317 BAREBOX_CONFIG:qemuarm = "multi_v7_defconfig"
318 BAREBOX_CONFIG:qemuarm64 = "multi_v8_defconfig"
319 BAREBOX_CONFIG:qemux86-64 = "efi_defconfig"
320
321 Except for these, the default value of :term:`BAREBOX_CONFIG` is empty.
322 For more information on how to provide a barebox configuration, see the
323 :ref:`ref-classes-barebox` class.
324
Andrew Geisslerf0343792020-11-18 10:42:21 -0600325 :term:`BASE_LIB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500326 The library directory name for the CPU or Application Binary
Andrew Geissler09036742021-06-25 14:25:14 -0500327 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib
Andrew Geissler517393d2023-01-13 08:55:19 -0600328 context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500329 section in the Yocto Project Development Tasks Manual for information
330 on Multilib.
331
Andrew Geissler09036742021-06-25 14:25:14 -0500332 The :term:`BASE_LIB` variable is defined in the machine include files in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500333 the :term:`Source Directory`. If Multilib is not
334 being used, the value defaults to "lib".
335
Andrew Geisslerf0343792020-11-18 10:42:21 -0600336 :term:`BASE_WORKDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500337 Points to the base of the work directory for all recipes. The default
338 value is "${TMPDIR}/work".
339
Andrew Geisslerf0343792020-11-18 10:42:21 -0600340 :term:`BB_ALLOWED_NETWORKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500341 Specifies a space-delimited list of hosts that the fetcher is allowed
Patrick Williams39653562024-03-01 08:54:02 -0600342 to use to obtain the required source code. Here are
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500343 considerations surrounding this variable:
344
Andrew Geissler09036742021-06-25 14:25:14 -0500345 - This host list is only used if :term:`BB_NO_NETWORK` is either not set
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500346 or set to "0".
347
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700348 - There is limited support for wildcard matching against the beginning of
349 host names. For example, the following setting matches
Andrew Geissler517393d2023-01-13 08:55:19 -0600350 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500351
352 BB_ALLOWED_NETWORKS = "*.gnu.org"
353
354 .. note::
355
356 The use of the "``*``" character only works at the beginning of
357 a host name and it must be isolated from the remainder of the
358 host name. You cannot use the wildcard character in any other
359 location of the name or combined with the front part of the
360 name.
361
362 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
363 is not.
364
365 - Mirrors not in the host list are skipped and logged in debug.
366
367 - Attempts to access networks not in the host list cause a failure.
368
Andrew Geissler09036742021-06-25 14:25:14 -0500369 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370 :term:`PREMIRRORS` is very useful. Adding the host
Andrew Geissler09036742021-06-25 14:25:14 -0500371 you want to use to :term:`PREMIRRORS` results in the source code being
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500372 fetched from an allowed location and avoids raising an error when a
373 host that is not allowed is in a :term:`SRC_URI`
374 statement. This is because the fetcher does not attempt to use the
Andrew Geissler09036742021-06-25 14:25:14 -0500375 host listed in :term:`SRC_URI` after a successful fetch from the
376 :term:`PREMIRRORS` occurs.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500377
Andrew Geissler517393d2023-01-13 08:55:19 -0600378 :term:`BB_BASEHASH_IGNORE_VARS`
379 See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual.
380
Patrick Williams8e7b46e2023-05-01 14:19:06 -0500381 :term:`BB_CACHEDIR`
382 See :term:`bitbake:BB_CACHEDIR` in the BitBake manual.
383
Andrew Geissler517393d2023-01-13 08:55:19 -0600384 :term:`BB_CHECK_SSL_CERTS`
385 See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual.
386
387 :term:`BB_CONSOLELOG`
388 See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual.
389
390 :term:`BB_CURRENTTASK`
391 See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual.
392
Andrew Geissler517393d2023-01-13 08:55:19 -0600393 :term:`BB_DEFAULT_TASK`
394 See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual.
395
396 :term:`BB_DEFAULT_UMASK`
397 See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual.
398
Andrew Geisslerf0343792020-11-18 10:42:21 -0600399 :term:`BB_DISKMON_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500400 Monitors disk space and available inodes during the build and allows
401 you to control the build based on these parameters.
402
403 Disk space monitoring is disabled by default. To enable monitoring,
Andrew Geissler09036742021-06-25 14:25:14 -0500404 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500405 found in the :term:`Build Directory`. Use the
406 following form:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500407
408 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500409
410 BB_DISKMON_DIRS = "action,dir,threshold [...]"
411
412 where:
413
414 action is:
Andrew Geissler595f6302022-01-24 19:11:47 +0000415 ABORT: Immediately stop the build when
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500416 a threshold is broken.
417 STOPTASKS: Stop the build after the currently
418 executing tasks have finished when
419 a threshold is broken.
420 WARN: Issue a warning but continue the
421 build when a threshold is broken.
422 Subsequent warnings are issued as
423 defined by the BB_DISKMON_WARNINTERVAL
424 variable, which must be defined in
425 the conf/local.conf file.
426
427 dir is:
428 Any directory you choose. You can specify one or
429 more directories to monitor by separating the
430 groupings with a space. If two directories are
431 on the same device, only the first directory
432 is monitored.
433
434 threshold is:
435 Either the minimum available disk space,
436 the minimum number of free inodes, or
437 both. You must specify at least one. To
438 omit one or the other, simply omit the value.
439 Specify the threshold using G, M, K for Gbytes,
440 Mbytes, and Kbytes, respectively. If you do
441 not specify G, M, or K, Kbytes is assumed by
442 default. Do not use GB, MB, or KB.
443
Andrew Geisslerc926e172021-05-07 16:11:35 -0500444 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500445
446 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
447 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
448 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
449
450 The first example works only if you also provide the
451 :term:`BB_DISKMON_WARNINTERVAL`
452 variable in the ``conf/local.conf``. This example causes the build
Andrew Geissler595f6302022-01-24 19:11:47 +0000453 system to immediately stop when either the disk space in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500454 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
455 below 100 Kbytes. Because two directories are provided with the
456 variable, the build system also issue a warning when the disk space
457 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
458 of free inodes drops below 100 Kbytes. Subsequent warnings are issued
Andrew Geissler09036742021-06-25 14:25:14 -0500459 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460 variable.
461
462 The second example stops the build after all currently executing
463 tasks complete when the minimum disk space in the ``${TMPDIR}``
464 directory drops below 1 Gbyte. No disk monitoring occurs for the free
465 inodes in this case.
466
Andrew Geissler595f6302022-01-24 19:11:47 +0000467 The final example immediately stops the build when the number of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500468 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
469 disk space monitoring for the directory itself occurs in this case.
470
Andrew Geisslerf0343792020-11-18 10:42:21 -0600471 :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500472 Defines the disk space and free inode warning intervals. To set these
473 intervals, define the variable in your ``conf/local.conf`` file in
474 the :term:`Build Directory`.
475
Andrew Geissler09036742021-06-25 14:25:14 -0500476 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500477 must also use the :term:`BB_DISKMON_DIRS`
478 variable and define its action as "WARN". During the build,
479 subsequent warnings are issued each time disk space or number of free
480 inodes further reduces by the respective interval.
481
Andrew Geissler09036742021-06-25 14:25:14 -0500482 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
483 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
Andrew Geisslerc926e172021-05-07 16:11:35 -0500484 monitoring interval defaults to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500485
486 BB_DISKMON_WARNINTERVAL = "50M,5K"
487
488 When specifying the variable in your configuration file, use the
489 following form:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500490
491 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500492
493 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"
494
495 where:
496
497 disk_space_interval is:
498 An interval of memory expressed in either
499 G, M, or K for Gbytes, Mbytes, or Kbytes,
500 respectively. You cannot use GB, MB, or KB.
501
502 disk_inode_interval is:
503 An interval of free inodes expressed in either
504 G, M, or K for Gbytes, Mbytes, or Kbytes,
505 respectively. You cannot use GB, MB, or KB.
506
Andrew Geisslerc926e172021-05-07 16:11:35 -0500507 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500508
509 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
510 BB_DISKMON_WARNINTERVAL = "50M,5K"
511
512 These variables cause the
513 OpenEmbedded build system to issue subsequent warnings each time the
514 available disk space further reduces by 50 Mbytes or the number of
515 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
516 directory. Subsequent warnings based on the interval occur each time
517 a respective interval is reached beyond the initial warning (i.e. 1
518 Gbytes and 100 Kbytes).
519
Andrew Geissler517393d2023-01-13 08:55:19 -0600520 :term:`BB_ENV_PASSTHROUGH`
521 See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual.
522
523 :term:`BB_ENV_PASSTHROUGH_ADDITIONS`
524 See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual.
525
526 :term:`BB_FETCH_PREMIRRORONLY`
527 See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual.
528
529 :term:`BB_FILENAME`
530 See :term:`bitbake:BB_FILENAME` in the BitBake manual.
531
Andrew Geisslerf0343792020-11-18 10:42:21 -0600532 :term:`BB_GENERATE_MIRROR_TARBALLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500533 Causes tarballs of the source control repositories (e.g. Git
534 repositories), including metadata, to be placed in the
535 :term:`DL_DIR` directory.
536
537 For performance reasons, creating and placing tarballs of these
538 repositories is not the default action by the OpenEmbedded build
Andrew Geissler517393d2023-01-13 08:55:19 -0600539 system::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500540
541 BB_GENERATE_MIRROR_TARBALLS = "1"
542
543 Set this variable in your
544 ``local.conf`` file in the :term:`Build Directory`.
545
546 Once you have the tarballs containing your source files, you can
Andrew Geissler09036742021-06-25 14:25:14 -0500547 clean up your :term:`DL_DIR` directory by deleting any Git or other
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500548 source control work directories.
549
Andrew Geissler517393d2023-01-13 08:55:19 -0600550 :term:`BB_GENERATE_SHALLOW_TARBALLS`
551 See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
552
553 :term:`BB_GIT_SHALLOW`
554 See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual.
555
556 :term:`BB_GIT_SHALLOW_DEPTH`
557 See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual.
558
559 :term:`BB_HASHCHECK_FUNCTION`
560 See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual.
561
562 :term:`BB_HASHCONFIG_IGNORE_VARS`
563 See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual.
564
565 :term:`BB_HASHSERVE`
566 See :term:`bitbake:BB_HASHSERVE` in the BitBake manual.
567
568 :term:`BB_HASHSERVE_UPSTREAM`
569 See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual.
570
571 :term:`BB_INVALIDCONF`
572 See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual.
573
Patrick Williams44b3caf2024-04-12 16:51:14 -0500574 :term:`BB_LOADFACTOR_MAX`
575 The system load threshold above which BitBake will stop runnig extra
576 tasks.
577
Andrew Geissler517393d2023-01-13 08:55:19 -0600578 :term:`BB_LOGCONFIG`
579 See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual.
580
581 :term:`BB_LOGFMT`
582 See :term:`bitbake:BB_LOGFMT` in the BitBake manual.
583
584 :term:`BB_MULTI_PROVIDER_ALLOWED`
585 See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual.
586
587 :term:`BB_NICE_LEVEL`
588 See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual.
589
590 :term:`BB_NO_NETWORK`
591 See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual.
592
593 :term:`BB_NUMBER_PARSE_THREADS`
594 See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual.
595
Andrew Geisslerf0343792020-11-18 10:42:21 -0600596 :term:`BB_NUMBER_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500597 The maximum number of tasks BitBake should run in parallel at any one
598 time. The OpenEmbedded build system automatically configures this
599 variable to be equal to the number of cores on the build system. For
600 example, a system with a dual core processor that also uses
Andrew Geissler09036742021-06-25 14:25:14 -0500601 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500602 to "4".
603
604 For single socket systems (i.e. one CPU), you should not have to
605 override this variable to gain optimal parallelism during builds.
606 However, if you have very large systems that employ multiple physical
Andrew Geissler09036742021-06-25 14:25:14 -0500607 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500608 is not set higher than "20".
609
610 For more information on speeding up builds, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600611 ":ref:`dev-manual/speeding-up-build:speeding up a build`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500612 section in the Yocto Project Development Tasks Manual.
613
Patrick Williams7784c422022-11-17 07:29:11 -0600614 On the other hand, if your goal is to limit the amount of system
615 resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS`
616 to a number lower than the number of CPU threads in your machine
617 won't be sufficient. That's because each package will still be built
618 and installed through a number of parallel jobs specified by the
619 :term:`PARALLEL_MAKE` variable, which is by default the number of CPU
620 threads in your system, and is not impacted by the
621 :term:`BB_NUMBER_THREADS` value.
622
623 So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set
624 :term:`PARALLEL_MAKE`, most of your system resources will be consumed
625 anyway.
626
627 Therefore, if you intend to reduce the load of your build system by
628 setting :term:`BB_NUMBER_THREADS` to a relatively low value compared
629 to the number of CPU threads on your system, you should also set
630 :term:`PARALLEL_MAKE` to a similarly low value.
631
632 An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage
633 of build system resources under control is to use the smarter
634 :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or
635 :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake
636 from starting new tasks as long as thresholds are exceeded. Anyway,
637 as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the
638 tasks already being run from using all CPU threads on the system
639 if :term:`PARALLEL_MAKE` is not set to a low value.
640
Andrew Geissler517393d2023-01-13 08:55:19 -0600641 :term:`BB_ORIGENV`
642 See :term:`bitbake:BB_ORIGENV` in the BitBake manual.
643
644 :term:`BB_PRESERVE_ENV`
645 See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual.
646
647 :term:`BB_PRESSURE_MAX_CPU`
648 See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual.
649
650 :term:`BB_PRESSURE_MAX_IO`
651 See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual.
652
653 :term:`BB_PRESSURE_MAX_MEMORY`
654 See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual.
655
656 :term:`BB_RUNFMT`
657 See :term:`bitbake:BB_RUNFMT` in the BitBake manual.
658
659 :term:`BB_RUNTASK`
660 See :term:`bitbake:BB_RUNTASK` in the BitBake manual.
661
662 :term:`BB_SCHEDULER`
663 See :term:`bitbake:BB_SCHEDULER` in the BitBake manual.
664
665 :term:`BB_SCHEDULERS`
666 See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual.
667
Andrew Geisslerf0343792020-11-18 10:42:21 -0600668 :term:`BB_SERVER_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500669 Specifies the time (in seconds) after which to unload the BitBake
Andrew Geissler09036742021-06-25 14:25:14 -0500670 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500671 long the BitBake server stays resident between invocations.
672
673 For example, the following statement in your ``local.conf`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500674 instructs the server to be unloaded after 20 seconds of inactivity::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500675
676 BB_SERVER_TIMEOUT = "20"
677
678 If you want the server to never be unloaded,
Andrew Geissler5f350902021-07-23 13:09:54 -0400679 set :term:`BB_SERVER_TIMEOUT` to "-1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500680
Andrew Geissler517393d2023-01-13 08:55:19 -0600681 :term:`BB_SETSCENE_DEPVALID`
682 See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual.
683
684 :term:`BB_SIGNATURE_EXCLUDE_FLAGS`
685 See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual.
686
687 :term:`BB_SIGNATURE_HANDLER`
688 See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual.
689
690 :term:`BB_SRCREV_POLICY`
691 See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual.
692
693 :term:`BB_STRICT_CHECKSUM`
694 See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual.
695
696 :term:`BB_TASK_IONICE_LEVEL`
697 See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual.
698
699 :term:`BB_TASK_NICE_LEVEL`
700 See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual.
701
702 :term:`BB_TASKHASH`
703 See :term:`bitbake:BB_TASKHASH` in the BitBake manual.
704
705 :term:`BB_VERBOSE_LOGS`
706 See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual.
707
708 :term:`BB_WORKERCONTEXT`
709 See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual.
710
Andrew Geisslerf0343792020-11-18 10:42:21 -0600711 :term:`BBCLASSEXTEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500712 Allows you to extend a recipe so that it builds variants of the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700713 software. There are common variants for recipes as "natives" like
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500714 ``quilt-native``, which is a copy of Quilt built to run on the build
715 system; "crosses" such as ``gcc-cross``, which is a compiler built to
716 run on the build machine but produces binaries that run on the target
Andrew Geissler517393d2023-01-13 08:55:19 -0600717 :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which
718 targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in
719 the form "``multilib:``\ multilib_name".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500720
721 To build a different variant of the recipe with a minimal amount of
Andrew Geisslerc926e172021-05-07 16:11:35 -0500722 code, it usually is as simple as adding the following to your recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500723
724 BBCLASSEXTEND =+ "native nativesdk"
725 BBCLASSEXTEND =+ "multilib:multilib_name"
726
727 .. note::
728
Andrew Geissler09036742021-06-25 14:25:14 -0500729 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500730 variants by rewriting variable values and applying overrides such
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500731 as ``:class-native``. For example, to generate a native version of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500732 a recipe, a :term:`DEPENDS` on "foo" is rewritten
Andrew Geissler5f350902021-07-23 13:09:54 -0400733 to a :term:`DEPENDS` on "foo-native".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500734
Andrew Geissler09036742021-06-25 14:25:14 -0500735 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500736 Parsing once adds some limitations. For example, it is not
737 possible to include a different file depending on the variant,
738 since ``include`` statements are processed when the recipe is
739 parsed.
740
Andrew Geissler517393d2023-01-13 08:55:19 -0600741 :term:`BBDEBUG`
742 See :term:`bitbake:BBDEBUG` in the BitBake manual.
743
Andrew Geisslerf0343792020-11-18 10:42:21 -0600744 :term:`BBFILE_COLLECTIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500745 Lists the names of configured layers. These names are used to find
746 the other ``BBFILE_*`` variables. Typically, each layer will append
747 its name to this variable in its ``conf/layer.conf`` file.
748
Andrew Geisslerf0343792020-11-18 10:42:21 -0600749 :term:`BBFILE_PATTERN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500750 Variable that expands to match files from
751 :term:`BBFILES` in a particular layer. This variable
752 is used in the ``conf/layer.conf`` file and must be suffixed with the
753 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
754
Andrew Geisslerf0343792020-11-18 10:42:21 -0600755 :term:`BBFILE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500756 Assigns the priority for recipe files in each layer.
757
758 This variable is useful in situations where the same recipe appears
759 in more than one layer. Setting this variable allows you to
760 prioritize a layer against other layers that contain the same recipe
Andrew Geissler615f2f12022-07-15 14:00:58 -0500761 --- effectively letting you control the precedence for the multiple
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500762 layers. The precedence established through this variable stands
763 regardless of a recipe's version (:term:`PV` variable). For
Andrew Geissler09036742021-06-25 14:25:14 -0500764 example, a layer that has a recipe with a higher :term:`PV` value but for
765 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500766 has a lower precedence.
767
Andrew Geissler09036742021-06-25 14:25:14 -0500768 A larger value for the :term:`BBFILE_PRIORITY` variable results in a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500769 higher precedence. For example, the value 6 has a higher precedence
Andrew Geissler09036742021-06-25 14:25:14 -0500770 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
771 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500772 for more information. The default priority, if unspecified for a
773 layer with no dependencies, is the lowest defined priority + 1 (or 1
774 if no priorities are defined).
775
776 .. tip::
777
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500778 You can use the command ``bitbake-layers show-layers``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500779 to list all configured layers along with their priorities.
780
Andrew Geisslerf0343792020-11-18 10:42:21 -0600781 :term:`BBFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500782 A space-separated list of recipe files BitBake uses to build
783 software.
784
785 When specifying recipe files, you can pattern match using Python's
Patrick Williams2390b1b2022-11-03 13:47:49 -0500786 `glob <https://docs.python.org/3/library/glob.html>`__ syntax.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500787 For details on the syntax, see the documentation by following the
788 previous link.
789
Andrew Geisslerf0343792020-11-18 10:42:21 -0600790 :term:`BBFILES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500791 Activates content when identified layers are present. You identify
792 the layers by the collections that the layers define.
793
Andrew Geissler09036742021-06-25 14:25:14 -0500794 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500795 whose corresponding ``.bb`` file is in a layer that attempts to
796 modify other layers through ``.bbappend`` but does not want to
797 introduce a hard dependency on those other layers.
798
Andrew Geissler09036742021-06-25 14:25:14 -0500799 Use the following form for :term:`BBFILES_DYNAMIC`:
Andrew Geissler595f6302022-01-24 19:11:47 +0000800 ``collection_name:filename_pattern``.
801
802 The following example identifies two collection names and two
803 filename patterns::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500804
805 BBFILES_DYNAMIC += " \
806 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
807 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
808 "
809
810 This next example shows an error message that occurs because invalid
Andrew Geissler595f6302022-01-24 19:11:47 +0000811 entries are found, which cause parsing to fail:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500812
813 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500814
815 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
816 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
817 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
818
Andrew Geissler517393d2023-01-13 08:55:19 -0600819 :term:`BBINCLUDED`
820 See :term:`bitbake:BBINCLUDED` in the BitBake manual.
821
Andrew Geisslerf0343792020-11-18 10:42:21 -0600822 :term:`BBINCLUDELOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500823 Variable that controls how BitBake displays logs on build failure.
824
Andrew Geisslerf0343792020-11-18 10:42:21 -0600825 :term:`BBINCLUDELOGS_LINES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500826 If :term:`BBINCLUDELOGS` is set, specifies the
827 maximum number of lines from the task log file to print when
Andrew Geissler09036742021-06-25 14:25:14 -0500828 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500829 the entire log is printed.
830
Andrew Geisslerf0343792020-11-18 10:42:21 -0600831 :term:`BBLAYERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500832 Lists the layers to enable during the build. This variable is defined
833 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500834 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500835
836 BBLAYERS = " \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500837 /home/scottrif/poky/meta \
838 /home/scottrif/poky/meta-poky \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500839 /home/scottrif/poky/meta-yocto-bsp \
840 /home/scottrif/poky/meta-mykernel \
841 "
842
843 This example enables four layers, one of which is a custom,
844 user-defined layer named ``meta-mykernel``.
845
Andrew Geissler517393d2023-01-13 08:55:19 -0600846 :term:`BBLAYERS_FETCH_DIR`
847 See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual.
848
Andrew Geisslerf0343792020-11-18 10:42:21 -0600849 :term:`BBMASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500850 Prevents BitBake from processing recipes and recipe append files.
851
Andrew Geissler09036742021-06-25 14:25:14 -0500852 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500853 ``.bbappend`` files. BitBake ignores any recipe or recipe append
854 files that match any of the expressions. It is as if BitBake does not
855 see them at all. Consequently, matching files are not parsed or
856 otherwise used by BitBake.
857
858 The values you provide are passed to Python's regular expression
859 compiler. Consequently, the syntax follows Python's Regular
860 Expression (re) syntax. The expressions are compared against the full
861 paths to the files. For complete syntax information, see Python's
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500862 documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500863
864 The following example uses a complete regular expression to tell
865 BitBake to ignore all recipe and recipe append files in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500866 ``meta-ti/recipes-misc/`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500867
868 BBMASK = "meta-ti/recipes-misc/"
869
870 If you want to mask out multiple directories or recipes, you can
871 specify multiple regular expression fragments. This next example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500872 masks out multiple directories and individual recipes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873
874 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
875 BBMASK += "/meta-oe/recipes-support/"
876 BBMASK += "/meta-foo/.*/openldap"
877 BBMASK += "opencv.*\.bbappend"
878 BBMASK += "lzma"
879
880 .. note::
881
882 When specifying a directory name, use the trailing slash character
883 to ensure you match just that directory name.
884
Andrew Geisslerf0343792020-11-18 10:42:21 -0600885 :term:`BBMULTICONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500886 Specifies each additional separate configuration when you are
887 building targets with multiple configurations. Use this variable in
888 your ``conf/local.conf`` configuration file. Specify a
889 multiconfigname for each configuration file you are using. For
Andrew Geisslerc926e172021-05-07 16:11:35 -0500890 example, the following line specifies three configuration files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500891
892 BBMULTICONFIG = "configA configB configC"
893
Andrew Geissler615f2f12022-07-15 14:00:58 -0500894 Each configuration file you use must reside in a ``multiconfig``
895 subdirectory of a configuration directory within a layer, or
896 within the :term:`Build Directory` (e.g.
897 ``build_directory/conf/multiconfig/configA.conf`` or
898 ``mylayer/conf/multiconfig/configB.conf``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500899
Andrew Geissler09036742021-06-25 14:25:14 -0500900 For information on how to use :term:`BBMULTICONFIG` in an environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500901 that supports building targets with multiple configurations, see the
Andrew Geissler517393d2023-01-13 08:55:19 -0600902 ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500903 section in the Yocto Project Development Tasks Manual.
904
Andrew Geissler517393d2023-01-13 08:55:19 -0600905 :term:`BBPATH`
906 See :term:`bitbake:BBPATH` in the BitBake manual.
907
Andrew Geisslerf0343792020-11-18 10:42:21 -0600908 :term:`BBSERVER`
Andrew Geissler09036742021-06-25 14:25:14 -0500909 If defined in the BitBake environment, :term:`BBSERVER` points to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500910 BitBake remote server.
911
912 Use the following format to export the variable to the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -0500913 environment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500914
915 export BBSERVER=localhost:$port
916
Andrew Geissler7e0e3c02022-02-25 20:34:39 +0000917 By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`.
Andrew Geissler09036742021-06-25 14:25:14 -0500918 Consequently, :term:`BBSERVER` is excluded from checksum and dependency
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500919 data.
920
Andrew Geissler517393d2023-01-13 08:55:19 -0600921 :term:`BBTARGETS`
922 See :term:`bitbake:BBTARGETS` in the BitBake manual.
923
Andrew Geisslerf0343792020-11-18 10:42:21 -0600924 :term:`BINCONFIG`
Andrew Geissler517393d2023-01-13 08:55:19 -0600925 When inheriting the :ref:`ref-classes-binconfig-disabled` class, this
926 variable specifies binary configuration scripts to disable in favor of
927 using ``pkg-config`` to query the information. The
928 :ref:`ref-classes-binconfig-disabled` class will modify the specified
929 scripts to return an error so that calls to them can be easily found
930 and replaced.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500931
932 To add multiple scripts, separate them by spaces. Here is an example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500933 from the ``libpng`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500934
935 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
936
Andrew Geisslerf0343792020-11-18 10:42:21 -0600937 :term:`BINCONFIG_GLOB`
Andrew Geissler517393d2023-01-13 08:55:19 -0600938 When inheriting the :ref:`ref-classes-binconfig` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939 this variable specifies a wildcard for configuration scripts that
940 need editing. The scripts are edited to correct any paths that have
941 been set up during compilation so that they are correct for use when
942 installed into the sysroot and called by the build processes of other
943 recipes.
944
945 .. note::
946
Andrew Geissler09036742021-06-25 14:25:14 -0500947 The :term:`BINCONFIG_GLOB` variable uses
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500948 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__,
949 which is recognition and expansion of wildcards during pattern
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950 matching. Shell globbing is very similar to
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500951 `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__
952 and `glob <https://docs.python.org/3/library/glob.html>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500953
954 For more information on how this variable works, see
Patrick Williams975a06f2022-10-21 14:42:47 -0500955 ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500956 You can also find general
957 information on the class in the
Andrew Geissler595f6302022-01-24 19:11:47 +0000958 ":ref:`ref-classes-binconfig`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500959
Andrew Geissler517393d2023-01-13 08:55:19 -0600960 :term:`BITBAKE_UI`
961 See :term:`bitbake:BITBAKE_UI` in the BitBake manual.
962
Andrew Geisslerf0343792020-11-18 10:42:21 -0600963 :term:`BP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500964 The base recipe name and version but without any special recipe name
Andrew Geissler09036742021-06-25 14:25:14 -0500965 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500966 comprised of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500967
968 ${BPN}-${PV}
969
Andrew Geisslerf0343792020-11-18 10:42:21 -0600970 :term:`BPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500971 This variable is a version of the :term:`PN` variable with
972 common prefixes and suffixes removed, such as ``nativesdk-``,
973 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``.
974 The exact lists of prefixes and suffixes removed are specified by the
975 :term:`MLPREFIX` and
976 :term:`SPECIAL_PKGSUFFIX` variables,
977 respectively.
978
Andrew Geisslerf0343792020-11-18 10:42:21 -0600979 :term:`BUGTRACKER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500980 Specifies a URL for an upstream bug tracking website for a recipe.
981 The OpenEmbedded build system does not use this variable. Rather, the
982 variable is a useful pointer in case a bug in the software being
983 built needs to be manually reported.
984
Andrew Geisslerf0343792020-11-18 10:42:21 -0600985 :term:`BUILD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500986 Specifies the architecture of the build host (e.g. ``i686``). The
Andrew Geissler09036742021-06-25 14:25:14 -0500987 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500988 machine name reported by the ``uname`` command.
989
Andrew Geisslerf0343792020-11-18 10:42:21 -0600990 :term:`BUILD_AS_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500991 Specifies the architecture-specific assembler flags for the build
Andrew Geissler09036742021-06-25 14:25:14 -0500992 host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500993
Andrew Geisslerf0343792020-11-18 10:42:21 -0600994 :term:`BUILD_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500995 Specifies the architecture-specific C compiler flags for the build
Andrew Geissler09036742021-06-25 14:25:14 -0500996 host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500997
Andrew Geisslerf0343792020-11-18 10:42:21 -0600998 :term:`BUILD_CCLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500999 Specifies the linker command to be used for the build host when the C
Andrew Geissler09036742021-06-25 14:25:14 -05001000 compiler is being used as the linker. By default, :term:`BUILD_CCLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001001 points to GCC and passes as arguments the value of
1002 :term:`BUILD_CC_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -05001003 :term:`BUILD_CC_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001004
Andrew Geisslerf0343792020-11-18 10:42:21 -06001005 :term:`BUILD_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001006 Specifies the flags to pass to the C compiler when building for the
1007 build host. When building in the ``-native`` context,
1008 :term:`CFLAGS` is set to the value of this variable by
1009 default.
1010
Andrew Geisslerf0343792020-11-18 10:42:21 -06001011 :term:`BUILD_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001012 Specifies the flags to pass to the C preprocessor (i.e. to both the C
1013 and the C++ compilers) when building for the build host. When
1014 building in the ``-native`` context, :term:`CPPFLAGS`
1015 is set to the value of this variable by default.
1016
Andrew Geisslerf0343792020-11-18 10:42:21 -06001017 :term:`BUILD_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001018 Specifies the flags to pass to the C++ compiler when building for the
1019 build host. When building in the ``-native`` context,
1020 :term:`CXXFLAGS` is set to the value of this variable
1021 by default.
1022
Andrew Geisslerf0343792020-11-18 10:42:21 -06001023 :term:`BUILD_FC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001024 Specifies the Fortran compiler command for the build host. By
Andrew Geissler09036742021-06-25 14:25:14 -05001025 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001026 value of :term:`BUILD_CC_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -05001027 :term:`BUILD_CC_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001028
Andrew Geisslerf0343792020-11-18 10:42:21 -06001029 :term:`BUILD_LD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001030 Specifies the linker command for the build host. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05001031 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001032 the value of :term:`BUILD_LD_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -05001033 :term:`BUILD_LD_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001034
Andrew Geisslerf0343792020-11-18 10:42:21 -06001035 :term:`BUILD_LD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001036 Specifies architecture-specific linker flags for the build host. By
Andrew Geissler09036742021-06-25 14:25:14 -05001037 default, the value of :term:`BUILD_LD_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001038
Andrew Geisslerf0343792020-11-18 10:42:21 -06001039 :term:`BUILD_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001040 Specifies the flags to pass to the linker when building for the build
1041 host. When building in the ``-native`` context,
1042 :term:`LDFLAGS` is set to the value of this variable
1043 by default.
1044
Andrew Geisslerf0343792020-11-18 10:42:21 -06001045 :term:`BUILD_OPTIMIZATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001046 Specifies the optimization flags passed to the C compiler when
1047 building for the build host or the SDK. The flags are passed through
1048 the :term:`BUILD_CFLAGS` and
1049 :term:`BUILDSDK_CFLAGS` default values.
1050
Andrew Geissler5f350902021-07-23 13:09:54 -04001051 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001052 -pipe".
1053
Andrew Geisslerf0343792020-11-18 10:42:21 -06001054 :term:`BUILD_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001055 Specifies the operating system in use on the build host (e.g.
1056 "linux"). The OpenEmbedded build system sets the value of
Andrew Geissler615f2f12022-07-15 14:00:58 -05001057 :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001058 first word, converted to lower-case characters.
1059
Andrew Geisslerf0343792020-11-18 10:42:21 -06001060 :term:`BUILD_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001061 The toolchain binary prefix used for native recipes. The OpenEmbedded
Andrew Geissler09036742021-06-25 14:25:14 -05001062 build system uses the :term:`BUILD_PREFIX` value to set the
Andrew Geissler517393d2023-01-13 08:55:19 -06001063 :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001064
Andrew Geisslerf0343792020-11-18 10:42:21 -06001065 :term:`BUILD_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001066 Specifies the command to be used to strip debugging symbols from
Andrew Geissler09036742021-06-25 14:25:14 -05001067 binaries produced for the build host. By default, :term:`BUILD_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001068 points to
1069 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
1070
Andrew Geisslerf0343792020-11-18 10:42:21 -06001071 :term:`BUILD_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001072 Specifies the system, including the architecture and the operating
1073 system, to use when building for the build host (i.e. when building
Andrew Geissler517393d2023-01-13 08:55:19 -06001074 :ref:`ref-classes-native` recipes).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001075
1076 The OpenEmbedded build system automatically sets this variable based
1077 on :term:`BUILD_ARCH`,
1078 :term:`BUILD_VENDOR`, and
1079 :term:`BUILD_OS`. You do not need to set the
Andrew Geissler09036742021-06-25 14:25:14 -05001080 :term:`BUILD_SYS` variable yourself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001081
Andrew Geisslerf0343792020-11-18 10:42:21 -06001082 :term:`BUILD_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001083 Specifies the vendor name to use when building for the build host.
1084 The default value is an empty string ("").
1085
Andrew Geisslerf0343792020-11-18 10:42:21 -06001086 :term:`BUILDDIR`
Patrick Williams2390b1b2022-11-03 13:47:49 -05001087 Points to the location of the :term:`Build Directory`. You can define
1088 this directory indirectly through the :ref:`structure-core-script` script
1089 by passing in a :term:`Build Directory` path when you run the script. If
1090 you run the script and do not provide a :term:`Build Directory` path, the
1091 :term:`BUILDDIR` defaults to ``build`` in the current directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001092
Andrew Geisslerf0343792020-11-18 10:42:21 -06001093 :term:`BUILDHISTORY_COMMIT`
Andrew Geissler517393d2023-01-13 08:55:19 -06001094 When inheriting the :ref:`ref-classes-buildhistory` class, this variable
1095 specifies whether or not to commit the build history output in a local
1096 Git repository. If set to "1", this local repository will be maintained
1097 automatically by the :ref:`ref-classes-buildhistory` class and a commit
1098 will be created on every build for changes to each top-level subdirectory
1099 of the build history output (images, packages, and sdk). If you want to
1100 track changes to build history over time, you should set this value to
1101 "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001102
Andrew Geissler517393d2023-01-13 08:55:19 -06001103 By default, the :ref:`ref-classes-buildhistory` class
Patrick Williams975a06f2022-10-21 14:42:47 -05001104 enables committing the buildhistory output in a local Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001105
Patrick Williams975a06f2022-10-21 14:42:47 -05001106 BUILDHISTORY_COMMIT ?= "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001107
Andrew Geisslerf0343792020-11-18 10:42:21 -06001108 :term:`BUILDHISTORY_COMMIT_AUTHOR`
Andrew Geissler517393d2023-01-13 08:55:19 -06001109 When inheriting the :ref:`ref-classes-buildhistory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001110 class, this variable specifies the author to use for each Git commit.
Andrew Geissler09036742021-06-25 14:25:14 -05001111 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001112 :term:`BUILDHISTORY_COMMIT` variable must
1113 be set to "1".
1114
1115 Git requires that the value you provide for the
Andrew Geissler09036742021-06-25 14:25:14 -05001116 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001117 email@host". Providing an email address or host that is not valid
1118 does not produce an error.
1119
Andrew Geissler517393d2023-01-13 08:55:19 -06001120 By default, the :ref:`ref-classes-buildhistory` class sets the variable
1121 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001122
1123 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
1124
Andrew Geisslerf0343792020-11-18 10:42:21 -06001125 :term:`BUILDHISTORY_DIR`
Andrew Geissler517393d2023-01-13 08:55:19 -06001126 When inheriting the :ref:`ref-classes-buildhistory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001127 class, this variable specifies the directory in which build history
1128 information is kept. For more information on how the variable works,
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00001129 see the :ref:`ref-classes-buildhistory` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001130
Andrew Geissler517393d2023-01-13 08:55:19 -06001131 By default, the :ref:`ref-classes-buildhistory` class sets the directory
1132 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001133
1134 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
1135
Andrew Geisslerf0343792020-11-18 10:42:21 -06001136 :term:`BUILDHISTORY_FEATURES`
Andrew Geissler517393d2023-01-13 08:55:19 -06001137 When inheriting the :ref:`ref-classes-buildhistory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001138 class, this variable specifies the build history features to be
1139 enabled. For more information on how build history works, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06001140 ":ref:`dev-manual/build-quality:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001141 section in the Yocto Project Development Tasks Manual.
1142
1143 You can specify these features in the form of a space-separated list:
1144
1145 - *image:* Analysis of the contents of images, which includes the
1146 list of installed packages among other things.
1147
1148 - *package:* Analysis of the contents of individual packages.
1149
1150 - *sdk:* Analysis of the contents of the software development kit
1151 (SDK).
1152
1153 - *task:* Save output file signatures for
Andrew Geissler09209ee2020-12-13 08:44:15 -06001154 :ref:`shared state <overview-manual/concepts:shared state cache>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001155 (sstate) tasks.
1156 This saves one file per task and lists the SHA-256 checksums for
1157 each file staged (i.e. the output of the task).
1158
Andrew Geissler517393d2023-01-13 08:55:19 -06001159 By default, the :ref:`ref-classes-buildhistory` class enables the
1160 following features::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001161
1162 BUILDHISTORY_FEATURES ?= "image package sdk"
1163
Andrew Geisslerf0343792020-11-18 10:42:21 -06001164 :term:`BUILDHISTORY_IMAGE_FILES`
Andrew Geissler517393d2023-01-13 08:55:19 -06001165 When inheriting the :ref:`ref-classes-buildhistory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001166 class, this variable specifies a list of paths to files copied from
1167 the image contents into the build history directory under an
1168 "image-files" directory in the directory for the image, so that you
1169 can track the contents of each file. The default is to copy
1170 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for
1171 changes in user and group entries. You can modify the list to include
1172 any file. Specifying an invalid path does not produce an error.
1173 Consequently, you can include files that might not always be present.
1174
Andrew Geissler517393d2023-01-13 08:55:19 -06001175 By default, the :ref:`ref-classes-buildhistory` class provides paths to
1176 the following files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001177
1178 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1179
Andrew Geissler5f350902021-07-23 13:09:54 -04001180 :term:`BUILDHISTORY_PATH_PREFIX_STRIP`
Andrew Geissler517393d2023-01-13 08:55:19 -06001181 When inheriting the :ref:`ref-classes-buildhistory`
Andrew Geissler5f350902021-07-23 13:09:54 -04001182 class, this variable specifies a common path prefix that should be
1183 stripped off the beginning of paths in the task signature list when the
1184 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be
1185 useful when build history is populated from multiple sources that may not
1186 all use the same top level directory.
1187
Andrew Geissler517393d2023-01-13 08:55:19 -06001188 By default, the :ref:`ref-classes-buildhistory` class sets the variable
1189 as follows::
Andrew Geissler5f350902021-07-23 13:09:54 -04001190
1191 BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
1192
1193 In this case, no prefixes will be stripped.
1194
Andrew Geisslerf0343792020-11-18 10:42:21 -06001195 :term:`BUILDHISTORY_PUSH_REPO`
Andrew Geissler517393d2023-01-13 08:55:19 -06001196 When inheriting the :ref:`ref-classes-buildhistory` class, this variable
1197 optionally specifies a remote repository to which build history pushes
1198 Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work,
1199 :term:`BUILDHISTORY_COMMIT` must be set to "1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001200
1201 The repository should correspond to a remote address that specifies a
1202 repository as understood by Git, or alternatively to a remote name
1203 that you have set up manually using ``git remote`` within the local
1204 repository.
1205
Andrew Geissler517393d2023-01-13 08:55:19 -06001206 By default, the :ref:`ref-classes-buildhistory` class sets the variable
1207 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001208
1209 BUILDHISTORY_PUSH_REPO ?= ""
1210
Andrew Geissler517393d2023-01-13 08:55:19 -06001211 :term:`BUILDNAME`
1212 See :term:`bitbake:BUILDNAME` in the BitBake manual.
1213
Andrew Geisslerf0343792020-11-18 10:42:21 -06001214 :term:`BUILDSDK_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001215 Specifies the flags to pass to the C compiler when building for the
1216 SDK. When building in the ``nativesdk-`` context,
1217 :term:`CFLAGS` is set to the value of this variable by
1218 default.
1219
Andrew Geisslerf0343792020-11-18 10:42:21 -06001220 :term:`BUILDSDK_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001221 Specifies the flags to pass to the C pre-processor (i.e. to both the
1222 C and the C++ compilers) when building for the SDK. When building in
1223 the ``nativesdk-`` context, :term:`CPPFLAGS` is set
1224 to the value of this variable by default.
1225
Andrew Geisslerf0343792020-11-18 10:42:21 -06001226 :term:`BUILDSDK_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001227 Specifies the flags to pass to the C++ compiler when building for the
1228 SDK. When building in the ``nativesdk-`` context,
1229 :term:`CXXFLAGS` is set to the value of this variable
1230 by default.
1231
Andrew Geisslerf0343792020-11-18 10:42:21 -06001232 :term:`BUILDSDK_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001233 Specifies the flags to pass to the linker when building for the SDK.
1234 When building in the ``nativesdk-`` context,
1235 :term:`LDFLAGS` is set to the value of this variable
1236 by default.
1237
Andrew Geisslerf0343792020-11-18 10:42:21 -06001238 :term:`BUILDSTATS_BASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001239 Points to the location of the directory that holds build statistics
Andrew Geissler517393d2023-01-13 08:55:19 -06001240 when you use and enable the :ref:`ref-classes-buildstats` class. The
Andrew Geissler09036742021-06-25 14:25:14 -05001241 :term:`BUILDSTATS_BASE` directory defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001242 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
1243
Andrew Geisslerf0343792020-11-18 10:42:21 -06001244 :term:`BUSYBOX_SPLIT_SUID`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001245 For the BusyBox recipe, specifies whether to split the output
1246 executable file into two parts: one for features that require
1247 ``setuid root``, and one for the remaining features (i.e. those that
1248 do not require ``setuid root``).
1249
Andrew Geissler09036742021-06-25 14:25:14 -05001250 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001251 splitting the output executable file. Set the variable to "0" to get
1252 a single output executable file.
1253
Andrew Geissler517393d2023-01-13 08:55:19 -06001254 :term:`BZRDIR`
1255 See :term:`bitbake:BZRDIR` in the BitBake manual.
1256
Andrew Geisslerf0343792020-11-18 10:42:21 -06001257 :term:`CACHE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001258 Specifies the directory BitBake uses to store a cache of the
1259 :term:`Metadata` so it does not need to be parsed every time
1260 BitBake is started.
1261
Patrick Williams96e4b4e2025-02-03 15:49:15 -05001262 :term:`CARGO_INSTALL_LIBRARIES`
1263 When inheriting the :ref:`ref-classes-cargo` class, the variable
1264 :term:`CARGO_INSTALL_LIBRARIES` can be set to a non-empty value by
1265 individual recipes to enable the installation of the libraries the
1266 recipe has built in ``${B}/target/${CARGO_TARGET_SUBDIR}`` (files ending
1267 with ``.so`` or ``.rlib``). By default this variable is not defined and
1268 libraries are not installed, to replicate the behavior of the ``cargo
1269 install`` command.
1270
Andrew Geisslerf0343792020-11-18 10:42:21 -06001271 :term:`CC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001272 The minimal command and arguments used to run the C compiler.
1273
Andrew Geisslerf0343792020-11-18 10:42:21 -06001274 :term:`CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001275 Specifies the flags to pass to the C compiler. This variable is
1276 exported to an environment variable and thus made visible to the
1277 software being built during the compilation step.
1278
Andrew Geissler09036742021-06-25 14:25:14 -05001279 Default initialization for :term:`CFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001280 being built:
1281
1282 - :term:`TARGET_CFLAGS` when building for the
1283 target
1284
1285 - :term:`BUILD_CFLAGS` when building for the
1286 build host (i.e. ``-native``)
1287
1288 - :term:`BUILDSDK_CFLAGS` when building for
1289 an SDK (i.e. ``nativesdk-``)
1290
Patrick Williams96e4b4e2025-02-03 15:49:15 -05001291 :term:`CHECKLAYER_REQUIRED_TESTS`
1292 The :term:`CHECKLAYER_REQUIRED_TESTS` variable lists the QA tests that are
1293 required to be enabled to pass the Yocto Project Compatible status for a
1294 layer. It is meant to be a read-only variable and any change to the
1295 variable may be done with the approval of the :oe_wiki:`Technical Steering
1296 Committee (TSC) </TSC>`.
1297
1298 For more information on the Yocto Project Compatible status, see
1299 the :ref:`dev-manual/layers:Making Sure Your Layer is Compatible With
1300 Yocto Project` section of the Yocto Project Development Manual.
1301
Andrew Geisslerf0343792020-11-18 10:42:21 -06001302 :term:`CLASSOVERRIDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001303 An internal variable specifying the special class override that
1304 should currently apply (e.g. "class-target", "class-native", and so
1305 forth). The classes that use this variable (e.g.
Andrew Geissler517393d2023-01-13 08:55:19 -06001306 :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth)
1307 set the variable to appropriate values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001308
1309 .. note::
1310
Andrew Geissler5f350902021-07-23 13:09:54 -04001311 :term:`CLASSOVERRIDE` gets its default "class-target" value from the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001312 ``bitbake.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001313
1314 As an example, the following override allows you to install extra
Andrew Geisslerc926e172021-05-07 16:11:35 -05001315 files, but only when building for the target::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001316
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001317 do_install:append:class-target() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001318 install my-extra-file ${D}${sysconfdir}
1319 }
1320
1321 Here is an example where ``FOO`` is set to
1322 "native" when building for the build host, and to "other" when not
Andrew Geisslerc926e172021-05-07 16:11:35 -05001323 building for the build host::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001324
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001325 FOO:class-native = "native"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001326 FOO = "other"
1327
Andrew Geissler09036742021-06-25 14:25:14 -05001328 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001329 that it is included in the default value of
1330 :term:`OVERRIDES`.
1331
Andrew Geisslerf0343792020-11-18 10:42:21 -06001332 :term:`CLEANBROKEN`
Andrew Geissler09036742021-06-25 14:25:14 -05001333 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001334 ``make clean`` command does not work for the software being built.
1335 Consequently, the OpenEmbedded build system will not try to run
1336 ``make clean`` during the :ref:`ref-tasks-configure`
1337 task, which is the default behavior.
1338
Andrew Geisslerf0343792020-11-18 10:42:21 -06001339 :term:`COMBINED_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001340 Provides a list of hardware features that are enabled in both
1341 :term:`MACHINE_FEATURES` and
1342 :term:`DISTRO_FEATURES`. This select list of
1343 features contains features that make sense to be controlled both at
1344 the machine and distribution configuration level. For example, the
1345 "bluetooth" feature requires hardware support but should also be
1346 optional at the distribution level, in case the hardware supports
1347 Bluetooth but you do not ever intend to use it.
1348
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06001349 :term:`COMMERCIAL_AUDIO_PLUGINS`
1350 This variable is specific to the :yocto_git:`GStreamer recipes
1351 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1352 It allows to build the GStreamer `"ugly"
Patrick Williams520786c2023-06-25 16:20:36 -05001353 <https://github.com/GStreamer/gst-plugins-ugly>`__ and
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06001354 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins.
1355
1356 See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1357 section for usage details.
1358
1359 :term:`COMMERCIAL_VIDEO_PLUGINS`
1360 This variable is specific to the :yocto_git:`GStreamer recipes
1361 </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`.
1362 It allows to build the GStreamer `"ugly"
Patrick Williams520786c2023-06-25 16:20:36 -05001363 <https://github.com/GStreamer/gst-plugins-ugly>`__ and
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06001364 `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins.
1365
1366 See the :ref:`dev-manual/licenses:other variables related to commercial licenses`
1367 section for usage details.
1368
Andrew Geisslerf0343792020-11-18 10:42:21 -06001369 :term:`COMMON_LICENSE_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001370 Points to ``meta/files/common-licenses`` in the
1371 :term:`Source Directory`, which is where generic license
1372 files reside.
1373
Andrew Geisslerf0343792020-11-18 10:42:21 -06001374 :term:`COMPATIBLE_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001375 A regular expression that resolves to one or more hosts (when the
1376 recipe is native) or one or more targets (when the recipe is
1377 non-native) with which a recipe is compatible. The regular expression
1378 is matched against :term:`HOST_SYS`. You can use the
1379 variable to stop recipes from being built for classes of systems with
1380 which the recipes are not compatible. Stopping these builds is
1381 particularly useful with kernels. The variable also helps to increase
1382 parsing speed since the build system skips parsing recipes not
1383 compatible with the current system.
1384
Andrew Geisslerf0343792020-11-18 10:42:21 -06001385 :term:`COMPATIBLE_MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001386 A regular expression that resolves to one or more target machines
1387 with which a recipe is compatible. The regular expression is matched
1388 against :term:`MACHINEOVERRIDES`. You can use
1389 the variable to stop recipes from being built for machines with which
1390 the recipes are not compatible. Stopping these builds is particularly
1391 useful with kernels. The variable also helps to increase parsing
1392 speed since the build system skips parsing recipes not compatible
1393 with the current machine.
1394
Patrick Williamsac13d5f2023-11-24 18:59:46 -06001395 If one wants to have a recipe only available for some architectures
1396 (here ``aarch64`` and ``mips64``), the following can be used::
1397
1398 COMPATIBLE_MACHINE = "^$"
1399 COMPATIBLE_MACHINE:arch64 = "^(aarch64)$"
1400 COMPATIBLE_MACHINE:mips64 = "^(mips64)$"
1401
1402 The first line means "match all machines whose :term:`MACHINEOVERRIDES`
1403 contains the empty string", which will always be none.
1404
1405 The second is for matching all machines whose :term:`MACHINEOVERRIDES`
1406 contains one override which is exactly ``aarch64``.
1407
1408 The third is for matching all machines whose :term:`MACHINEOVERRIDES`
1409 contains one override which is exactly ``mips64``.
1410
1411 The same could be achieved with::
1412
1413 COMPATIBLE_MACHINE = "^(aarch64|mips64)$"
1414
1415 .. note::
1416
1417 When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from
1418 native, the recipe is always skipped. All native recipes must be
1419 entirely target independent and should not rely on :term:`MACHINE`.
1420
Andrew Geisslerf0343792020-11-18 10:42:21 -06001421 :term:`COMPLEMENTARY_GLOB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001422 Defines wildcards to match when installing a list of complementary
1423 packages for all the packages explicitly (or implicitly) installed in
1424 an image.
1425
Patrick Williams975a06f2022-10-21 14:42:47 -05001426 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching
1427 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__),
1428 which is similar to the Unix style pathname pattern expansion
1429 (`glob <https://docs.python.org/3/library/glob.html>`__).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001430
1431 The resulting list of complementary packages is associated with an
1432 item that can be added to
1433 :term:`IMAGE_FEATURES`. An example usage of
Andrew Geissler09036742021-06-25 14:25:14 -05001434 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001435 will install -dev packages (containing headers and other development
1436 files) for every package in the image.
1437
1438 To add a new feature item pointing to a wildcard, use a variable flag
1439 to specify the feature item name and use the value to specify the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001440 wildcard. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001441
1442 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1443
Patrick Williams975a06f2022-10-21 14:42:47 -05001444 .. note::
1445
1446 When installing complementary packages, recommends relationships
1447 (set via :term:`RRECOMMENDS`) are always ignored.
1448
Andrew Geisslerf0343792020-11-18 10:42:21 -06001449 :term:`COMPONENTS_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001450 Stores sysroot components for each recipe. The OpenEmbedded build
Andrew Geissler5f350902021-07-23 13:09:54 -04001451 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001452 sysroots for other recipes.
1453
1454 The default is
1455 "``${``\ :term:`STAGING_DIR`\ ``}-components``."
1456 (i.e.
1457 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
1458
Andrew Geisslerf0343792020-11-18 10:42:21 -06001459 :term:`CONF_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001460 Tracks the version of the local configuration file (i.e.
Andrew Geissler09036742021-06-25 14:25:14 -05001461 ``local.conf``). The value for :term:`CONF_VERSION` increments each time
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001462 ``build/conf/`` compatibility changes.
1463
Andrew Geisslerf0343792020-11-18 10:42:21 -06001464 :term:`CONFFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001465 Identifies editable or configurable files that are part of a package.
1466 If the Package Management System (PMS) is being used to update
1467 packages on the target system, it is possible that configuration
1468 files you have changed after the original installation and that you
1469 now want to remain unchanged are overwritten. In other words,
1470 editable files might exist in the package that you do not want reset
Andrew Geissler09036742021-06-25 14:25:14 -05001471 as part of the package update process. You can use the :term:`CONFFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001472 variable to list the files in the package that you wish to prevent
1473 the PMS from overwriting during this update process.
1474
Andrew Geissler09036742021-06-25 14:25:14 -05001475 To use the :term:`CONFFILES` variable, provide a package name override
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001476 that identifies the resulting package. Then, provide a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001477 space-separated list of files. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001478
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001479 CONFFILES:${PN} += "${sysconfdir}/file1 \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001480 ${sysconfdir}/file2 ${sysconfdir}/file3"
1481
Andrew Geissler09036742021-06-25 14:25:14 -05001482 There is a relationship between the :term:`CONFFILES` and :term:`FILES`
1483 variables. The files listed within :term:`CONFFILES` must be a subset of
1484 the files listed within :term:`FILES`. Because the configuration files
1485 you provide with :term:`CONFFILES` are simply being identified so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001486 the PMS will not overwrite them, it makes sense that the files must
Andrew Geissler09036742021-06-25 14:25:14 -05001487 already be included as part of the package through the :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001488 variable.
1489
1490 .. note::
1491
Andrew Geissler09036742021-06-25 14:25:14 -05001492 When specifying paths as part of the :term:`CONFFILES` variable, it is
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001493 good practice to use appropriate path variables.
1494 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}``
1495 rather than ``/usr/bin``. You can find a list of these variables at
1496 the top of the ``meta/conf/bitbake.conf`` file in the
1497 :term:`Source Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001498
Andrew Geisslerf0343792020-11-18 10:42:21 -06001499 :term:`CONFIG_INITRAMFS_SOURCE`
Patrick Williams2194f502022-10-16 14:26:09 -05001500 Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001501 OpenEmbedded build system receives and uses this kernel Kconfig
1502 variable as an environment variable. By default, the variable is set
1503 to null ("").
1504
Andrew Geissler09036742021-06-25 14:25:14 -05001505 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001506 with a ``.cpio`` suffix or a space-separated list of directories and
Patrick Williams2194f502022-10-16 14:26:09 -05001507 files for building the :term:`Initramfs` image. A cpio archive should contain
1508 a filesystem archive to be used as an :term:`Initramfs` image. Directories
1509 should contain a filesystem layout to be included in the :term:`Initramfs`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001510 image. Files should contain entries according to the format described
1511 by the ``usr/gen_init_cpio`` program in the kernel tree.
1512
Patrick Williams2194f502022-10-16 14:26:09 -05001513 If you specify multiple directories and files, the :term:`Initramfs` image
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001514 will be the aggregate of all of them.
1515
Patrick Williams2194f502022-10-16 14:26:09 -05001516 For information on creating an :term:`Initramfs`, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06001517 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001518 in the Yocto Project Development Tasks Manual.
1519
Andrew Geisslerf0343792020-11-18 10:42:21 -06001520 :term:`CONFIG_SITE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001521 A list of files that contains ``autoconf`` test results relevant to
1522 the current build. This variable is used by the Autotools utilities
1523 when running ``configure``.
1524
Andrew Geisslerf0343792020-11-18 10:42:21 -06001525 :term:`CONFIGURE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001526 The minimal arguments for GNU configure.
1527
Andrew Geisslerf0343792020-11-18 10:42:21 -06001528 :term:`CONFLICT_DISTRO_FEATURES`
Andrew Geissler517393d2023-01-13 08:55:19 -06001529 When inheriting the :ref:`ref-classes-features_check`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001530 class, this variable identifies distribution features that would be
1531 in conflict should the recipe be built. In other words, if the
Andrew Geissler09036742021-06-25 14:25:14 -05001532 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also
1533 appears in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -06001534 the recipe will be skipped, and if the build system attempts to build
1535 the recipe then an error will be triggered.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001536
Andrew Geissler615f2f12022-07-15 14:00:58 -05001537 :term:`CONVERSION_CMD`
1538 This variable is used for storing image conversion commands.
1539 Image conversion can convert an image into different objects like:
1540
1541 - Compressed version of the image
1542
1543 - Checksums for the image
1544
Andrew Geissler517393d2023-01-13 08:55:19 -06001545 An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types`
1546 class is::
Andrew Geissler615f2f12022-07-15 14:00:58 -05001547
1548 CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}"
1549
Andrew Geissler9aee5002022-03-30 16:27:02 +00001550 :term:`COPY_LIC_DIRS`
1551 If set to "1" along with the
1552 :term:`COPY_LIC_MANIFEST` variable, the
1553 OpenEmbedded build system copies into the image the license files,
1554 which are located in ``/usr/share/common-licenses``, for each
1555 package. The license files are placed in directories within the image
1556 itself during build time.
1557
1558 .. note::
1559
1560 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for
1561 newly installed packages to an image, which might be most suitable for
1562 read-only filesystems that cannot be upgraded. See the
1563 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
Andrew Geissler517393d2023-01-13 08:55:19 -06001564 You can also reference the ":ref:`dev-manual/licenses:providing license text`"
Andrew Geissler9aee5002022-03-30 16:27:02 +00001565 section in the Yocto Project Development Tasks Manual for
1566 information on providing license text.
1567
1568 :term:`COPY_LIC_MANIFEST`
1569 If set to "1", the OpenEmbedded build system copies the license
1570 manifest for the image to
1571 ``/usr/share/common-licenses/license.manifest`` within the image
1572 itself during build time.
1573
1574 .. note::
1575
1576 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for
1577 newly installed packages to an image, which might be most suitable for
1578 read-only filesystems that cannot be upgraded. See the
1579 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
Andrew Geissler517393d2023-01-13 08:55:19 -06001580 You can also reference the ":ref:`dev-manual/licenses:providing license text`"
Andrew Geissler9aee5002022-03-30 16:27:02 +00001581 section in the Yocto Project Development Tasks Manual for
1582 information on providing license text.
1583
Andrew Geisslerf0343792020-11-18 10:42:21 -06001584 :term:`COPYLEFT_LICENSE_EXCLUDE`
Andrew Geissler517393d2023-01-13 08:55:19 -06001585 A space-separated list of licenses to exclude from the source archived by
1586 the :ref:`ref-classes-archiver` class. In other words, if a license in a
1587 recipe's :term:`LICENSE` value is in the value of
Andrew Geissler09036742021-06-25 14:25:14 -05001588 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001589 class.
1590
1591 .. note::
1592
Andrew Geissler09036742021-06-25 14:25:14 -05001593 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001594 :term:`COPYLEFT_LICENSE_INCLUDE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001595
1596 The default value, which is "CLOSED Proprietary", for
Andrew Geissler09036742021-06-25 14:25:14 -05001597 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the
Andrew Geissler517393d2023-01-13 08:55:19 -06001598 :ref:`ref-classes-copyleft_filter` class, which
1599 is inherited by the :ref:`ref-classes-archiver` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001600
Andrew Geisslerf0343792020-11-18 10:42:21 -06001601 :term:`COPYLEFT_LICENSE_INCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001602 A space-separated list of licenses to include in the source archived
Andrew Geissler517393d2023-01-13 08:55:19 -06001603 by the :ref:`ref-classes-archiver` class. In other
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001604 words, if a license in a recipe's :term:`LICENSE`
Andrew Geissler09036742021-06-25 14:25:14 -05001605 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001606 source is archived by the class.
1607
Andrew Geissler517393d2023-01-13 08:55:19 -06001608 The default value is set by the :ref:`ref-classes-copyleft_filter` class,
1609 which is inherited by the :ref:`ref-classes-archiver` class. The default
1610 value includes "GPL*", "LGPL*", and "AGPL*".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001611
Andrew Geisslerf0343792020-11-18 10:42:21 -06001612 :term:`COPYLEFT_PN_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001613 A list of recipes to exclude in the source archived by the
Andrew Geissler517393d2023-01-13 08:55:19 -06001614 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE`
1615 variable overrides the license inclusion and exclusion caused through the
1616 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001617 variables, respectively.
1618
1619 The default value, which is "" indicating to not explicitly exclude
Andrew Geissler09036742021-06-25 14:25:14 -05001620 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the
Andrew Geissler517393d2023-01-13 08:55:19 -06001621 :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1622 :ref:`ref-classes-archiver` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001623
Andrew Geisslerf0343792020-11-18 10:42:21 -06001624 :term:`COPYLEFT_PN_INCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001625 A list of recipes to include in the source archived by the
Andrew Geissler517393d2023-01-13 08:55:19 -06001626 :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE`
1627 variable overrides the license inclusion and exclusion caused through the
1628 :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001629 variables, respectively.
1630
1631 The default value, which is "" indicating to not explicitly include
Andrew Geissler09036742021-06-25 14:25:14 -05001632 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the
Andrew Geissler517393d2023-01-13 08:55:19 -06001633 :ref:`ref-classes-copyleft_filter` class, which is inherited by the
1634 :ref:`ref-classes-archiver` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001635
Andrew Geisslerf0343792020-11-18 10:42:21 -06001636 :term:`COPYLEFT_RECIPE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001637 A space-separated list of recipe types to include in the source
1638 archived by the :ref:`archiver <ref-classes-archiver>` class.
Andrew Geissler517393d2023-01-13 08:55:19 -06001639 Recipe types are ``target``, :ref:`ref-classes-native`,
1640 :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`,
1641 :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001642
Andrew Geissler09036742021-06-25 14:25:14 -05001643 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES`
Andrew Geissler517393d2023-01-13 08:55:19 -06001644 is set by the :ref:`ref-classes-copyleft_filter` class, which is
1645 inherited by the :ref:`ref-classes-archiver` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001646
Andrew Geisslerf0343792020-11-18 10:42:21 -06001647 :term:`CORE_IMAGE_EXTRA_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001648 Specifies the list of packages to be added to the image. You should
1649 only set this variable in the ``local.conf`` configuration file found
1650 in the :term:`Build Directory`.
1651
1652 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
1653 supported.
1654
Andrew Geisslerf0343792020-11-18 10:42:21 -06001655 :term:`COREBASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001656 Specifies the parent directory of the OpenEmbedded-Core Metadata
1657 layer (i.e. ``meta``).
1658
Andrew Geissler09036742021-06-25 14:25:14 -05001659 It is an important distinction that :term:`COREBASE` points to the parent
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001660 of this layer and not the layer itself. Consider an example where you
1661 have cloned the Poky Git repository and retained the ``poky`` name
Andrew Geissler09036742021-06-25 14:25:14 -05001662 for your local copy of the repository. In this case, :term:`COREBASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001663 points to the ``poky`` folder because it is the parent directory of
1664 the ``poky/meta`` layer.
1665
Andrew Geisslerf0343792020-11-18 10:42:21 -06001666 :term:`COREBASE_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001667 Lists files from the :term:`COREBASE` directory that
1668 should be copied other than the layers listed in the
Andrew Geissler09036742021-06-25 14:25:14 -05001669 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001670 to copy metadata from the OpenEmbedded build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001671 into the extensible SDK.
1672
Andrew Geissler09036742021-06-25 14:25:14 -05001673 Explicitly listing files in :term:`COREBASE` is needed because it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001674 typically contains build directories and other files that should not
1675 normally be copied into the extensible SDK. Consequently, the value
Andrew Geissler09036742021-06-25 14:25:14 -05001676 of :term:`COREBASE_FILES` is used in order to only copy the files that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001677 are actually needed.
1678
Andrew Geisslerf0343792020-11-18 10:42:21 -06001679 :term:`CPP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001680 The minimal command and arguments used to run the C preprocessor.
1681
Andrew Geisslerf0343792020-11-18 10:42:21 -06001682 :term:`CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001683 Specifies the flags to pass to the C pre-processor (i.e. to both the
1684 C and the C++ compilers). This variable is exported to an environment
1685 variable and thus made visible to the software being built during the
1686 compilation step.
1687
Andrew Geissler09036742021-06-25 14:25:14 -05001688 Default initialization for :term:`CPPFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001689 being built:
1690
1691 - :term:`TARGET_CPPFLAGS` when building for
1692 the target
1693
1694 - :term:`BUILD_CPPFLAGS` when building for the
1695 build host (i.e. ``-native``)
1696
1697 - :term:`BUILDSDK_CPPFLAGS` when building
1698 for an SDK (i.e. ``nativesdk-``)
1699
Andrew Geisslerf0343792020-11-18 10:42:21 -06001700 :term:`CROSS_COMPILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001701 The toolchain binary prefix for the target tools. The
Andrew Geissler09036742021-06-25 14:25:14 -05001702 :term:`CROSS_COMPILE` variable is the same as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001703 :term:`TARGET_PREFIX` variable.
1704
1705 .. note::
1706
Andrew Geissler09036742021-06-25 14:25:14 -05001707 The OpenEmbedded build system sets the :term:`CROSS_COMPILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001708 variable only in certain contexts (e.g. when building for kernel
1709 and kernel module recipes).
1710
Patrick Williams84603582024-12-14 08:00:57 -05001711 :term:`CVE_CHECK_CREATE_MANIFEST`
1712 Specifies whether to create a CVE manifest to place in the deploy
1713 directory. The default is "1".
1714
Andrew Geissler9aee5002022-03-30 16:27:02 +00001715 :term:`CVE_CHECK_IGNORE`
Patrick Williams2a254922023-08-11 09:48:11 -05001716 This variable is deprecated and should be replaced by :term:`CVE_STATUS`.
Andrew Geissler9aee5002022-03-30 16:27:02 +00001717
Patrick Williams84603582024-12-14 08:00:57 -05001718 :term:`CVE_CHECK_MANIFEST_JSON`
1719 Specifies the path to the CVE manifest in JSON format. See
1720 :term:`CVE_CHECK_CREATE_MANIFEST`.
1721
1722 :term:`CVE_CHECK_MANIFEST_JSON_SUFFIX`
1723 Allows to modify the JSON manifest suffix. See
1724 :term:`CVE_CHECK_MANIFEST_JSON`.
1725
Andrew Geissleredff4922024-06-19 14:12:16 -04001726 :term:`CVE_CHECK_REPORT_PATCHED`
1727 Specifies whether or not the :ref:`ref-classes-cve-check`
1728 class should report patched or ignored CVEs. The default is "1", but you
1729 may wish to set it to "0" if you do not need patched or ignored CVEs in
1730 the logs.
1731
Patrick Williams975a06f2022-10-21 14:42:47 -05001732 :term:`CVE_CHECK_SHOW_WARNINGS`
Andrew Geissler517393d2023-01-13 08:55:19 -06001733 Specifies whether or not the :ref:`ref-classes-cve-check`
Patrick Williams975a06f2022-10-21 14:42:47 -05001734 class should generate warning messages on the console when unpatched
1735 CVEs are found. The default is "1", but you may wish to set it to "0" if
1736 you are already examining/processing the logs after the build has
1737 completed and thus do not need the warning messages.
1738
Andrew Geissler9aee5002022-03-30 16:27:02 +00001739 :term:`CVE_CHECK_SKIP_RECIPE`
1740 The list of package names (:term:`PN`) for which
1741 CVEs (Common Vulnerabilities and Exposures) are ignored.
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001742
Patrick Williams44b3caf2024-04-12 16:51:14 -05001743 :term:`CVE_DB_INCR_UPDATE_AGE_THRES`
1744 Specifies the maximum age of the CVE database in seconds for an
1745 incremental update (instead of a full-download). Use "0" to force a
1746 full-download.
1747
Patrick Williams975a06f2022-10-21 14:42:47 -05001748 :term:`CVE_DB_UPDATE_INTERVAL`
1749 Specifies the CVE database update interval in seconds, as used by
1750 ``cve-update-db-native``. The default value is "86400" i.e. once a day
1751 (24*60*60). If the value is set to "0" then the update will be forced
1752 every time. Alternatively, a negative value e.g. "-1" will disable
1753 updates entirely.
1754
Patrick Williams213cb262021-08-07 19:21:33 -05001755 :term:`CVE_PRODUCT`
1756 In a recipe, defines the name used to match the recipe name
1757 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
1758
Patrick Williams975a06f2022-10-21 14:42:47 -05001759 The default is ${:term:`BPN`} (except for recipes that inherit the
Andrew Geissler517393d2023-01-13 08:55:19 -06001760 :ref:`ref-classes-pypi` class where it is set based upon
Patrick Williams975a06f2022-10-21 14:42:47 -05001761 :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE
Patrick Williams213cb262021-08-07 19:21:33 -05001762 database or matches with multiple entries in the database, the default
1763 value needs to be changed.
1764
1765 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
1766
1767 CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
1768
Patrick Williams03907ee2022-05-01 06:28:52 -05001769 Sometimes the product name is not specific enough, for example
1770 "tar" has been matching CVEs for the GNU ``tar`` package and also
1771 the ``node-tar`` node.js extension. To avoid this problem, use the
1772 vendor name as a prefix. The syntax for this is::
1773
1774 CVE_PRODUCT = "vendor:package"
1775
Patrick Williams2a254922023-08-11 09:48:11 -05001776 :term:`CVE_STATUS`
1777 The CVE ID which is patched or should be ignored. Here is
1778 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
1779
1780 CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows"
1781
1782 It has the format "reason: description" and the description is optional.
1783 The Reason is mapped to the final CVE state by mapping via
Patrick Williamsac13d5f2023-11-24 18:59:46 -06001784 :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes`
1785 for details.
Patrick Williams2a254922023-08-11 09:48:11 -05001786
1787 :term:`CVE_STATUS_GROUPS`
1788 If there are many CVEs with the same status and reason, they can by simplified by using this
1789 variable instead of many similar lines with :term:`CVE_STATUS`::
1790
1791 CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED"
1792
1793 CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002"
1794 CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows"
1795 CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004"
1796 CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally"
1797
1798 :term:`CVE_CHECK_STATUSMAP`
1799 Mapping variable for all possible reasons of :term:`CVE_STATUS`:
1800 ``Patched``, ``Unpatched`` and ``Ignored``.
1801 See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details::
1802
1803 CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored"
1804
Patrick Williams2390b1b2022-11-03 13:47:49 -05001805 :term:`CVE_VERSION`
1806 In a recipe, defines the version used to match the recipe version
1807 against the version in the `NIST CVE database <https://nvd.nist.gov/>`__
Andrew Geissler517393d2023-01-13 08:55:19 -06001808 when usign :ref:`ref-classes-cve-check`.
Patrick Williams2390b1b2022-11-03 13:47:49 -05001809
1810 The default is ${:term:`PV`} but if recipes use custom version numbers
1811 which do not map to upstream software component release versions and the versions
1812 used in the CVE database, then this variable can be used to set the
Andrew Geissler517393d2023-01-13 08:55:19 -06001813 version number for :ref:`ref-classes-cve-check`. Example::
Patrick Williams2390b1b2022-11-03 13:47:49 -05001814
1815 CVE_VERSION = "2.39"
1816
Andrew Geisslerf0343792020-11-18 10:42:21 -06001817 :term:`CVSDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001818 The directory in which files checked out under the CVS system are
1819 stored.
1820
Andrew Geisslerf0343792020-11-18 10:42:21 -06001821 :term:`CXX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001822 The minimal command and arguments used to run the C++ compiler.
1823
Andrew Geisslerf0343792020-11-18 10:42:21 -06001824 :term:`CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001825 Specifies the flags to pass to the C++ compiler. This variable is
1826 exported to an environment variable and thus made visible to the
1827 software being built during the compilation step.
1828
Andrew Geissler09036742021-06-25 14:25:14 -05001829 Default initialization for :term:`CXXFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001830 being built:
1831
1832 - :term:`TARGET_CXXFLAGS` when building for
1833 the target
1834
1835 - :term:`BUILD_CXXFLAGS` when building for the
1836 build host (i.e. ``-native``)
1837
1838 - :term:`BUILDSDK_CXXFLAGS` when building
1839 for an SDK (i.e. ``nativesdk-``)
1840
Andrew Geisslerf0343792020-11-18 10:42:21 -06001841 :term:`D`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001842 The destination directory. The location in the :term:`Build Directory`
1843 where components are installed by the
1844 :ref:`ref-tasks-install` task. This location defaults
Andrew Geisslerc926e172021-05-07 16:11:35 -05001845 to::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001846
1847 ${WORKDIR}/image
1848
1849 .. note::
1850
1851 Tasks that read from or write to this directory should run under
Andrew Geissler09209ee2020-12-13 08:44:15 -06001852 :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001853
Andrew Geisslerf0343792020-11-18 10:42:21 -06001854 :term:`DATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001855 The date the build was started. Dates appear using the year, month,
1856 and day (YMD) format (e.g. "20150209" for February 9th, 2015).
1857
Andrew Geisslerf0343792020-11-18 10:42:21 -06001858 :term:`DATETIME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001859 The date and time on which the current build started. The format is
1860 suitable for timestamps.
1861
Andrew Geisslerf0343792020-11-18 10:42:21 -06001862 :term:`DEBIAN_NOAUTONAME`
Andrew Geissler517393d2023-01-13 08:55:19 -06001863 When the :ref:`ref-classes-debian` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -05001864 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001865 particular package should not be renamed according to Debian library
1866 package naming. You must use the package name as an override when you
Andrew Geisslerc926e172021-05-07 16:11:35 -05001867 set this variable. Here is an example from the ``fontconfig`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001868
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001869 DEBIAN_NOAUTONAME:fontconfig-utils = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001870
Andrew Geisslerf0343792020-11-18 10:42:21 -06001871 :term:`DEBIANNAME`
Andrew Geissler517393d2023-01-13 08:55:19 -06001872 When the :ref:`ref-classes-debian` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -05001873 which is the default behavior, :term:`DEBIANNAME` allows you to override
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001874 the library name for an individual package. Overriding the library
1875 name in these cases is rare. You must use the package name as an
1876 override when you set this variable. Here is an example from the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001877 ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001878
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001879 DEBIANNAME:${PN} = "dbus-1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001880
Andrew Geisslerf0343792020-11-18 10:42:21 -06001881 :term:`DEBUG_BUILD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001882 Specifies to build packages with debugging information. This
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001883 influences the value of the :term:`SELECTED_OPTIMIZATION` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001884
Andrew Geisslerf0343792020-11-18 10:42:21 -06001885 :term:`DEBUG_OPTIMIZATION`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001886 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001887 compiling a system for debugging. This variable defaults to "-O
1888 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1889
Andrew Geisslereff27472021-10-29 15:35:00 -05001890 :term:`DEBUG_PREFIX_MAP`
1891 Allows to set C compiler options, such as ``-fdebug-prefix-map``,
1892 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to
1893 replace build-time paths by install-time ones in the debugging sections
1894 of binaries. This makes compiler output files location independent,
1895 at the cost of having to pass an extra command to tell the debugger
1896 where source files are.
1897
1898 This is used by the Yocto Project to guarantee
1899 :doc:`/test-manual/reproducible-builds` even when the source code of
1900 a package uses the ``__FILE__`` or ``assert()`` macros. See the
1901 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__
1902 website for details.
1903
1904 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1905 not intended to be user-configurable.
1906
Andrew Geissler9aee5002022-03-30 16:27:02 +00001907 :term:`DEFAULT_PREFERENCE`
1908 Specifies a weak bias for recipe selection priority.
1909
1910 The most common usage of this is variable is to set it to "-1" within
1911 a recipe for a development version of a piece of software. Using the
1912 variable in this way causes the stable version of the recipe to build
1913 by default in the absence of :term:`PREFERRED_VERSION` being used to
1914 build the development version.
1915
1916 .. note::
1917
1918 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden
1919 by :term:`BBFILE_PRIORITY` if that variable is different between two
1920 layers that contain different versions of the same recipe.
1921
Patrick Williams84603582024-12-14 08:00:57 -05001922 :term:`DEFAULT_TIMEZONE`
1923 Specifies the time zone set in the image.
1924
1925 This variable causes the ``tzdata`` package to configure
1926 ``${sysconfdir}/localtime`` accordingly. Valid values are all files
1927 found in ``/usr/share/zoneinfo`` like ``CET`` or ``Asia/Baku``.
1928
Andrew Geisslerf0343792020-11-18 10:42:21 -06001929 :term:`DEFAULTTUNE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001930 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1931 the "tune") used by the OpenEmbedded build system. The
Andrew Geissler09036742021-06-25 14:25:14 -05001932 :term:`DEFAULTTUNE` helps define
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001933 :term:`TUNE_FEATURES`.
1934
1935 The default tune is either implicitly or explicitly set by the
1936 machine (:term:`MACHINE`). However, you can override
1937 the setting using available tunes as defined with
1938 :term:`AVAILTUNES`.
1939
Andrew Geisslerf0343792020-11-18 10:42:21 -06001940 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001941 Lists a recipe's build-time dependencies. These are dependencies on
1942 other recipes whose contents (e.g. headers and shared libraries) are
1943 needed by the recipe at build time.
1944
1945 As an example, consider a recipe ``foo`` that contains the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001946 assignment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001947
1948 DEPENDS = "bar"
1949
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05001950 The practical effect of the previous assignment is that all files
1951 installed by bar will be available in the appropriate staging sysroot,
1952 given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time
1953 the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is
1954 implemented by having :ref:`ref-tasks-configure` depend on the
1955 :ref:`ref-tasks-populate_sysroot` task of each recipe listed in
1956 :term:`DEPENDS`, through a
1957 ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
Andrew Geissler517393d2023-01-13 08:55:19 -06001958 declaration in the :ref:`ref-classes-base` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001959
1960 .. note::
1961
Andrew Geissler09036742021-06-25 14:25:14 -05001962 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001963 explicitly. The standard classes and build-related variables are
1964 configured to automatically use the appropriate staging sysroots.
1965
Andrew Geissler09036742021-06-25 14:25:14 -05001966 As another example, :term:`DEPENDS` can also be used to add utilities
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001967 that run on the build machine during the build. For example, a recipe
1968 that makes use of a code generator built by the recipe ``codegen``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001969 might have the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001970
1971 DEPENDS = "codegen-native"
1972
1973 For more
Andrew Geissler517393d2023-01-13 08:55:19 -06001974 information, see the :ref:`ref-classes-native` class and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001975 the :term:`EXTRANATIVEPATH` variable.
1976
1977 .. note::
1978
Andrew Geissler09036742021-06-25 14:25:14 -05001979 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001980 it is a list of :term:`PROVIDES` names, which
1981 usually match recipe names. Putting a package name such as
Andrew Geissler09036742021-06-25 14:25:14 -05001982 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001983 instead, as this will put files from all the packages that make
1984 up ``foo``, which includes those from ``foo-dev``, into the
1985 sysroot.
1986
Andrew Geissler09036742021-06-25 14:25:14 -05001987 - One recipe having another recipe in :term:`DEPENDS` does not by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001988 itself add any runtime dependencies between the packages
1989 produced by the two recipes. However, as explained in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001990 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001991 section in the Yocto Project Overview and Concepts Manual,
1992 runtime dependencies will often be added automatically, meaning
Andrew Geissler5f350902021-07-23 13:09:54 -04001993 :term:`DEPENDS` alone is sufficient for most recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001994
Andrew Geissler09036742021-06-25 14:25:14 -05001995 - Counterintuitively, :term:`DEPENDS` is often necessary even for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001996 recipes that install precompiled components. For example, if
1997 ``libfoo`` is a precompiled library that links against
1998 ``libbar``, then linking against ``libfoo`` requires both
1999 ``libfoo`` and ``libbar`` to be available in the sysroot.
Andrew Geissler09036742021-06-25 14:25:14 -05002000 Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002001 to the recipe that installs ``libbar``, other recipes might
2002 fail to link against ``libfoo``.
2003
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05002004 For information on runtime dependencies, see the :term:`RDEPENDS`
2005 variable. You can also see the
2006 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
2007 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`"
2008 sections in the BitBake User Manual for additional information on tasks
2009 and dependencies.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002010
Andrew Geisslerf0343792020-11-18 10:42:21 -06002011 :term:`DEPLOY_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002012 Points to the general area that the OpenEmbedded build system uses to
2013 place images, packages, SDKs, and other output files that are ready
2014 to be used outside of the build system. By default, this directory
Patrick Williams2390b1b2022-11-03 13:47:49 -05002015 resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002016
2017 For more information on the structure of the Build Directory, see
Andrew Geissler615f2f12022-07-15 14:00:58 -05002018 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002019 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002020 ":ref:`overview-manual/concepts:images`",
2021 ":ref:`overview-manual/concepts:package feeds`", and
2022 ":ref:`overview-manual/concepts:application development sdk`" sections all in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002023 Yocto Project Overview and Concepts Manual.
2024
Andrew Geisslerf0343792020-11-18 10:42:21 -06002025 :term:`DEPLOY_DIR_DEB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002026 Points to the area that the OpenEmbedded build system uses to place
2027 Debian packages that are ready to be used outside of the build
Andrew Geissler517393d2023-01-13 08:55:19 -06002028 system. This variable applies only when :term:`PACKAGE_CLASSES` contains
2029 ":ref:`ref-classes-package_deb`".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002030
2031 The BitBake configuration file initially defines the
Andrew Geissler5f350902021-07-23 13:09:54 -04002032 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of
Andrew Geisslerc926e172021-05-07 16:11:35 -05002033 :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002034
2035 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
2036
Andrew Geissler517393d2023-01-13 08:55:19 -06002037 The :ref:`ref-classes-package_deb` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05002038 :term:`DEPLOY_DIR_DEB` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002039 :ref:`ref-tasks-package_write_deb` task
2040 writes Debian packages into the appropriate folder. For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06002041 information on how packaging works, see the
2042 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002043 in the Yocto Project Overview and Concepts Manual.
2044
Andrew Geisslerf0343792020-11-18 10:42:21 -06002045 :term:`DEPLOY_DIR_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002046 Points to the area that the OpenEmbedded build system uses to place
2047 images and other associated output files that are ready to be
2048 deployed onto the target machine. The directory is machine-specific
2049 as it contains the ``${MACHINE}`` name. By default, this directory
2050 resides within the :term:`Build Directory` as
2051 ``${DEPLOY_DIR}/images/${MACHINE}/``.
2052
Andrew Geissler09036742021-06-25 14:25:14 -05002053 It must not be used directly in recipes when deploying files. Instead,
2054 it's only useful when a recipe needs to "read" a file already deployed
2055 by a dependency. So, it should be filled with the contents of
Andrew Geissler517393d2023-01-13 08:55:19 -06002056 :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the
2057 contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class.
Andrew Geissler09036742021-06-25 14:25:14 -05002058
Patrick Williams2390b1b2022-11-03 13:47:49 -05002059 For more information on the structure of the :term:`Build Directory`, see
Andrew Geissler615f2f12022-07-15 14:00:58 -05002060 ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002061 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002062 ":ref:`overview-manual/concepts:images`" and
2063 ":ref:`overview-manual/concepts:application development sdk`" sections both in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002064 the Yocto Project Overview and Concepts Manual.
2065
Andrew Geisslerf0343792020-11-18 10:42:21 -06002066 :term:`DEPLOY_DIR_IPK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002067 Points to the area that the OpenEmbedded build system uses to place
2068 IPK packages that are ready to be used outside of the build system.
Andrew Geissler517393d2023-01-13 08:55:19 -06002069 This variable applies only when :term:`PACKAGE_CLASSES` contains
2070 ":ref:`ref-classes-package_ipk`".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002071
2072 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002073 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002074
2075 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
2076
Andrew Geissler517393d2023-01-13 08:55:19 -06002077 The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK`
2078 variable to make sure the :ref:`ref-tasks-package_write_ipk` task
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002079 writes IPK packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06002080 on how packaging works, see the
2081 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002082 in the Yocto Project Overview and Concepts Manual.
2083
Andrew Geisslerf0343792020-11-18 10:42:21 -06002084 :term:`DEPLOY_DIR_RPM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002085 Points to the area that the OpenEmbedded build system uses to place
2086 RPM packages that are ready to be used outside of the build system.
Andrew Geissler517393d2023-01-13 08:55:19 -06002087 This variable applies only when :term:`PACKAGE_CLASSES` contains
2088 ":ref:`ref-classes-package_rpm`".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002089
2090 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002091 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002092
2093 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
2094
Andrew Geissler517393d2023-01-13 08:55:19 -06002095 The :ref:`ref-classes-package_rpm` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05002096 :term:`DEPLOY_DIR_RPM` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002097 :ref:`ref-tasks-package_write_rpm` task
2098 writes RPM packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06002099 on how packaging works, see the
2100 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002101 in the Yocto Project Overview and Concepts Manual.
2102
Andrew Geisslerf0343792020-11-18 10:42:21 -06002103 :term:`DEPLOYDIR`
Andrew Geissler517393d2023-01-13 08:55:19 -06002104 When inheriting the :ref:`ref-classes-deploy` class, the
Andrew Geissler09036742021-06-25 14:25:14 -05002105 :term:`DEPLOYDIR` points to a temporary work area for deployed files that
Andrew Geissler517393d2023-01-13 08:55:19 -06002106 is set in the :ref:`ref-classes-deploy` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002107
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002108 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002109
Andrew Geissler517393d2023-01-13 08:55:19 -06002110 Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be
Andrew Geissler09036742021-06-25 14:25:14 -05002111 deployed into :term:`DEPLOYDIR`, and the class will take care of copying
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002112 them into :term:`DEPLOY_DIR_IMAGE`
2113 afterwards.
2114
Andrew Geisslerf0343792020-11-18 10:42:21 -06002115 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002116 The package description used by package managers. If not set,
Andrew Geissler09036742021-06-25 14:25:14 -05002117 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002118 variable.
2119
Patrick Williams975a06f2022-10-21 14:42:47 -05002120 :term:`DEV_PKG_DEPENDENCY`
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06002121 Provides an easy way for recipes to disable or adjust the runtime recommendation
2122 (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main
2123 (``${PN}``) package.
Patrick Williams975a06f2022-10-21 14:42:47 -05002124
2125 :term:`DISABLE_STATIC`
2126 Used in order to disable static linking by default (in order to save
2127 space, since static libraries are often unused in embedded systems.)
2128 The default value is " --disable-static", however it can be set to ""
2129 in order to enable static linking if desired. Certain recipes do this
2130 individually, and also there is a
2131 ``meta/conf/distro/include/no-static-libs.inc`` include file that
2132 disables static linking for a number of recipes. Some software
2133 packages or build tools (such as CMake) have explicit support for
2134 enabling / disabling static linking, and in those cases
2135 :term:`DISABLE_STATIC` is not used.
2136
Andrew Geisslerf0343792020-11-18 10:42:21 -06002137 :term:`DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002138 The short name of the distribution. For information on the long name
2139 of the distribution, see the :term:`DISTRO_NAME`
2140 variable.
2141
Andrew Geissler09036742021-06-25 14:25:14 -05002142 The :term:`DISTRO` variable corresponds to a distribution configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002143 file whose root name is the same as the variable's argument and whose
2144 filename extension is ``.conf``. For example, the distribution
2145 configuration file for the Poky distribution is named ``poky.conf``
2146 and resides in the ``meta-poky/conf/distro`` directory of the
2147 :term:`Source Directory`.
2148
Andrew Geissler09036742021-06-25 14:25:14 -05002149 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05002150 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002151
2152 DISTRO = "poky"
2153
2154 Distribution configuration files are located in a ``conf/distro``
2155 directory within the :term:`Metadata` that contains the
Andrew Geissler09036742021-06-25 14:25:14 -05002156 distribution configuration. The value for :term:`DISTRO` must not contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002157 spaces, and is typically all lower-case.
2158
2159 .. note::
2160
Andrew Geissler09036742021-06-25 14:25:14 -05002161 If the :term:`DISTRO` variable is blank, a set of default configurations
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002162 are used, which are specified within
2163 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002164
Andrew Geisslerf0343792020-11-18 10:42:21 -06002165 :term:`DISTRO_CODENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002166 Specifies a codename for the distribution being built.
2167
Andrew Geisslerf0343792020-11-18 10:42:21 -06002168 :term:`DISTRO_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002169 Specifies a list of distro-specific packages to add to all images.
Andrew Geissler595f6302022-01-24 19:11:47 +00002170 This variable takes effect through ``packagegroup-base`` so the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002171 variable only really applies to the more full-featured images that
2172 include ``packagegroup-base``. You can use this variable to keep
2173 distro policy out of generic images. As with all other distro
2174 variables, you set this variable in the distro ``.conf`` file.
2175
Andrew Geisslerf0343792020-11-18 10:42:21 -06002176 :term:`DISTRO_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002177 Specifies a list of distro-specific packages to add to all images if
2178 the packages exist. The packages might not exist or be empty (e.g.
2179 kernel modules). The list of packages are automatically installed but
2180 you can remove them.
2181
Andrew Geisslerf0343792020-11-18 10:42:21 -06002182 :term:`DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002183 The software support you want in your distribution for various
2184 features. You define your distribution features in the distribution
2185 configuration file.
2186
2187 In most cases, the presence or absence of a feature in
Andrew Geissler09036742021-06-25 14:25:14 -05002188 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002189 to the configure script during the
2190 :ref:`ref-tasks-configure` task for recipes that
2191 optionally support the feature. For example, specifying "x11" in
Andrew Geissler09036742021-06-25 14:25:14 -05002192 :term:`DISTRO_FEATURES`, causes every piece of software built for the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002193 target that can optionally support X11 to have its X11 support
Patrick Williamsdb4c27e2022-08-05 08:10:29 -05002194 enabled.
2195
2196 .. note::
2197
2198 Just enabling :term:`DISTRO_FEATURES` alone doesn't
2199 enable feature support for packages. Mechanisms such as making
2200 :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used
2201 to enable/disable package features.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002202
2203 Two more examples are Bluetooth and NFS support. For a more complete
2204 list of features that ships with the Yocto Project and that you can
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002205 provide with this variable, see the ":ref:`ref-features-distro`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002206
Andrew Geisslerf0343792020-11-18 10:42:21 -06002207 :term:`DISTRO_FEATURES_BACKFILL`
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05002208 A space-separated list of features to be added to :term:`DISTRO_FEATURES`
2209 if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002210
2211 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
2212 not intended to be user-configurable. It is best to just reference
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05002213 the variable to see which distro features are being
2214 :ref:`backfilled <ref-features-backfill>` for all distro configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002215
Andrew Geisslerf0343792020-11-18 10:42:21 -06002216 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05002217 A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL`
2218 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
2219 to :term:`DISTRO_FEATURES`) during the build.
2220
2221 This corresponds to an opt-out mechanism. When new default distro
2222 features are introduced, distribution maintainers can review (`consider`)
2223 them and decide to exclude them from the
2224 :ref:`backfilled <ref-features-backfill>` features. Therefore, the
2225 combination of :term:`DISTRO_FEATURES_BACKFILL` and
2226 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to
2227 add new default features without breaking existing distributions.
2228
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002229
Andrew Geisslerf0343792020-11-18 10:42:21 -06002230 :term:`DISTRO_FEATURES_DEFAULT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002231 A convenience variable that gives you the default list of distro
2232 features with the exception of any features specific to the C library
2233 (``libc``).
2234
2235 When creating a custom distribution, you might find it useful to be
2236 able to reuse the default
2237 :term:`DISTRO_FEATURES` options without the
2238 need to write out the full set. Here is an example that uses
Andrew Geissler09036742021-06-25 14:25:14 -05002239 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002240
2241 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
2242
Andrew Geisslerf0343792020-11-18 10:42:21 -06002243 :term:`DISTRO_FEATURES_FILTER_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002244 Specifies a list of features that if present in the target
2245 :term:`DISTRO_FEATURES` value should be
Andrew Geissler09036742021-06-25 14:25:14 -05002246 included in :term:`DISTRO_FEATURES` when building native recipes. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002247 variable is used in addition to the features filtered using the
2248 :term:`DISTRO_FEATURES_NATIVE`
2249 variable.
2250
Andrew Geisslerf0343792020-11-18 10:42:21 -06002251 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002252 Specifies a list of features that if present in the target
Andrew Geissler517393d2023-01-13 08:55:19 -06002253 :term:`DISTRO_FEATURES` value should be included in
2254 :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk`
2255 recipes. This variable is used in addition to the features filtered using
2256 the :term:`DISTRO_FEATURES_NATIVESDK` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002257
Andrew Geisslerf0343792020-11-18 10:42:21 -06002258 :term:`DISTRO_FEATURES_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002259 Specifies a list of features that should be included in
2260 :term:`DISTRO_FEATURES` when building native
2261 recipes. This variable is used in addition to the features filtered
2262 using the
2263 :term:`DISTRO_FEATURES_FILTER_NATIVE`
2264 variable.
2265
Andrew Geisslerf0343792020-11-18 10:42:21 -06002266 :term:`DISTRO_FEATURES_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002267 Specifies a list of features that should be included in
2268 :term:`DISTRO_FEATURES` when building
Andrew Geissler517393d2023-01-13 08:55:19 -06002269 :ref:`ref-classes-nativesdk` recipes. This variable is used
2270 in addition to the features filtered using the
2271 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002272
Andrew Geisslerf0343792020-11-18 10:42:21 -06002273 :term:`DISTRO_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002274 The long name of the distribution. For information on the short name
2275 of the distribution, see the :term:`DISTRO` variable.
2276
Andrew Geissler09036742021-06-25 14:25:14 -05002277 The :term:`DISTRO_NAME` variable corresponds to a distribution
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002278 configuration file whose root name is the same as the variable's
2279 argument and whose filename extension is ``.conf``. For example, the
2280 distribution configuration file for the Poky distribution is named
2281 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
2282 of the :term:`Source Directory`.
2283
Andrew Geissler09036742021-06-25 14:25:14 -05002284 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
Andrew Geisslerc926e172021-05-07 16:11:35 -05002285 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002286
2287 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
2288
2289 Distribution configuration files are located in a ``conf/distro``
2290 directory within the :term:`Metadata` that contains the
2291 distribution configuration.
2292
2293 .. note::
2294
Andrew Geissler09036742021-06-25 14:25:14 -05002295 If the :term:`DISTRO_NAME` variable is blank, a set of default
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002296 configurations are used, which are specified within
2297 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002298
Andrew Geisslerf0343792020-11-18 10:42:21 -06002299 :term:`DISTRO_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002300 The version of the distribution.
2301
Andrew Geisslerf0343792020-11-18 10:42:21 -06002302 :term:`DISTROOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002303 A colon-separated list of overrides specific to the current
2304 distribution. By default, this list includes the value of
2305 :term:`DISTRO`.
2306
Andrew Geissler09036742021-06-25 14:25:14 -05002307 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002308 apply to the distribution.
2309
Andrew Geissler09036742021-06-25 14:25:14 -05002310 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002311 is included in the default value of
2312 :term:`OVERRIDES`.
2313
Patrick Williams520786c2023-06-25 16:20:36 -05002314 Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf
2315 </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`::
2316
2317 DISTROOVERRIDES = "poky:poky-tiny"
2318
Andrew Geisslerf0343792020-11-18 10:42:21 -06002319 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002320 The central download directory used by the build process to store
Andrew Geissler09036742021-06-25 14:25:14 -05002321 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002322 for everything except Git repositories. If you want tarballs of Git
2323 repositories, use the
2324 :term:`BB_GENERATE_MIRROR_TARBALLS`
2325 variable.
2326
Andrew Geissler09036742021-06-25 14:25:14 -05002327 You can set this directory by defining the :term:`DL_DIR` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002328 ``conf/local.conf`` file. This directory is self-maintaining and you
2329 should not have to touch it. By default, the directory is
Patrick Williams2390b1b2022-11-03 13:47:49 -05002330 ``downloads`` in the :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002331
2332 #DL_DIR ?= "${TOPDIR}/downloads"
2333
2334 To specify a different download directory,
2335 simply remove the comment from the line and provide your directory.
2336
2337 During a first build, the system downloads many different source code
2338 tarballs from various upstream projects. Downloading can take a
2339 while, particularly if your network connection is slow. Tarballs are
Andrew Geissler09036742021-06-25 14:25:14 -05002340 all stored in the directory defined by :term:`DL_DIR` and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002341 system looks there first to find source tarballs.
2342
2343 .. note::
2344
2345 When wiping and rebuilding, you can preserve this directory to
2346 speed up this part of subsequent builds.
2347
2348 You can safely share this directory between multiple builds on the
2349 same development machine. For additional information on how the build
2350 process gets source files when working behind a firewall or proxy
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002351 server, see this specific question in the ":doc:`faq`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002352 chapter. You can also refer to the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002353 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002354 Wiki page.
2355
Andrew Geisslerf0343792020-11-18 10:42:21 -06002356 :term:`DOC_COMPRESS`
Andrew Geissler517393d2023-01-13 08:55:19 -06002357 When inheriting the :ref:`ref-classes-compress_doc`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002358 class, this variable sets the compression policy used when the
Patrick Williams03514f12024-04-05 07:04:11 -05002359 OpenEmbedded build system compresses manual and info pages. By
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002360 default, the compression method used is gz (gzip). Other policies
2361 available are xz and bz2.
2362
2363 For information on policies and on how to use this variable, see the
Patrick Williams975a06f2022-10-21 14:42:47 -05002364 comments in the ``meta/classes-recipe/compress_doc.bbclass`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002365
Patrick Williamsb542dec2023-06-09 01:26:37 -05002366 :term:`DT_FILES`
2367 Space-separated list of device tree source files to compile using
2368 a recipe that inherits the :ref:`ref-classes-devicetree` class. These
2369 are relative to the :term:`DT_FILES_PATH`.
2370
2371 For convenience, both ``.dts`` and ``.dtb`` extensions can be used.
2372
2373 Use an empty string (default) to build all device tree sources within
2374 the :term:`DT_FILES_PATH` directory.
2375
2376 :term:`DT_FILES_PATH`
2377 When compiling out-of-tree device tree sources using a recipe that
2378 inherits the :ref:`ref-classes-devicetree` class, this variable specifies
2379 the path to the directory containing dts files to build.
2380
2381 Defaults to the :term:`S` directory.
2382
2383 :term:`DT_PADDING_SIZE`
2384 When inheriting the :ref:`ref-classes-devicetree` class, this variable
2385 specifies the size of padding appended to the device tree blob, used as
2386 extra space typically for additional properties during boot.
2387
Patrick Williams84603582024-12-14 08:00:57 -05002388 :term:`EFI_ARCH`
2389 The CPU architecture name within EFI standard. Set in
2390 :oe_git:`meta/conf/image-uefi.conf
2391 <openembedded-core/tree/meta/conf/image-uefi.conf>`.
2392
Andrew Geisslerf0343792020-11-18 10:42:21 -06002393 :term:`EFI_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002394 When building bootable images (i.e. where ``hddimg``, ``iso``, or
2395 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
Andrew Geissler09036742021-06-25 14:25:14 -05002396 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002397 default is "grub-efi", but "systemd-boot" can be used instead.
2398
Andrew Geissler517393d2023-01-13 08:55:19 -06002399 See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live`
2400 classes for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002401
Patrick Williams44b3caf2024-04-12 16:51:14 -05002402 :term:`EFI_UKI_DIR`
2403 The primary place for the UKI image inside the EFI System Partition.
2404
2405 :term:`EFI_UKI_PATH`
2406 The path for the UKI image inside the root filesystem.
2407
Andrew Geisslerf0343792020-11-18 10:42:21 -06002408 :term:`ENABLE_BINARY_LOCALE_GENERATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002409 Variable that controls which locales for ``glibc`` are generated
2410 during the build (useful if the target device has 64Mbytes of RAM or
2411 less).
2412
Andrew Geisslerf0343792020-11-18 10:42:21 -06002413 :term:`ERR_REPORT_DIR`
Andrew Geissler517393d2023-01-13 08:55:19 -06002414 When used with the :ref:`ref-classes-report-error` class, specifies the
2415 path used for storing the debug files created by the :ref:`error reporting
2416 tool <dev-manual/error-reporting-tool:using the error reporting tool>`,
2417 which allows you to submit build errors you encounter to a central
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002418 database. By default, the value of this variable is
2419 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2420
Andrew Geissler09036742021-06-25 14:25:14 -05002421 You can set :term:`ERR_REPORT_DIR` to the path you want the error
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002422 reporting tool to store the debug files as follows in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05002423 ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002424
2425 ERR_REPORT_DIR = "path"
2426
Andrew Geisslerf0343792020-11-18 10:42:21 -06002427 :term:`ERROR_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002428 Specifies the quality assurance checks whose failures are reported as
2429 errors by the OpenEmbedded build system. You set this variable in
2430 your distribution configuration file. For a list of the checks you
2431 can control with this variable, see the
Andrew Geissler595f6302022-01-24 19:11:47 +00002432 ":ref:`ref-classes-insane`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002433
Andrew Geissler9aee5002022-03-30 16:27:02 +00002434 :term:`ESDK_CLASS_INHERIT_DISABLE`
2435 A list of classes to remove from the :term:`INHERIT`
2436 value globally within the extensible SDK configuration. The
2437 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
2438 default value::
2439
2440 ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc"
2441
2442 Some classes are not generally applicable within the extensible SDK
2443 context. You can use this variable to disable those classes.
2444
2445 For additional information on how to customize the extensible SDK's
2446 configuration, see the
2447 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2448 section in the Yocto Project Application Development and the
2449 Extensible Software Development Kit (eSDK) manual.
2450
2451 :term:`ESDK_LOCALCONF_ALLOW`
2452 A list of variables allowed through from the OpenEmbedded build
2453 system configuration into the extensible SDK configuration. By
2454 default, the list of variables is empty and is set in the
2455 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
2456
2457 This list overrides the variables specified using the
2458 :term:`ESDK_LOCALCONF_REMOVE` variable as well as
2459 other variables automatically added due to the "/" character
2460 being found at the start of the
2461 value, which is usually indicative of being a path and thus might not
2462 be valid on the system where the SDK is installed.
2463
2464 For additional information on how to customize the extensible SDK's
2465 configuration, see the
2466 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2467 section in the Yocto Project Application Development and the
2468 Extensible Software Development Kit (eSDK) manual.
2469
2470 :term:`ESDK_LOCALCONF_REMOVE`
2471 A list of variables not allowed through from the OpenEmbedded build
2472 system configuration into the extensible SDK configuration. Usually,
2473 these are variables that are specific to the machine on which the
2474 build system is running and thus would be potentially problematic
2475 within the extensible SDK.
2476
2477 By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the
2478 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
2479 excludes the following variables:
2480
2481 - :term:`CONF_VERSION`
2482 - :term:`BB_NUMBER_THREADS`
2483 - :term:`BB_NUMBER_PARSE_THREADS`
2484 - :term:`PARALLEL_MAKE`
2485 - :term:`PRSERV_HOST`
2486 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
2487 - :term:`SSTATE_DIR` :term:`TMPDIR`
2488 - :term:`BB_SERVER_TIMEOUT`
2489
2490 For additional information on how to customize the extensible SDK's
2491 configuration, see the
2492 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
2493 section in the Yocto Project Application Development and the
2494 Extensible Software Development Kit (eSDK) manual.
2495
Andrew Geisslerf0343792020-11-18 10:42:21 -06002496 :term:`EXCLUDE_FROM_SHLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002497 Triggers the OpenEmbedded build system's shared libraries resolver to
2498 exclude an entire package when scanning for shared libraries.
2499
2500 .. note::
2501
2502 The shared libraries resolver's functionality results in part from
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002503 the internal function ``package_do_shlibs``, which is part of the
2504 :ref:`ref-tasks-package` task. You should be aware that the shared
2505 libraries resolver might implicitly define some dependencies between
2506 packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002507
Andrew Geissler09036742021-06-25 14:25:14 -05002508 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002509 :term:`PRIVATE_LIBS` variable, which excludes a
2510 package's particular libraries only and not the whole package.
2511
Andrew Geissler09036742021-06-25 14:25:14 -05002512 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002513 particular package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002514
2515 EXCLUDE_FROM_SHLIBS = "1"
2516
Andrew Geisslerf0343792020-11-18 10:42:21 -06002517 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002518 Directs BitBake to exclude a recipe from world builds (i.e.
2519 ``bitbake world``). During world builds, BitBake locates, parses and
2520 builds all recipes found in every layer exposed in the
2521 ``bblayers.conf`` configuration file.
2522
2523 To exclude a recipe from a world build using this variable, set the
2524 variable to "1" in the recipe.
2525
2526 .. note::
2527
Andrew Geissler09036742021-06-25 14:25:14 -05002528 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002529 world build in order to satisfy dependencies of other recipes. Adding
Andrew Geissler09036742021-06-25 14:25:14 -05002530 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002531 explicitly added to the list of build targets in a world build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002532
Andrew Geisslerf0343792020-11-18 10:42:21 -06002533 :term:`EXTENDPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002534 Used with file and pathnames to create a prefix for a recipe's
Andrew Geissler09036742021-06-25 14:25:14 -05002535 version based on the recipe's :term:`PE` value. If :term:`PE`
2536 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
2537 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
2538 If a recipe's :term:`PE` is not set (the default) or is equal to zero,
2539 :term:`EXTENDPE` becomes "".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002540
2541 See the :term:`STAMP` variable for an example.
2542
Andrew Geisslerf0343792020-11-18 10:42:21 -06002543 :term:`EXTENDPKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002544 The full package version specification as it appears on the final
2545 packages produced by a recipe. The variable's value is normally used
2546 to fix a runtime dependency to the exact same version of another
Andrew Geisslerc926e172021-05-07 16:11:35 -05002547 package in the same recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002548
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002549 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002550
2551 The dependency relationships are intended to force the package
2552 manager to upgrade these types of packages in lock-step.
2553
Andrew Geisslerf0343792020-11-18 10:42:21 -06002554 :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geissler09036742021-06-25 14:25:14 -05002555 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002556 tools are not in the source tree.
2557
2558 When kernel tools are available in the tree, they are preferred over
Andrew Geissler09036742021-06-25 14:25:14 -05002559 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002560 variable tells the OpenEmbedded build system to prefer the installed
Andrew Geissler517393d2023-01-13 08:55:19 -06002561 external tools. See the :ref:`ref-classes-kernel-yocto` class in
Patrick Williams975a06f2022-10-21 14:42:47 -05002562 ``meta/classes-recipe`` to see how the variable is used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002563
Patrick Williams84603582024-12-14 08:00:57 -05002564 :term:`EXTERNAL_KERNEL_DEVICETREE`
2565 When inheriting :ref:`ref-classes-kernel-fitimage` and a
2566 :term:`PREFERRED_PROVIDER` for ``virtual/dtb`` set to ``devicetree``, the
2567 variable :term:`EXTERNAL_KERNEL_DEVICETREE` can be used to specify a
2568 directory containing one or more compiled device tree or device tree
2569 overlays to use.
2570
Patrick Williamsac13d5f2023-11-24 18:59:46 -06002571 :term:`KERNEL_LOCALVERSION`
2572 This variable allows to append a string to the version
2573 of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION``
2574 kernel configuration parameter.
2575
2576 Using this variable is only useful when you are using a kernel recipe
2577 inheriting the :ref:`ref-classes-kernel` class, and which doesn't
2578 already set a local version. Therefore, setting this variable has no
2579 impact on ``linux-yocto`` kernels.
2580
Andrew Geissler517393d2023-01-13 08:55:19 -06002581 :term:`EXTERNAL_TOOLCHAIN`
2582 When you intend to use an
2583 :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`,
2584 this variable allows to specify the directory where this toolchain was
2585 installed.
2586
Andrew Geisslerf0343792020-11-18 10:42:21 -06002587 :term:`EXTERNALSRC`
Andrew Geissler517393d2023-01-13 08:55:19 -06002588 When inheriting the :ref:`ref-classes-externalsrc`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002589 class, this variable points to the source tree, which is outside of
2590 the OpenEmbedded build system. When set, this variable sets the
2591 :term:`S` variable, which is what the OpenEmbedded build
2592 system uses to locate unpacked recipe source code.
2593
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00002594 See the ":ref:`ref-classes-externalsrc`" section for details. You
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002595 can also find information on how to use this variable in the
Andrew Geissler517393d2023-01-13 08:55:19 -06002596 ":ref:`dev-manual/building:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002597 section in the Yocto Project Development Tasks Manual.
2598
Andrew Geisslerf0343792020-11-18 10:42:21 -06002599 :term:`EXTERNALSRC_BUILD`
Andrew Geissler517393d2023-01-13 08:55:19 -06002600 When inheriting the :ref:`ref-classes-externalsrc`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002601 class, this variable points to the directory in which the recipe's
2602 source code is built, which is outside of the OpenEmbedded build
2603 system. When set, this variable sets the :term:`B` variable,
Patrick Williams2390b1b2022-11-03 13:47:49 -05002604 which is what the OpenEmbedded build system uses to locate the
2605 :term:`Build Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002606
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00002607 See the ":ref:`ref-classes-externalsrc`" section for details. You
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002608 can also find information on how to use this variable in the
Andrew Geissler517393d2023-01-13 08:55:19 -06002609 ":ref:`dev-manual/building:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002610 section in the Yocto Project Development Tasks Manual.
2611
Andrew Geisslerf0343792020-11-18 10:42:21 -06002612 :term:`EXTRA_AUTORECONF`
Andrew Geissler517393d2023-01-13 08:55:19 -06002613 For recipes inheriting the :ref:`ref-classes-autotools`
Andrew Geissler09036742021-06-25 14:25:14 -05002614 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002615 pass to the ``autoreconf`` command that is executed during the
2616 :ref:`ref-tasks-configure` task.
2617
2618 The default value is "--exclude=autopoint".
2619
Andrew Geisslerf0343792020-11-18 10:42:21 -06002620 :term:`EXTRA_IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002621 A list of additional features to include in an image. When listing
2622 more than one feature, separate them with a space.
2623
2624 Typically, you configure this variable in your ``local.conf`` file,
Patrick Williams2390b1b2022-11-03 13:47:49 -05002625 which is found in the :term:`Build Directory`. Although you can use this
2626 variable from within a recipe, best practices dictate that you do not.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002627
2628 .. note::
2629
2630 To enable primary features from within the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002631 :term:`IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002632
2633 Here are some examples of features you can add:
2634
Andrew Geissler615f2f12022-07-15 14:00:58 -05002635 - "dbg-pkgs" --- adds -dbg packages for all installed packages including
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002636 symbol information for debugging and profiling.
2637
Patrick Williams96e4b4e2025-02-03 15:49:15 -05002638 - "empty-root-password" --- This feature can be used if you want to
2639 allow root login with an empty password.
2640 - "allow-empty-password" --- Allows Dropbear and OpenSSH to accept
2641 logins from accounts having an empty password string.
2642 - "allow-root-login" --- Allows Dropbear and OpenSSH to accept root logins.
2643 - "post-install-logging" --- Enables logging postinstall script runs to
2644 the ``/var/log/postinstall.log`` file on first boot of the image on
2645 the target system.
Andrew Geissler615f2f12022-07-15 14:00:58 -05002646 - "dev-pkgs" --- adds -dev packages for all installed packages. This is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002647 useful if you want to develop against the libraries in the image.
Andrew Geissler615f2f12022-07-15 14:00:58 -05002648 - "read-only-rootfs" --- creates an image whose root filesystem is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002649 read-only. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06002650 ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002651 section in the Yocto Project Development Tasks Manual for more
2652 information
Andrew Geissler615f2f12022-07-15 14:00:58 -05002653 - "tools-debug" --- adds debugging tools such as gdb and strace.
2654 - "tools-sdk" --- adds development tools such as gcc, make,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002655 pkgconfig and so forth.
Andrew Geissler615f2f12022-07-15 14:00:58 -05002656 - "tools-testapps" --- adds useful testing tools
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002657 such as ts_print, aplay, arecord and so forth.
2658
2659 For a complete list of image features that ships with the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002660 Project, see the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002661
2662 For an example that shows how to customize your image by using this
Andrew Geissler517393d2023-01-13 08:55:19 -06002663 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002664 section in the Yocto Project Development Tasks Manual.
2665
Andrew Geisslerf0343792020-11-18 10:42:21 -06002666 :term:`EXTRA_IMAGECMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002667 Specifies additional options for the image creation command that has
2668 been specified in :term:`IMAGE_CMD`. When setting
2669 this variable, use an override for the associated image type. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002670 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002671
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002672 EXTRA_IMAGECMD:ext3 ?= "-i 4096"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002673
Andrew Geisslerf0343792020-11-18 10:42:21 -06002674 :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002675 A list of recipes to build that do not provide packages for
2676 installing into the root filesystem.
2677
2678 Sometimes a recipe is required to build the final image but is not
Andrew Geissler09036742021-06-25 14:25:14 -05002679 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002680 variable to list these recipes and thus specify the dependencies. A
2681 typical example is a required bootloader in a machine configuration.
2682
2683 .. note::
2684
2685 To add packages to the root filesystem, see the various
Andrew Geissler95ac1b82021-03-31 14:34:31 -05002686 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002687
Andrew Geisslerf0343792020-11-18 10:42:21 -06002688 :term:`EXTRA_OECMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002689 Additional `CMake <https://cmake.org/overview/>`__ options. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06002690 :ref:`ref-classes-cmake` class for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002691
Andrew Geisslerf0343792020-11-18 10:42:21 -06002692 :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002693 Additional ``configure`` script options. See
2694 :term:`PACKAGECONFIG_CONFARGS` for
2695 additional information on passing configure script options.
2696
Andrew Geisslerf0343792020-11-18 10:42:21 -06002697 :term:`EXTRA_OEMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002698 Additional GNU ``make`` options.
2699
Andrew Geissler09036742021-06-25 14:25:14 -05002700 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002701 variable to specify any required GNU options.
2702
2703 :term:`PARALLEL_MAKE` and
2704 :term:`PARALLEL_MAKEINST` also make use of
Andrew Geissler09036742021-06-25 14:25:14 -05002705 :term:`EXTRA_OEMAKE` to pass the required flags.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002706
Andrew Geisslerf0343792020-11-18 10:42:21 -06002707 :term:`EXTRA_OESCONS`
Andrew Geissler517393d2023-01-13 08:55:19 -06002708 When inheriting the :ref:`ref-classes-scons` class, this
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002709 variable specifies additional configuration options you want to pass
2710 to the ``scons`` command line.
2711
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06002712 :term:`EXTRA_OEMESON`
2713 Additional `Meson <https://mesonbuild.com/>`__ options. See the
2714 :ref:`ref-classes-meson` class for additional information.
2715
2716 In addition to standard Meson options, such options correspond to
2717 `Meson build options <https://mesonbuild.com/Build-options.html>`__
2718 defined in the ``meson_options.txt`` file in the sources to build.
2719 Here is an example::
2720
2721 EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled"
2722
2723 Note that any custom value for the Meson ``--buildtype`` option
2724 should be set through the :term:`MESON_BUILDTYPE` variable.
2725
Andrew Geisslerf0343792020-11-18 10:42:21 -06002726 :term:`EXTRA_USERS_PARAMS`
Andrew Geissler517393d2023-01-13 08:55:19 -06002727 When inheriting the :ref:`ref-classes-extrausers`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002728 class, this variable provides image level user and group operations.
2729 This is a more global method of providing user and group
2730 configuration as compared to using the
Andrew Geissler517393d2023-01-13 08:55:19 -06002731 :ref:`ref-classes-useradd` class, which ties user and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002732 group configurations to a specific recipe.
2733
2734 The set list of commands you can configure using the
Andrew Geissler517393d2023-01-13 08:55:19 -06002735 :term:`EXTRA_USERS_PARAMS` is shown in the
2736 :ref:`ref-classes-extrausers` class. These commands map to the normal
2737 Unix commands of the same names::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002738
2739 # EXTRA_USERS_PARAMS = "\
2740 # useradd -p '' tester; \
2741 # groupadd developers; \
2742 # userdel nobody; \
2743 # groupdel -g video; \
2744 # groupmod -g 1020 developers; \
2745 # usermod -s /bin/sh tester; \
2746 # "
2747
Patrick Williams03907ee2022-05-01 06:28:52 -05002748 Hardcoded passwords are supported via the ``-p`` parameters for
2749 ``useradd`` or ``usermod``, but only hashed.
2750
2751 Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
2752 passwords. First on host, create the (escaped) password hash::
2753
2754 printf "%q" $(mkpasswd -m sha256crypt tester01)
2755
2756 The resulting hash is set to a variable and used in ``useradd`` command parameters::
2757
2758 inherit extrausers
2759 PASSWD = "\$X\$ABC123\$A-Long-Hash"
2760 EXTRA_USERS_PARAMS = "\
2761 useradd -p '${PASSWD}' tester-jim; \
2762 useradd -p '${PASSWD}' tester-sue; \
2763 "
2764
2765 Finally, here is an example that sets the root password::
2766
2767 inherit extrausers
2768 EXTRA_USERS_PARAMS = "\
2769 usermod -p '${PASSWD}' root; \
2770 "
2771
2772 .. note::
2773
2774 From a security perspective, hardcoding a default password is not
Andrew Geissler87f5cff2022-09-30 13:13:31 -05002775 generally a good idea or even legal in some jurisdictions. It is
2776 recommended that you do not do this if you are building a production
Patrick Williams03907ee2022-05-01 06:28:52 -05002777 image.
2778
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002779 Additionally there is a special ``passwd-expire`` command that will
2780 cause the password for a user to be expired and thus force changing it
2781 on first login, for example::
2782
2783 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
2784
2785 .. note::
2786
2787 At present, ``passwd-expire`` may only work for remote logins when
2788 using OpenSSH and not dropbear as an SSH server.
2789
Andrew Geissler9aee5002022-03-30 16:27:02 +00002790 :term:`EXTRANATIVEPATH`
2791 A list of subdirectories of
2792 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2793 added to the beginning of the environment variable ``PATH``. As an
2794 example, the following prepends
2795 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2796 ``PATH``::
2797
2798 EXTRANATIVEPATH = "foo bar"
2799
Andrew Geissler517393d2023-01-13 08:55:19 -06002800 :term:`FAKEROOT`
2801 See :term:`bitbake:FAKEROOT` in the BitBake manual.
2802
2803 :term:`FAKEROOTBASEENV`
2804 See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual.
2805
2806 :term:`FAKEROOTCMD`
2807 See :term:`bitbake:FAKEROOTCMD` in the BitBake manual.
2808
2809 :term:`FAKEROOTDIRS`
2810 See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual.
2811
2812 :term:`FAKEROOTENV`
2813 See :term:`bitbake:FAKEROOTENV` in the BitBake manual.
2814
2815 :term:`FAKEROOTNOENV`
2816 See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual.
2817
Andrew Geisslerf0343792020-11-18 10:42:21 -06002818 :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002819 Defines one or more packages to include in an image when a specific
2820 item is included in :term:`IMAGE_FEATURES`.
Andrew Geissler09036742021-06-25 14:25:14 -05002821 When setting the value, :term:`FEATURE_PACKAGES` should have the name of
Andrew Geisslerc926e172021-05-07 16:11:35 -05002822 the feature item as an override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002823
2824 FEATURE_PACKAGES_widget = "package1 package2"
2825
Andrew Geissler09036742021-06-25 14:25:14 -05002826 In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002827 package1 and package2 would be included in the image.
2828
2829 .. note::
2830
Andrew Geissler09036742021-06-25 14:25:14 -05002831 Packages installed by features defined through :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002832 are often package groups. While similarly named, you should not
Andrew Geissler09036742021-06-25 14:25:14 -05002833 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002834 are discussed elsewhere in the documentation.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002835
Andrew Geisslerf0343792020-11-18 10:42:21 -06002836 :term:`FEED_DEPLOYDIR_BASE_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002837 Points to the base URL of the server and location within the
2838 document-root that provides the metadata and packages required by
2839 OPKG to support runtime package management of IPK packages. You set
2840 this variable in your ``local.conf`` file.
2841
Andrew Geisslerc926e172021-05-07 16:11:35 -05002842 Consider the following example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002843
2844 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2845
2846 This example assumes you are serving
2847 your packages over HTTP and your databases are located in a directory
2848 named ``BOARD-dir``, which is underneath your HTTP server's
2849 document-root. In this case, the OpenEmbedded build system generates
2850 a set of configuration files for you in your target that work with
2851 the feed.
2852
Andrew Geissler517393d2023-01-13 08:55:19 -06002853 :term:`FETCHCMD`
2854 See :term:`bitbake:FETCHCMD` in the BitBake manual.
2855
2856 :term:`FILE`
2857 See :term:`bitbake:FILE` in the BitBake manual.
2858
Andrew Geisslerf0343792020-11-18 10:42:21 -06002859 :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002860 The list of files and directories that are placed in a package. The
2861 :term:`PACKAGES` variable lists the packages
2862 generated by a recipe.
2863
Andrew Geissler09036742021-06-25 14:25:14 -05002864 To use the :term:`FILES` variable, provide a package name override that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002865 identifies the resulting package. Then, provide a space-separated
2866 list of files or paths that identify the files you want included as
Andrew Geisslerc926e172021-05-07 16:11:35 -05002867 part of the resulting package. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002868
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002869 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002870
2871 .. note::
2872
2873 - When specifying files or paths, you can pattern match using
2874 Python's
Patrick Williams2390b1b2022-11-03 13:47:49 -05002875 `glob <https://docs.python.org/3/library/glob.html>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002876 syntax. For details on the syntax, see the documentation by
2877 following the previous link.
2878
Andrew Geissler09036742021-06-25 14:25:14 -05002879 - When specifying paths as part of the :term:`FILES` variable, it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002880 good practice to use appropriate path variables. For example,
2881 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2882 rather than ``/usr/bin``. You can find a list of these
2883 variables at the top of the ``meta/conf/bitbake.conf`` file in
2884 the :term:`Source Directory`. You will also
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002885 find the default values of the various ``FILES:*`` variables in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002886 this file.
2887
Andrew Geissler09036742021-06-25 14:25:14 -05002888 If some of the files you provide with the :term:`FILES` variable are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002889 editable and you know they should not be overwritten during the
2890 package update process by the Package Management System (PMS), you
2891 can identify these files so that the PMS will not overwrite them. See
2892 the :term:`CONFFILES` variable for information on
2893 how to identify these files to the PMS.
2894
Andrew Geisslerf0343792020-11-18 10:42:21 -06002895 :term:`FILES_SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002896 Defines the file specification to match
2897 :term:`SOLIBSDEV`. In other words,
Andrew Geissler09036742021-06-25 14:25:14 -05002898 :term:`FILES_SOLIBSDEV` defines the full path name of the development
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002899 symbolic link (symlink) for shared libraries on the target platform.
2900
2901 The following statement from the ``bitbake.conf`` shows how it is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002902 set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002903
2904 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2905
Andrew Geisslerf0343792020-11-18 10:42:21 -06002906 :term:`FILESEXTRAPATHS`
Patrick Williams520786c2023-06-25 16:20:36 -05002907 A colon-separated list to extend the search path the OpenEmbedded build
2908 system uses when looking for files and patches as it processes recipes
2909 and append files. The default directories BitBake uses when it processes
2910 recipes are initially defined by the :term:`FILESPATH` variable. You can
2911 extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002912
2913 Best practices dictate that you accomplish this by using
Andrew Geissler09036742021-06-25 14:25:14 -05002914 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
Andrew Geisslerc926e172021-05-07 16:11:35 -05002915 prepend paths as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002916
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002917 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002918
2919 In the above example, the build system first
2920 looks for files in a directory that has the same name as the
2921 corresponding append file.
2922
2923 .. note::
2924
Andrew Geissler09036742021-06-25 14:25:14 -05002925 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002926 expansion (``:=``) operator. Immediate expansion makes sure that
2927 BitBake evaluates :term:`THISDIR` at the time the
2928 directive is encountered rather than at some later time when
2929 expansion might result in a directory that does not contain the
2930 files you need.
2931
2932 Also, include the trailing separating colon character if you are
2933 prepending. The trailing colon character is necessary because you
2934 are directing BitBake to extend the path by prepending directories
2935 to the search path.
2936
Andrew Geisslerc926e172021-05-07 16:11:35 -05002937 Here is another common use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002938
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002939 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002940
2941 In this example, the build system extends the
Andrew Geissler09036742021-06-25 14:25:14 -05002942 :term:`FILESPATH` variable to include a directory named ``files`` that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002943 in the same directory as the corresponding append file.
2944
Andrew Geisslerc926e172021-05-07 16:11:35 -05002945 This next example specifically adds three paths::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002946
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002947 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002948
2949 A final example shows how you can extend the search path and include
2950 a :term:`MACHINE`-specific override, which is useful
Andrew Geisslerc926e172021-05-07 16:11:35 -05002951 in a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002952
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002953 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002954
2955 The previous statement appears in the
2956 ``linux-yocto-dev.bbappend`` file, which is found in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002957 :ref:`overview-manual/development-environment:yocto project source repositories` in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002958 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2959 override is a special :term:`PACKAGE_ARCH`
2960 definition for multiple ``meta-intel`` machines.
2961
2962 .. note::
2963
2964 For a layer that supports a single BSP, the override could just be
Andrew Geissler09036742021-06-25 14:25:14 -05002965 the value of :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002966
2967 By prepending paths in ``.bbappend`` files, you allow multiple append
2968 files that reside in different layers but are used for the same
2969 recipe to correctly extend the path.
2970
Andrew Geisslerf0343792020-11-18 10:42:21 -06002971 :term:`FILESOVERRIDES`
Patrick Williams520786c2023-06-25 16:20:36 -05002972 A colon-separated list to specify a subset of :term:`OVERRIDES` used by
2973 the OpenEmbedded build system for creating :term:`FILESPATH`. The
2974 :term:`FILESOVERRIDES` variable uses overrides to automatically extend
2975 the :term:`FILESPATH` variable. For an example of how that works, see the
2976 :term:`FILESPATH` variable description. Additionally, you find more
2977 information on how overrides are handled in the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05002978 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002979 section of the BitBake User Manual.
2980
Andrew Geissler09036742021-06-25 14:25:14 -05002981 By default, the :term:`FILESOVERRIDES` variable is defined as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002982
2983 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2984
2985 .. note::
2986
Andrew Geissler09036742021-06-25 14:25:14 -05002987 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002988 with expected overrides and are used in an expected manner by the
2989 build system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002990
Andrew Geisslerf0343792020-11-18 10:42:21 -06002991 :term:`FILESPATH`
Patrick Williams520786c2023-06-25 16:20:36 -05002992 A colon-separated list specifying the default set of directories the
2993 OpenEmbedded build system uses when searching for patches and files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002994
2995 During the build process, BitBake searches each directory in
Andrew Geissler09036742021-06-25 14:25:14 -05002996 :term:`FILESPATH` in the specified order when looking for files and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002997 patches specified by each ``file://`` URI in a recipe's
2998 :term:`SRC_URI` statements.
2999
Andrew Geissler09036742021-06-25 14:25:14 -05003000 The default value for the :term:`FILESPATH` variable is defined in the
Patrick Williams975a06f2022-10-21 14:42:47 -05003001 :ref:`ref-classes-base` class found in ``meta/classes-global`` in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003002 :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003003
3004 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
3005 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
3006
3007 The
Andrew Geissler09036742021-06-25 14:25:14 -05003008 :term:`FILESPATH` variable is automatically extended using the overrides
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003009 from the :term:`FILESOVERRIDES` variable.
3010
3011 .. note::
3012
Andrew Geissler09036742021-06-25 14:25:14 -05003013 - Do not hand-edit the :term:`FILESPATH` variable. If you want the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003014 build system to look in directories other than the defaults,
Andrew Geissler09036742021-06-25 14:25:14 -05003015 extend the :term:`FILESPATH` variable by using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003016 :term:`FILESEXTRAPATHS` variable.
3017
Andrew Geissler09036742021-06-25 14:25:14 -05003018 - Be aware that the default :term:`FILESPATH` directories do not map
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003019 to directories in custom layers where append files
3020 (``.bbappend``) are used. If you want the build system to find
3021 patches or files that reside with your append files, you need
Andrew Geissler09036742021-06-25 14:25:14 -05003022 to extend the :term:`FILESPATH` variable by using the
3023 :term:`FILESEXTRAPATHS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003024
3025 You can take advantage of this searching behavior in useful ways. For
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003026 example, consider a case where there is the following directory structure
3027 for general and machine-specific configurations::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003028
3029 files/defconfig
3030 files/MACHINEA/defconfig
3031 files/MACHINEB/defconfig
3032
Andrew Geissler09036742021-06-25 14:25:14 -05003033 Also in the example, the :term:`SRC_URI` statement contains
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003034 "file://defconfig". Given this scenario, you can set
3035 :term:`MACHINE` to "MACHINEA" and cause the build
Andrew Geissler09036742021-06-25 14:25:14 -05003036 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003037 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
3038 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
3039 build system uses files from ``files/defconfig``.
3040
3041 You can find out more about the patching process in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003042 ":ref:`overview-manual/concepts:patching`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003043 in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler517393d2023-01-13 08:55:19 -06003044 ":ref:`dev-manual/new-recipe:patching code`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003045 the Yocto Project Development Tasks Manual. See the
3046 :ref:`ref-tasks-patch` task as well.
3047
Andrew Geisslerf0343792020-11-18 10:42:21 -06003048 :term:`FILESYSTEM_PERMS_TABLES`
Patrick Williams84603582024-12-14 08:00:57 -05003049 Allows you to define your own file permissions settings tables as part
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003050 of your configuration for the packaging process. For example, suppose
3051 you need a consistent set of custom permissions for a set of groups
3052 and users across an entire work project. It is best to do this in the
3053 packages themselves but this is not always possible.
3054
3055 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
Patrick Williams84603582024-12-14 08:00:57 -05003056 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` which are
3057 located in the ``meta/files`` folder in the :term:`Source Directory`. If
3058 you create your own permission setting table files, you should place
3059 those in your layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003060
Patrick Williams84603582024-12-14 08:00:57 -05003061 You can override the value of :term:`FILESYSTEM_PERMS_TABLES` variable
3062 in your distribution configuration file to point to your custom
3063 permission table files. You can specify one or more file permissions
3064 setting tables. The paths that you specify to these files must be defined
3065 within the :term:`BBPATH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003066
Patrick Williams84603582024-12-14 08:00:57 -05003067 In order to disable the volatile log, which is enabled by default, one
3068 can remove the ``files/fs-perms-volatile-log.txt`` value from
3069 ``FILESYSTEM_PERMS_TABLES``. Similarly, in order to disable the volatile
3070 tmp, one can remove the ``files/fs-perms-volatile-tmp.txt`` value.
3071
3072 For guidance on how to define your own file permissions settings
3073 tables, examine the existing ``fs-perms.txt``,
3074 ``fs-perms-volatile-log.txt`` and ``fs-perms-volatile-tmp.txt`` files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003075
Patrick Williams96e4b4e2025-02-03 15:49:15 -05003076 :term:`FIRMWARE_COMPRESSION`
3077 The :term:`FIRMWARE_COMPRESSION` allows compressing the firmware provided
3078 by the ``linux-firmware`` recipe. The default value of this variable is an
3079 empty string (no compression), and the possible values it can take are
3080 ``xz`` and ``zst``. This can allow significant disk space savings.
3081
3082 For this to work, the Linux Kernel requires the
3083 ``CONFIG_FW_LOADER_COMPRESS_XZ`` or ``CONFIG_FW_LOADER_COMPRESS_ZSTD``
3084 configuration options to be set.
3085
Andrew Geissler3eeda902023-05-19 10:14:02 -05003086 :term:`FIT_ADDRESS_CELLS`
Andrew Geissler3eeda902023-05-19 10:14:02 -05003087 Specifies the value of the ``#address-cells`` value for the
Patrick Williams44b3caf2024-04-12 16:51:14 -05003088 description of the FIT image.
Andrew Geissler3eeda902023-05-19 10:14:02 -05003089
3090 The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage`
Patrick Williams44b3caf2024-04-12 16:51:14 -05003091 class, which corresponds to 32 bit addresses.
Andrew Geissler3eeda902023-05-19 10:14:02 -05003092
Patrick Williamsb542dec2023-06-09 01:26:37 -05003093 For platforms that need to set 64 bit addresses, for example in
Andrew Geissler3eeda902023-05-19 10:14:02 -05003094 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
Patrick Williams44b3caf2024-04-12 16:51:14 -05003095 set this value to "2", as two 32 bit values (cells) will be needed
Andrew Geissler3eeda902023-05-19 10:14:02 -05003096 to represent such addresses.
3097
3098 Here is an example setting "0x400000000" as a load address::
Patrick Williams44b3caf2024-04-12 16:51:14 -05003099
Andrew Geissler3eeda902023-05-19 10:14:02 -05003100 FIT_ADDRESS_CELLS = "2"
3101 UBOOT_LOADADDRESS= "0x04 0x00000000"
3102
3103 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
3104
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003105 :term:`FIT_CONF_DEFAULT_DTB`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003106 Specifies the default device tree binary (dtb) file for a FIT image
3107 when multiple ones are provided.
3108
3109 This variable is used in the :ref:`ref-classes-kernel-fitimage` class.
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003110
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003111 :term:`FIT_DESC`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003112 Specifies the description string encoded into a FIT image. The
3113 default value is set by the :ref:`ref-classes-kernel-fitimage` class as
3114 follows::
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003115
3116 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
3117
Andrew Geisslerf0343792020-11-18 10:42:21 -06003118 :term:`FIT_GENERATE_KEYS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003119 Decides whether to generate the keys for signing the FIT image if
3120 they don't already exist. The keys are created in
3121 :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0"
3122 by the :ref:`ref-classes-kernel-fitimage` class.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003123
Andrew Geisslerf0343792020-11-18 10:42:21 -06003124 :term:`FIT_HASH_ALG`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003125 Specifies the hash algorithm used in creating the FIT Image.
3126 This variable is set by default to "sha256" by the
3127 :ref:`ref-classes-kernel-fitimage` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003128
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003129 :term:`FIT_KERNEL_COMP_ALG`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003130 The compression algorithm to use for the kernel image inside the FIT Image.
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06003131 At present, the only supported values are "gzip" (default), "lzo" or "none".
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003132 If you set this variable to anything other than "none" you may also need
3133 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
3134
Patrick Williamsb542dec2023-06-09 01:26:37 -05003135 This variable is used in the :ref:`ref-classes-kernel-uboot` class.
3136
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003137 :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
3138 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
Patrick Williamsb542dec2023-06-09 01:26:37 -05003139 value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you
3140 set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this
3141 variable to ".lzo".
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003142
Andrew Geisslerf0343792020-11-18 10:42:21 -06003143 :term:`FIT_KEY_GENRSA_ARGS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003144 Arguments to ``openssl genrsa`` for generating a RSA private key for
3145 signing the FIT image. The default value is set to "-F4" by the
3146 :ref:`ref-classes-kernel-fitimage` class.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003147
Andrew Geisslerf0343792020-11-18 10:42:21 -06003148 :term:`FIT_KEY_REQ_ARGS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003149 Arguments to ``openssl req`` for generating a certificate for signing
3150 the FIT image. The default value is "-batch -new" by the
3151 :ref:`ref-classes-kernel-fitimage` class, "batch" for
3152 non interactive mode and "new" for generating new keys.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003153
Andrew Geisslerf0343792020-11-18 10:42:21 -06003154 :term:`FIT_KEY_SIGN_PKCS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003155 Format for the public key certificate used for signing the FIT image.
3156 The default value is set to "x509" by the
3157 :ref:`ref-classes-kernel-fitimage` class.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003158
Andrew Geisslerf0343792020-11-18 10:42:21 -06003159 :term:`FIT_SIGN_ALG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003160 Specifies the signature algorithm used in creating the FIT Image.
Patrick Williamsb542dec2023-06-09 01:26:37 -05003161 This variable is set by default to "rsa2048" by the
3162 :ref:`ref-classes-kernel-fitimage` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003163
Patrick Williams975a06f2022-10-21 14:42:47 -05003164 :term:`FIT_PAD_ALG`
3165 Specifies the padding algorithm used in creating the FIT Image.
Patrick Williamsb542dec2023-06-09 01:26:37 -05003166 The default value is set to "pkcs-1.5" by the
3167 :ref:`ref-classes-kernel-fitimage` class.
Patrick Williams975a06f2022-10-21 14:42:47 -05003168
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003169 :term:`FIT_SIGN_INDIVIDUAL`
Andrew Geissler517393d2023-01-13 08:55:19 -06003170 If set to "1", then the :ref:`ref-classes-kernel-fitimage`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003171 class will sign the kernel, dtb and ramdisk images individually in addition
Patrick Williamsb542dec2023-06-09 01:26:37 -05003172 to signing the FIT image itself. This could be useful if you are
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003173 intending to verify signatures in another context than booting via
3174 U-Boot.
3175
Patrick Williamsb542dec2023-06-09 01:26:37 -05003176 This variable is set to "0" by default.
3177
Andrew Geissler9aee5002022-03-30 16:27:02 +00003178 :term:`FIT_SIGN_NUMBITS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05003179 Size of the private key used in the FIT image, in number of bits.
3180 The default value for this variable is set to "2048"
3181 by the :ref:`ref-classes-kernel-fitimage` class.
Andrew Geissler9aee5002022-03-30 16:27:02 +00003182
Andrew Geisslerf0343792020-11-18 10:42:21 -06003183 :term:`FONT_EXTRA_RDEPENDS`
Andrew Geissler517393d2023-01-13 08:55:19 -06003184 When inheriting the :ref:`ref-classes-fontcache` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003185 this variable specifies the runtime dependencies for font packages.
Andrew Geissler5f350902021-07-23 13:09:54 -04003186 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003187
Andrew Geisslerf0343792020-11-18 10:42:21 -06003188 :term:`FONT_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -06003189 When inheriting the :ref:`ref-classes-fontcache` class, this variable
3190 identifies packages containing font files that need to be cached by
3191 Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003192 that fonts are in the recipe's main package (i.e.
3193 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
3194 need are in a package other than that main package.
3195
Andrew Geisslerf0343792020-11-18 10:42:21 -06003196 :term:`FORCE_RO_REMOVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003197 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
3198 during the generation of the root filesystem.
3199
3200 Set the variable to "1" to force the removal of these packages.
3201
Andrew Geisslerf0343792020-11-18 10:42:21 -06003202 :term:`FULL_OPTIMIZATION`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003203 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003204 compiling an optimized system. This variable defaults to "-O2 -pipe
3205 ${DEBUG_FLAGS}".
3206
Andrew Geisslerf0343792020-11-18 10:42:21 -06003207 :term:`GCCPIE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003208 Enables Position Independent Executables (PIE) within the GNU C
3209 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
3210 Programming (ROP) attacks much more difficult to execute.
3211
3212 By default the ``security_flags.inc`` file enables PIE by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003213 variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003214
3215 GCCPIE ?= "--enable-default-pie"
3216
Andrew Geisslerf0343792020-11-18 10:42:21 -06003217 :term:`GCCVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003218 Specifies the default version of the GNU C Compiler (GCC) used for
Andrew Geissler09036742021-06-25 14:25:14 -05003219 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003220 ``meta/conf/distro/include/tcmode-default.inc`` include file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003221
3222 GCCVERSION ?= "8.%"
3223
3224 You can override this value by setting it in a
3225 configuration file such as the ``local.conf``.
3226
Andrew Geisslerf0343792020-11-18 10:42:21 -06003227 :term:`GDB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003228 The minimal command and arguments to run the GNU Debugger.
3229
Andrew Geissler595f6302022-01-24 19:11:47 +00003230 :term:`GIR_EXTRA_LIBS_PATH`
3231 Allows to specify an extra search path for ``.so`` files
3232 in GLib related recipes using GObject introspection,
3233 and which do not compile without this setting.
Andrew Geissler517393d2023-01-13 08:55:19 -06003234 See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`"
Andrew Geissler595f6302022-01-24 19:11:47 +00003235 section for details.
3236
Andrew Geisslerf0343792020-11-18 10:42:21 -06003237 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003238 The directory in which a local copy of a Git repository is stored
3239 when it is cloned.
3240
Patrick Williams975a06f2022-10-21 14:42:47 -05003241 :term:`GITHUB_BASE_URI`
Andrew Geissler517393d2023-01-13 08:55:19 -06003242 When inheriting the :ref:`ref-classes-github-releases`
Patrick Williams975a06f2022-10-21 14:42:47 -05003243 class, specifies the base URL for fetching releases for the github
3244 project you wish to fetch sources from. The default value is as follows::
3245
3246 GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/"
3247
Andrew Geisslerf0343792020-11-18 10:42:21 -06003248 :term:`GLIBC_GENERATE_LOCALES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003249 Specifies the list of GLIBC locales to generate should you not wish
3250 to generate all LIBC locals, which can be time consuming.
3251
3252 .. note::
3253
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003254 If you specifically remove the locale ``en_US.UTF-8``, you must set
3255 :term:`IMAGE_LINGUAS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003256
Andrew Geissler09036742021-06-25 14:25:14 -05003257 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
Andrew Geissler517393d2023-01-13 08:55:19 -06003258 By default, all locales are generated::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003259
3260 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
3261
Andrew Geisslerc5535c92023-01-27 16:10:19 -06003262 :term:`GO_IMPORT`
3263 When inheriting the :ref:`ref-classes-go` class, this mandatory variable
3264 sets the import path for the Go package that will be created for the code
3265 to build. If you have a ``go.mod`` file in the source directory, this
3266 typically matches the path in the ``module`` line in this file.
3267
3268 Other Go programs importing this package will use this path.
3269
3270 Here is an example setting from the
3271 :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>`
3272 recipe::
3273
3274 GO_IMPORT = "golang.org/x/example"
3275
3276 :term:`GO_INSTALL`
3277 When inheriting the :ref:`ref-classes-go` class, this optional variable
3278 specifies which packages in the sources should be compiled and
3279 installed in the Go build space by the
3280 `go install <https://go.dev/ref/mod#go-install>`__ command.
3281
3282 Here is an example setting from the
3283 :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>`
3284 recipe::
3285
3286 GO_INSTALL = "\
3287 ${GO_IMPORT}/cmd/crucible \
3288 ${GO_IMPORT}/cmd/habtool \
3289 "
3290
3291 By default, :term:`GO_INSTALL` is defined as::
3292
3293 GO_INSTALL ?= "${GO_IMPORT}/..."
3294
3295 The ``...`` wildcard means that it will catch all
3296 packages found in the sources.
3297
3298 See the :term:`GO_INSTALL_FILTEROUT` variable for
3299 filtering out unwanted packages from the ones
3300 found from the :term:`GO_INSTALL` value.
3301
3302 :term:`GO_INSTALL_FILTEROUT`
3303 When using the Go "vendor" mechanism to bring in dependencies for a Go
3304 package, the default :term:`GO_INSTALL` setting, which uses the ``...``
3305 wildcard, will include the vendored packages in the build, which produces
3306 incorrect results.
3307
3308 There are also some Go packages that are structured poorly, so that the
3309 ``...`` wildcard results in building example or test code that should not
3310 be included in the build, or could fail to build.
3311
3312 This optional variable allows for filtering out a subset of the sources.
3313 It defaults to excluding everything under the ``vendor`` subdirectory
3314 under package's main directory. This is the normal location for vendored
3315 packages, but it can be overridden by a recipe to filter out other
3316 subdirectories if needed.
3317
3318 :term:`GO_WORKDIR`
3319 When using Go Modules, the current working directory must be the directory
3320 containing the ``go.mod`` file, or one of its subdirectories. When the
3321 ``go`` tool is used, it will automatically look for the ``go.mod`` file
3322 in the Go working directory or in any parent directory, but not in
3323 subdirectories.
3324
3325 When using the :ref:`ref-classes-go-mod` class to use Go modules,
3326 the optional :term:`GO_WORKDIR` variable, defaulting to the value
3327 of :term:`GO_IMPORT`, allows to specify a different Go working directory.
3328
Andrew Geisslerf0343792020-11-18 10:42:21 -06003329 :term:`GROUPADD_PARAM`
Andrew Geissler517393d2023-01-13 08:55:19 -06003330 When inheriting the :ref:`ref-classes-useradd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003331 this variable specifies for a package what parameters should be
3332 passed to the ``groupadd`` command if you wish to add a group to the
3333 system when the package is installed.
3334
Andrew Geisslerc926e172021-05-07 16:11:35 -05003335 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003336
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003337 GROUPADD_PARAM:${PN} = "-r netdev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003338
Patrick Williamsb58112e2024-03-07 11:16:36 -06003339 More than one group can be added by separating each set of different
3340 groups' parameters with a semicolon.
3341
3342 Here is an example adding multiple groups from the ``useradd-example.bb``
3343 file in the ``meta-skeleton`` layer::
3344
3345 GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2"
3346
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003347 For information on the standard Linux shell command
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003348 ``groupadd``, see https://linux.die.net/man/8/groupadd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003349
Andrew Geisslerf0343792020-11-18 10:42:21 -06003350 :term:`GROUPMEMS_PARAM`
Andrew Geissler517393d2023-01-13 08:55:19 -06003351 When inheriting the :ref:`ref-classes-useradd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003352 this variable specifies for a package what parameters should be
3353 passed to the ``groupmems`` command if you wish to modify the members
3354 of a group when the package is installed.
3355
3356 For information on the standard Linux shell command ``groupmems``,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003357 see https://linux.die.net/man/8/groupmems.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003358
Andrew Geisslerf0343792020-11-18 10:42:21 -06003359 :term:`GRUB_GFXSERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003360 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
3361 and serial in the boot menu. Set this variable to "1" in your
3362 ``local.conf`` or distribution configuration file to enable graphics
3363 and serial in the menu.
3364
Andrew Geissler517393d2023-01-13 08:55:19 -06003365 See the :ref:`ref-classes-grub-efi` class for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003366 information on how this variable is used.
3367
Andrew Geisslerf0343792020-11-18 10:42:21 -06003368 :term:`GRUB_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003369 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
3370 configuration. Use a semi-colon character (``;``) to separate
3371 multiple options.
3372
Andrew Geissler09036742021-06-25 14:25:14 -05003373 The :term:`GRUB_OPTS` variable is optional. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06003374 :ref:`ref-classes-grub-efi` class for more information
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003375 on how this variable is used.
3376
Andrew Geisslerf0343792020-11-18 10:42:21 -06003377 :term:`GRUB_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003378 Specifies the timeout before executing the default ``LABEL`` in the
3379 GNU GRand Unified Bootloader (GRUB).
3380
Andrew Geissler09036742021-06-25 14:25:14 -05003381 The :term:`GRUB_TIMEOUT` variable is optional. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06003382 :ref:`ref-classes-grub-efi` class for more information
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003383 on how this variable is used.
3384
Patrick Williams43a6b7c2025-02-13 15:13:32 -05003385 :term:`GRUB_TITLE`
3386 Specifies custom titles for GRUB labels defined in :term:`LABELS`. See
3387 the :ref:`ref-classes-grub-efi` class for more information on how this
3388 variable is used.
3389
Andrew Geisslerf0343792020-11-18 10:42:21 -06003390 :term:`GTKIMMODULES_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -06003391 When inheriting the :ref:`ref-classes-gtk-immodules-cache` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003392 this variable specifies the packages that contain the GTK+ input
3393 method modules being installed when the modules are in packages other
3394 than the main package.
3395
Andrew Geissler517393d2023-01-13 08:55:19 -06003396 :term:`HGDIR`
3397 See :term:`bitbake:HGDIR` in the BitBake manual.
3398
Andrew Geisslerf0343792020-11-18 10:42:21 -06003399 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003400 Website where more information about the software the recipe is
3401 building can be found.
3402
Andrew Geisslerf0343792020-11-18 10:42:21 -06003403 :term:`HOST_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003404 The name of the target architecture, which is normally the same as
3405 :term:`TARGET_ARCH`. The OpenEmbedded build system
3406 supports many architectures. Here is an example list of architectures
3407 supported. This list is by no means complete as the architecture is
3408 configurable:
3409
3410 - arm
3411 - i586
3412 - x86_64
3413 - powerpc
3414 - powerpc64
3415 - mips
3416 - mipsel
3417
Andrew Geisslerf0343792020-11-18 10:42:21 -06003418 :term:`HOST_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003419 Specifies architecture-specific compiler flags that are passed to the
3420 C compiler.
3421
Andrew Geissler09036742021-06-25 14:25:14 -05003422 Default initialization for :term:`HOST_CC_ARCH` varies depending on what
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003423 is being built:
3424
3425 - :term:`TARGET_CC_ARCH` when building for the
3426 target
3427
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003428 - :term:`BUILD_CC_ARCH` when building for the build host (i.e.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003429 ``-native``)
3430
3431 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
3432 ``nativesdk-``)
3433
Andrew Geisslerf0343792020-11-18 10:42:21 -06003434 :term:`HOST_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003435 Specifies the name of the target operating system, which is normally
3436 the same as the :term:`TARGET_OS`. The variable can
3437 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
3438 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
3439 "linux-musleabi" values possible.
3440
Andrew Geisslerf0343792020-11-18 10:42:21 -06003441 :term:`HOST_PREFIX`
Andrew Geissler09036742021-06-25 14:25:14 -05003442 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003443 is normally the same as :term:`TARGET_PREFIX`.
3444
Andrew Geisslerf0343792020-11-18 10:42:21 -06003445 :term:`HOST_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003446 Specifies the system, including the architecture and the operating
3447 system, for which the build is occurring in the context of the
3448 current recipe.
3449
3450 The OpenEmbedded build system automatically sets this variable based
3451 on :term:`HOST_ARCH`,
3452 :term:`HOST_VENDOR`, and
3453 :term:`HOST_OS` variables.
3454
3455 .. note::
3456
3457 You do not need to set the variable yourself.
3458
3459 Consider these two examples:
3460
3461 - Given a native recipe on a 32-bit x86 machine running Linux, the
3462 value is "i686-linux".
3463
3464 - Given a recipe being built for a little-endian MIPS target running
3465 Linux, the value might be "mipsel-linux".
3466
Andrew Geissler9aee5002022-03-30 16:27:02 +00003467 :term:`HOST_VENDOR`
3468 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
3469 same as :term:`TARGET_VENDOR`.
3470
Andrew Geisslerf0343792020-11-18 10:42:21 -06003471 :term:`HOSTTOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003472 A space-separated list (filter) of tools on the build host that
3473 should be allowed to be called from within build tasks. Using this
3474 filter helps reduce the possibility of host contamination. If a tool
Andrew Geissler09036742021-06-25 14:25:14 -05003475 specified in the value of :term:`HOSTTOOLS` is not found on the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003476 host, the OpenEmbedded build system produces an error and the build
3477 is not started.
3478
3479 For additional information, see
3480 :term:`HOSTTOOLS_NONFATAL`.
3481
Andrew Geisslerf0343792020-11-18 10:42:21 -06003482 :term:`HOSTTOOLS_NONFATAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003483 A space-separated list (filter) of tools on the build host that
3484 should be allowed to be called from within build tasks. Using this
3485 filter helps reduce the possibility of host contamination. Unlike
3486 :term:`HOSTTOOLS`, the OpenEmbedded build system
3487 does not produce an error if a tool specified in the value of
Andrew Geissler09036742021-06-25 14:25:14 -05003488 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
3489 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003490
Andrew Geissler9aee5002022-03-30 16:27:02 +00003491 :term:`ICECC_CLASS_DISABLE`
3492 Identifies user classes that you do not want the Icecream distributed
3493 compile support to consider. This variable is used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06003494 :ref:`ref-classes-icecc` class. You set this variable in
Andrew Geissler9aee5002022-03-30 16:27:02 +00003495 your ``local.conf`` file.
3496
3497 When you list classes using this variable, the recipes inheriting
3498 those classes will not benefit from distributed compilation across
3499 remote hosts. Instead they will be built locally.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003500
Andrew Geisslerf0343792020-11-18 10:42:21 -06003501 :term:`ICECC_DISABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003502 Disables or enables the ``icecc`` (Icecream) function. For more
3503 information on this function and best practices for using this
Andrew Geissler595f6302022-01-24 19:11:47 +00003504 variable, see the ":ref:`ref-classes-icecc`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003505 section.
3506
3507 Setting this variable to "1" in your ``local.conf`` disables the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003508 function::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003509
3510 ICECC_DISABLED ??= "1"
3511
Andrew Geisslerc926e172021-05-07 16:11:35 -05003512 To enable the function, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003513
3514 ICECC_DISABLED = ""
3515
Andrew Geisslerf0343792020-11-18 10:42:21 -06003516 :term:`ICECC_ENV_EXEC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003517 Points to the ``icecc-create-env`` script that you provide. This
Andrew Geissler517393d2023-01-13 08:55:19 -06003518 variable is used by the :ref:`ref-classes-icecc` class. You
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003519 set this variable in your ``local.conf`` file.
3520
3521 If you do not point to a script that you provide, the OpenEmbedded
3522 build system uses the default script provided by the
Andrew Geissler87f5cff2022-09-30 13:13:31 -05003523 :oe_git:`icecc-create-env_0.1.bb
3524 </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>`
3525 recipe, which is a modified version and not the one that comes with
3526 ``icecream``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003527
Andrew Geisslerf0343792020-11-18 10:42:21 -06003528 :term:`ICECC_PARALLEL_MAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003529 Extra options passed to the ``make`` command during the
3530 :ref:`ref-tasks-compile` task that specify parallel
3531 compilation. This variable usually takes the form of "-j x", where x
3532 represents the maximum number of parallel threads ``make`` can run.
3533
3534 .. note::
3535
3536 The options passed affect builds on all enabled machines on the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003537 network, which are machines running the ``iceccd`` daemon.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003538
3539 If your enabled machines support multiple cores, coming up with the
3540 maximum number of parallel threads that gives you the best
3541 performance could take some experimentation since machine speed,
3542 network lag, available memory, and existing machine loads can all
3543 affect build time. Consequently, unlike the
3544 :term:`PARALLEL_MAKE` variable, there is no
Andrew Geissler09036742021-06-25 14:25:14 -05003545 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003546 performance.
3547
Andrew Geissler09036742021-06-25 14:25:14 -05003548 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003549 use it (i.e. the system does not detect and assign the number of
Andrew Geissler09036742021-06-25 14:25:14 -05003550 cores as is done with :term:`PARALLEL_MAKE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003551
Andrew Geisslerf0343792020-11-18 10:42:21 -06003552 :term:`ICECC_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003553 The location of the ``icecc`` binary. You can set this variable in
3554 your ``local.conf`` file. If your ``local.conf`` file does not define
Andrew Geissler517393d2023-01-13 08:55:19 -06003555 this variable, the :ref:`ref-classes-icecc` class attempts
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003556 to define it by locating ``icecc`` using ``which``.
3557
Andrew Geissler9aee5002022-03-30 16:27:02 +00003558 :term:`ICECC_RECIPE_DISABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003559 Identifies user recipes that you do not want the Icecream distributed
3560 compile support to consider. This variable is used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06003561 :ref:`ref-classes-icecc` class. You set this variable in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003562 your ``local.conf`` file.
3563
Andrew Geissler595f6302022-01-24 19:11:47 +00003564 When you list recipes using this variable, you are excluding them
3565 from distributed compilation across remote hosts. Instead they will
3566 be built locally.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003567
Andrew Geissler9aee5002022-03-30 16:27:02 +00003568 :term:`ICECC_RECIPE_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003569 Identifies user recipes that use an empty
3570 :term:`PARALLEL_MAKE` variable that you want to
3571 force remote distributed compilation on using the Icecream
3572 distributed compile support. This variable is used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06003573 :ref:`ref-classes-icecc` class. You set this variable in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003574 your ``local.conf`` file.
3575
Andrew Geisslerf0343792020-11-18 10:42:21 -06003576 :term:`IMAGE_BASENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003577 The base name of image output files. This variable defaults to the
3578 recipe name (``${``\ :term:`PN`\ ``}``).
3579
Andrew Geisslerf0343792020-11-18 10:42:21 -06003580 :term:`IMAGE_BOOT_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003581 A space-separated list of files installed into the boot partition
3582 when preparing an image using the Wic tool with the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003583 ``bootimg-partition`` source plugin. By default,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003584 the files are
3585 installed under the same name as the source files. To change the
3586 installed name, separate it from the original name with a semi-colon
3587 (;). Source files need to be located in
3588 :term:`DEPLOY_DIR_IMAGE`. Here are two
Andrew Geisslerc926e172021-05-07 16:11:35 -05003589 examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003590
3591 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
3592 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
3593
3594 Alternatively, source files can be picked up using a glob pattern. In
3595 this case, the destination file must have the same name as the base
3596 name of the source file path. To install files into a directory
3597 within the target location, pass its name after a semi-colon (;).
Andrew Geisslerc926e172021-05-07 16:11:35 -05003598 Here are two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003599
3600 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
3601 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
3602
3603 The first example
3604 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
3605 into the root of the target partition. The second example installs
3606 the same files into a ``boot`` directory within the target partition.
3607
3608 You can find information on how to use the Wic tool in the
Andrew Geissler517393d2023-01-13 08:55:19 -06003609 ":ref:`dev-manual/wic:creating partitioned images using wic`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003610 section of the Yocto Project Development Tasks Manual. Reference
3611 material for Wic is located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003612 ":doc:`/ref-manual/kickstart`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003613
Patrick Williams975a06f2022-10-21 14:42:47 -05003614 :term:`IMAGE_BUILDINFO_FILE`
Andrew Geissler517393d2023-01-13 08:55:19 -06003615 When using the :ref:`ref-classes-image-buildinfo` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05003616 specifies the file in the image to write the build information into. The
3617 default value is "``${sysconfdir}/buildinfo``".
3618
3619 :term:`IMAGE_BUILDINFO_VARS`
Andrew Geissler517393d2023-01-13 08:55:19 -06003620 When using the :ref:`ref-classes-image-buildinfo` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05003621 specifies the list of variables to include in the `Build Configuration`
3622 section of the output file (as a space-separated list). Defaults to
3623 ":term:`DISTRO` :term:`DISTRO_VERSION`".
3624
Andrew Geisslerf0343792020-11-18 10:42:21 -06003625 :term:`IMAGE_CLASSES`
Patrick Williams975a06f2022-10-21 14:42:47 -05003626 A list of classes that all images should inherit. This is typically used
3627 to enable functionality across all image recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003628
Patrick Williams975a06f2022-10-21 14:42:47 -05003629 Classes specified in :term:`IMAGE_CLASSES` must be located in the
3630 ``classes-recipe/`` or ``classes/`` subdirectories.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003631
Andrew Geisslerf0343792020-11-18 10:42:21 -06003632 :term:`IMAGE_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003633 Specifies the command to create the image file for a specific image
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003634 type, which corresponds to the value set in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003635 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
3636 ``btrfs``, and so forth). When setting this variable, you should use
Andrew Geisslerc926e172021-05-07 16:11:35 -05003637 an override for the associated type. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003638
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003639 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
Andrew Geissler09036742021-06-25 14:25:14 -05003640 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003641 ${EXTRA_IMAGECMD}"
3642
3643 You typically do not need to set this variable unless you are adding
3644 support for a new image type. For more examples on how to set this
Andrew Geissler517393d2023-01-13 08:55:19 -06003645 variable, see the :ref:`ref-classes-image_types`
Patrick Williams975a06f2022-10-21 14:42:47 -05003646 class file, which is ``meta/classes-recipe/image_types.bbclass``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003647
Andrew Geisslerf0343792020-11-18 10:42:21 -06003648 :term:`IMAGE_DEVICE_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003649 Specifies one or more files that contain custom device tables that
3650 are passed to the ``makedevs`` command as part of creating an image.
3651 These files list basic device nodes that should be created under
Andrew Geissler09036742021-06-25 14:25:14 -05003652 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003653 ``files/device_table-minimal.txt`` is used, which is located by
3654 :term:`BBPATH`. For details on how you should write
3655 device table files, see ``meta/files/device_table-minimal.txt`` as an
3656 example.
3657
Andrew Geissler9aee5002022-03-30 16:27:02 +00003658 :term:`IMAGE_EFI_BOOT_FILES`
3659 A space-separated list of files installed into the boot partition
3660 when preparing an image using the Wic tool with the
3661 ``bootimg-efi`` source plugin. By default,
3662 the files are
3663 installed under the same name as the source files. To change the
3664 installed name, separate it from the original name with a semi-colon
3665 (;). Source files need to be located in
3666 :term:`DEPLOY_DIR_IMAGE`. Here are two
3667 examples::
3668
3669 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
3670 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
3671
3672 Alternatively, source files can be picked up using a glob pattern. In
3673 this case, the destination file must have the same name as the base
3674 name of the source file path. To install files into a directory
3675 within the target location, pass its name after a semi-colon (;).
3676 Here are two examples::
3677
3678 IMAGE_EFI_BOOT_FILES = "boot/loader/*"
3679 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
3680
3681 The first example
3682 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
3683 into the root of the target partition. The second example installs
3684 the same files into a ``boot`` directory within the target partition.
3685
3686 You can find information on how to use the Wic tool in the
Andrew Geissler517393d2023-01-13 08:55:19 -06003687 ":ref:`dev-manual/wic:creating partitioned images using wic`"
Andrew Geissler9aee5002022-03-30 16:27:02 +00003688 section of the Yocto Project Development Tasks Manual. Reference
3689 material for Wic is located in the
3690 ":doc:`/ref-manual/kickstart`" chapter.
3691
Andrew Geisslerf0343792020-11-18 10:42:21 -06003692 :term:`IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003693 The primary list of features to include in an image. Typically, you
3694 configure this variable in an image recipe. Although you can use this
3695 variable from your ``local.conf`` file, which is found in the
3696 :term:`Build Directory`, best practices dictate that you do
3697 not.
3698
3699 .. note::
3700
3701 To enable extra features from outside the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003702 :term:`EXTRA_IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003703
3704 For a list of image features that ships with the Yocto Project, see
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003705 the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003706
3707 For an example that shows how to customize your image by using this
Andrew Geissler517393d2023-01-13 08:55:19 -06003708 variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003709 section in the Yocto Project Development Tasks Manual.
3710
Andrew Geisslerf0343792020-11-18 10:42:21 -06003711 :term:`IMAGE_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003712 Specifies the formats the OpenEmbedded build system uses during the
3713 build when creating the root filesystem. For example, setting
Andrew Geissler09036742021-06-25 14:25:14 -05003714 :term:`IMAGE_FSTYPES` as follows causes the build system to create root
Andrew Geisslerc926e172021-05-07 16:11:35 -05003715 filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003716
3717 IMAGE_FSTYPES = "ext3 tar.bz2"
3718
3719 For the complete list of supported image formats from which you can
3720 choose, see :term:`IMAGE_TYPES`.
3721
3722 .. note::
3723
3724 - If an image recipe uses the "inherit image" line and you are
Andrew Geissler09036742021-06-25 14:25:14 -05003725 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
Andrew Geissler5f350902021-07-23 13:09:54 -04003726 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003727
3728 - Due to the way the OpenEmbedded build system processes this
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003729 variable, you cannot update its contents by using ``:append``
3730 or ``:prepend``. You must use the ``+=`` operator to add one or
Andrew Geissler09036742021-06-25 14:25:14 -05003731 more options to the :term:`IMAGE_FSTYPES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003732
Andrew Geisslerf0343792020-11-18 10:42:21 -06003733 :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003734 Used by recipes to specify the packages to install into an image
Andrew Geissler517393d2023-01-13 08:55:19 -06003735 through the :ref:`ref-classes-image` class. Use the
Andrew Geissler09036742021-06-25 14:25:14 -05003736 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003737
Andrew Geissler09036742021-06-25 14:25:14 -05003738 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00003739 install into an image through :ref:`ref-classes-image`. Additionally,
Andrew Geissler517393d2023-01-13 08:55:19 -06003740 there are "helper" classes such as the :ref:`ref-classes-core-image`
3741 class which can take lists used with :term:`IMAGE_FEATURES` and turn
3742 them into auto-generated entries in :term:`IMAGE_INSTALL` in addition
3743 to its default contents.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003744
Andrew Geisslerc926e172021-05-07 16:11:35 -05003745 When you use this variable, it is best to use it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003746
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003747 IMAGE_INSTALL:append = " package-name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003748
3749 Be sure to include the space
3750 between the quotation character and the start of the package name or
3751 names.
3752
3753 .. note::
3754
3755 - When working with a
Andrew Geissler09209ee2020-12-13 08:44:15 -06003756 :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Andrew Geissler09036742021-06-25 14:25:14 -05003757 image, do not use the :term:`IMAGE_INSTALL` variable to specify
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003758 packages for installation. Instead, use the
3759 :term:`PACKAGE_INSTALL` variable, which
Patrick Williams2194f502022-10-16 14:26:09 -05003760 allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a
Andrew Geissler09036742021-06-25 14:25:14 -05003761 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
Patrick Williams2194f502022-10-16 14:26:09 -05003762 For information on creating an :term:`Initramfs`, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06003763 ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003764 section in the Yocto Project Development Tasks Manual.
3765
Andrew Geissler09036742021-06-25 14:25:14 -05003766 - Using :term:`IMAGE_INSTALL` with the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05003767 :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003768 BitBake operator within the ``/conf/local.conf`` file or from
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05003769 within an image recipe is not recommended. Use of this operator in
3770 these ways can cause ordering issues. Since
3771 :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a
3772 default value using the
3773 :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
Andrew Geissler09036742021-06-25 14:25:14 -05003774 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003775 results in unexpected behavior when used within
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05003776 ``conf/local.conf``. Furthermore, the same operation from within an
3777 image recipe may or may not succeed depending on the specific
3778 situation. In both these cases, the behavior is contrary to how
3779 most users expect the ``+=`` operator to work.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003780
Andrew Geisslerf0343792020-11-18 10:42:21 -06003781 :term:`IMAGE_LINGUAS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003782 Specifies the list of locales to install into the image during the
3783 root filesystem construction process. The OpenEmbedded build system
3784 automatically splits locale files, which are used for localization,
Andrew Geissler09036742021-06-25 14:25:14 -05003785 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003786 ensures that any locale packages that correspond to packages already
3787 selected for installation into the image are also installed. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05003788 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003789
3790 IMAGE_LINGUAS = "pt-br de-de"
3791
3792 In this example, the build system ensures any Brazilian Portuguese
3793 and German locale files that correspond to packages in the image are
3794 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
3795 ``*-locale-pt`` and ``*-locale-de``, since some software packages
3796 only provide locale files by language and not by country-specific
3797 language).
3798
3799 See the :term:`GLIBC_GENERATE_LOCALES`
3800 variable for information on generating GLIBC locales.
3801
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003802
3803 :term:`IMAGE_LINK_NAME`
3804 The name of the output image symlink (which does not include
3805 the version part as :term:`IMAGE_NAME` does). The default value
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003806 is derived using the :term:`IMAGE_BASENAME` and
3807 :term:`IMAGE_MACHINE_SUFFIX` variables::
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003808
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003809 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}"
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003810
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003811 .. note::
3812
3813 It is possible to set this to "" to disable symlink creation,
3814 however, you also need to set :term:`IMAGE_NAME` to still have
3815 a reasonable value e.g.::
3816
3817 IMAGE_LINK_NAME = ""
3818 IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
3819
3820 :term:`IMAGE_MACHINE_SUFFIX`
3821 Specifies the by default machine-specific suffix for image file names
3822 (before the extension). The default value is set as follows::
3823
3824 IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}"
3825
3826 The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE`
3827 subdirectory, so you may find it unnecessary to also include this suffix
3828 in the name of every image file. If you prefer to remove the suffix you
3829 can set this variable to an empty string::
3830
3831 IMAGE_MACHINE_SUFFIX = ""
3832
3833 (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.)
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003834
Andrew Geisslerf0343792020-11-18 10:42:21 -06003835 :term:`IMAGE_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003836 The manifest file for the image. This file lists all the installed
3837 packages that make up the image. The file contains package
Andrew Geisslerc926e172021-05-07 16:11:35 -05003838 information on a line-per-package basis as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003839
3840 packagename packagearch version
3841
Andrew Geissler09036742021-06-25 14:25:14 -05003842 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
Andrew Geisslerc926e172021-05-07 16:11:35 -05003843 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003844
Andrew Geissler09036742021-06-25 14:25:14 -05003845 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003846
3847 The location is
Andrew Geissler09036742021-06-25 14:25:14 -05003848 derived using the :term:`IMGDEPLOYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003849 and :term:`IMAGE_NAME` variables. You can find
Andrew Geissler09209ee2020-12-13 08:44:15 -06003850 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003851 section in the Yocto Project Overview and Concepts Manual.
3852
Andrew Geisslerf0343792020-11-18 10:42:21 -06003853 :term:`IMAGE_NAME`
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003854 The name of the output image files minus the extension. By default
3855 this variable is set using the :term:`IMAGE_LINK_NAME`, and
3856 :term:`IMAGE_VERSION_SUFFIX` variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003857
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003858 IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}"
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003859
3860 :term:`IMAGE_NAME_SUFFIX`
Andrew Geissler615f2f12022-07-15 14:00:58 -05003861 Suffix used for the image output filename --- defaults to ``".rootfs"``
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003862 to distinguish the image file from other files created during image
3863 building; however if this suffix is redundant or not desired you can
3864 clear the value of this variable (set the value to ""). For example,
Patrick Williams2194f502022-10-16 14:26:09 -05003865 this is typically cleared in :term:`Initramfs` image recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003866
Patrick Williams84603582024-12-14 08:00:57 -05003867 :term:`IMAGE_OUTPUT_MANIFEST`
3868 When inheriting the :ref:`ref-classes-image` class directly or through the
3869 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST`
3870 points to a manifest ``json`` file that lists what images were created by
3871 various image creation tasks (as defined by the :term:`IMAGE_FSTYPES`
3872 variable). It is set in the :ref:`ref-classes-image` class as follows::
3873
3874 IMAGE_OUTPUT_MANIFEST = "${IMAGE_OUTPUT_MANIFEST_DIR}/manifest.json"
3875
3876 :term:`IMAGE_OUTPUT_MANIFEST_DIR`
3877 When inheriting the :ref:`ref-classes-image` class directly or through the
3878 :ref:`ref-classes-core-image` class, the :term:`IMAGE_OUTPUT_MANIFEST_DIR` points to
3879 a directory that stores a manifest ``json`` file that lists what
3880 images were created by various image creation tasks (as defined by the
3881 :term:`IMAGE_FSTYPES` variable). It is set in the :ref:`ref-classes-image`
3882 class as follows::
3883
3884 IMAGE_OUTPUT_MANIFEST_DIR = "${WORKDIR}/deploy-image-output-manifest"
3885
Andrew Geisslerf0343792020-11-18 10:42:21 -06003886 :term:`IMAGE_OVERHEAD_FACTOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003887 Defines a multiplier that the build system applies to the initial
3888 image size for cases when the multiplier times the returned disk
3889 usage value for the image is greater than the sum of
Andrew Geissler09036742021-06-25 14:25:14 -05003890 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003891 the multiplier applied to the initial image size creates free disk
3892 space in the image as overhead. By default, the build process uses a
3893 multiplier of 1.3 for this variable. This default value results in
3894 30% free disk space added to the image when this method is used to
3895 determine the final generated image size. You should be aware that
3896 post install scripts and the package management system uses disk
3897 space inside this overhead area. Consequently, the multiplier does
3898 not produce an image with all the theoretical free disk space. See
Andrew Geissler09036742021-06-25 14:25:14 -05003899 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003900 determines the overall image size.
3901
3902 The default 30% free disk space typically gives the image enough room
3903 to boot and allows for basic post installs while still leaving a
3904 small amount of free disk space. If 30% free space is inadequate, you
3905 can increase the default value. For example, the following setting
Andrew Geisslerc926e172021-05-07 16:11:35 -05003906 gives you 50% free space added to the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003907
3908 IMAGE_OVERHEAD_FACTOR = "1.5"
3909
3910 Alternatively, you can ensure a specific amount of free disk space is
Andrew Geissler09036742021-06-25 14:25:14 -05003911 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003912 variable.
3913
Andrew Geisslerf0343792020-11-18 10:42:21 -06003914 :term:`IMAGE_PKGTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003915 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
3916 OpenEmbedded build system. The variable is defined appropriately by
Andrew Geissler517393d2023-01-13 08:55:19 -06003917 the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`,
Patrick Williams8e7b46e2023-05-01 14:19:06 -05003918 or :ref:`ref-classes-package_ipk` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003919
Andrew Geissler517393d2023-01-13 08:55:19 -06003920 The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image`
3921 classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003922
Andrew Geissler09036742021-06-25 14:25:14 -05003923 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003924 variable is set indirectly through the appropriate
3925 :ref:`package_* <ref-classes-package>` class using the
3926 :term:`PACKAGE_CLASSES` variable. The
3927 OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
3928 or IPK) that appears with the variable
3929
3930 .. note::
3931
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003932 Files using the ``.tar`` format are never used as a substitute
3933 packaging format for DEB, RPM, and IPK formatted files for your image
3934 or SDK.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003935
Andrew Geisslerf0343792020-11-18 10:42:21 -06003936 :term:`IMAGE_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003937 Specifies a list of functions to call once the OpenEmbedded build
3938 system creates the final image output files. You can specify
Patrick Williamsac13d5f2023-11-24 18:59:46 -06003939 functions separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003940
Patrick Williamsac13d5f2023-11-24 18:59:46 -06003941 IMAGE_POSTPROCESS_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003942
3943 If you need to pass the root filesystem path to a command within the
3944 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3945 directory that becomes the root filesystem image. See the
3946 :term:`IMAGE_ROOTFS` variable for more
3947 information.
3948
Andrew Geisslerf0343792020-11-18 10:42:21 -06003949 :term:`IMAGE_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003950 Specifies a list of functions to call before the OpenEmbedded build
3951 system creates the final image output files. You can specify
Patrick Williamsac13d5f2023-11-24 18:59:46 -06003952 functions separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003953
Patrick Williamsac13d5f2023-11-24 18:59:46 -06003954 IMAGE_PREPROCESS_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003955
3956 If you need to pass the root filesystem path to a command within the
3957 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3958 directory that becomes the root filesystem image. See the
3959 :term:`IMAGE_ROOTFS` variable for more
3960 information.
3961
Andrew Geisslerf0343792020-11-18 10:42:21 -06003962 :term:`IMAGE_ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003963 The location of the root filesystem while it is under construction
3964 (i.e. during the :ref:`ref-tasks-rootfs` task). This
3965 variable is not configurable. Do not change it.
3966
Andrew Geisslerf0343792020-11-18 10:42:21 -06003967 :term:`IMAGE_ROOTFS_ALIGNMENT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003968 Specifies the alignment for the output image file in Kbytes. If the
3969 size of the image is not a multiple of this value, then the size is
3970 rounded up to the nearest multiple of the value. The default value is
3971 "1". See :term:`IMAGE_ROOTFS_SIZE` for
3972 additional information.
3973
Andrew Geisslerf0343792020-11-18 10:42:21 -06003974 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003975 Defines additional free disk space created in the image in Kbytes. By
3976 default, this variable is set to "0". This free disk space is added
3977 to the image after the build system determines the image size as
Andrew Geissler09036742021-06-25 14:25:14 -05003978 described in :term:`IMAGE_ROOTFS_SIZE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003979
3980 This variable is particularly useful when you want to ensure that a
3981 specific amount of free disk space is available on a device after an
3982 image is installed and running. For example, to be sure 5 Gbytes of
Andrew Geisslerc926e172021-05-07 16:11:35 -05003983 free disk space is available, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003984
3985 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3986
3987 For example, the Yocto Project Build Appliance specifically requests
Andrew Geisslerc926e172021-05-07 16:11:35 -05003988 40 Gbytes of extra space with the line::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003989
3990 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3991
Andrew Geisslerf0343792020-11-18 10:42:21 -06003992 :term:`IMAGE_ROOTFS_SIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003993 Defines the size in Kbytes for the generated image. The OpenEmbedded
3994 build system determines the final size for the generated image using
3995 an algorithm that takes into account the initial disk space used for
3996 the generated image, a requested size for the image, and requested
3997 additional free disk space to be added to the image. Programatically,
3998 the build system determines the final size of the generated image as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003999 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004000
4001 if (image-du * overhead) < rootfs-size:
4002 internal-rootfs-size = rootfs-size + xspace
4003 else:
4004 internal-rootfs-size = (image-du * overhead) + xspace
4005 where:
4006 image-du = Returned value of the du command on the image.
4007 overhead = IMAGE_OVERHEAD_FACTOR
4008 rootfs-size = IMAGE_ROOTFS_SIZE
4009 internal-rootfs-size = Initial root filesystem size before any modifications.
4010 xspace = IMAGE_ROOTFS_EXTRA_SPACE
4011
4012 See the :term:`IMAGE_OVERHEAD_FACTOR`
4013 and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
4014 variables for related information.
4015
Andrew Geisslerf0343792020-11-18 10:42:21 -06004016 :term:`IMAGE_TYPEDEP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004017 Specifies a dependency from one image type on another. Here is an
Andrew Geissler517393d2023-01-13 08:55:19 -06004018 example from the :ref:`ref-classes-image-live` class::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004019
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004020 IMAGE_TYPEDEP:live = "ext3"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004021
4022 In the previous example, the variable ensures that when "live" is
4023 listed with the :term:`IMAGE_FSTYPES` variable,
4024 the OpenEmbedded build system produces an ``ext3`` image first since
4025 one of the components of the live image is an ``ext3`` formatted
4026 partition containing the root filesystem.
4027
Andrew Geisslerf0343792020-11-18 10:42:21 -06004028 :term:`IMAGE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004029 Specifies the complete list of supported image types by default:
4030
4031 - btrfs
4032 - container
4033 - cpio
4034 - cpio.gz
4035 - cpio.lz4
4036 - cpio.lzma
4037 - cpio.xz
4038 - cramfs
Andrew Geissler09036742021-06-25 14:25:14 -05004039 - erofs
4040 - erofs-lz4
4041 - erofs-lz4hc
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004042 - ext2
4043 - ext2.bz2
4044 - ext2.gz
4045 - ext2.lzma
4046 - ext3
4047 - ext3.gz
4048 - ext4
4049 - ext4.gz
4050 - f2fs
4051 - hddimg
4052 - iso
4053 - jffs2
4054 - jffs2.sum
4055 - multiubi
4056 - squashfs
4057 - squashfs-lz4
4058 - squashfs-lzo
4059 - squashfs-xz
4060 - tar
4061 - tar.bz2
4062 - tar.gz
4063 - tar.lz4
4064 - tar.xz
4065 - tar.zst
4066 - ubi
4067 - ubifs
4068 - wic
4069 - wic.bz2
4070 - wic.gz
4071 - wic.lzma
Patrick Williams84603582024-12-14 08:00:57 -05004072 - wic.zst
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004073
4074 For more information about these types of images, see
Patrick Williams975a06f2022-10-21 14:42:47 -05004075 ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004076
Andrew Geissler6ce62a22020-11-30 19:58:47 -06004077 :term:`IMAGE_VERSION_SUFFIX`
4078 Version suffix that is part of the default :term:`IMAGE_NAME` and
4079 :term:`KERNEL_ARTIFACT_NAME` values.
4080 Defaults to ``"-${DATETIME}"``, however you could set this to a
4081 version string that comes from your external build environment if
4082 desired, and this suffix would then be used consistently across
4083 the build artifacts.
4084
Andrew Geissler09036742021-06-25 14:25:14 -05004085 :term:`IMGDEPLOYDIR`
Andrew Geissler517393d2023-01-13 08:55:19 -06004086 When inheriting the :ref:`ref-classes-image` class directly or
4087 through the :ref:`ref-classes-core-image` class, the
Andrew Geissler5f350902021-07-23 13:09:54 -04004088 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
Andrew Geissler09036742021-06-25 14:25:14 -05004089 that is set in the ``image`` class as follows::
4090
4091 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
4092
Andrew Geissler517393d2023-01-13 08:55:19 -06004093 Recipes inheriting the :ref:`ref-classes-image` class should copy
4094 files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take
4095 care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
Andrew Geissler09036742021-06-25 14:25:14 -05004096
Patrick Williams84603582024-12-14 08:00:57 -05004097 :term:`IMGMANIFESTDIR`
4098 When inheriting the :ref:`ref-classes-image` class directly or through the
4099 :ref:`ref-classes-core-image` class, the :term:`IMGMANIFESTDIR` setting
4100 points to a temporary area that stores manifest ``json`` files, that list
4101 what images were created by various images creation tasks (as defined by
4102 the :term:`IMAGE_FSTYPES` variable). It is set in the
4103 :ref:`ref-classes-image` class as follows::
4104
4105 IMGMANIFESTDIR = "${WORKDIR}/image-task-manifest"
4106
Andrew Geisslerf0343792020-11-18 10:42:21 -06004107 :term:`INCOMPATIBLE_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004108 Specifies a space-separated list of license names (as they would
4109 appear in :term:`LICENSE`) that should be excluded
Patrick Williams2a254922023-08-11 09:48:11 -05004110 from the build (if set globally), or from an image (if set locally
Patrick Williams44b3caf2024-04-12 16:51:14 -05004111 in an image recipe).
Patrick Williams2a254922023-08-11 09:48:11 -05004112
4113 When the variable is set globally, recipes that provide no alternatives to listed
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004114 incompatible licenses are not built. Packages that are individually
Patrick Williams44b3caf2024-04-12 16:51:14 -05004115 licensed with the specified incompatible licenses will be deleted.
Patrick Williams2a254922023-08-11 09:48:11 -05004116 Most of the time this does not allow a feasible build (because it becomes impossible
4117 to satisfy build time dependencies), so the recommended way to
4118 implement license restrictions is to set the variable in specific
Patrick Williams44b3caf2024-04-12 16:51:14 -05004119 image recipes where the restrictions must apply. That way there
Patrick Williams2a254922023-08-11 09:48:11 -05004120 are no build time restrictions, but the license check is still
4121 performed when the image's filesystem is assembled from packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004122
Patrick Williams03907ee2022-05-01 06:28:52 -05004123 There is some support for wildcards in this variable's value,
4124 however it is restricted to specific licenses. Currently only
4125 these wildcards are allowed and expand as follows:
4126
4127 - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later``
4128 - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later``
4129 - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later``
4130
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004131 .. note::
4132
4133 This functionality is only regularly tested using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05004134 setting::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004135
Andrew Geissler9aee5002022-03-30 16:27:02 +00004136 INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004137
4138
4139 Although you can use other settings, you might be required to
Patrick Williams975a06f2022-10-21 14:42:47 -05004140 remove dependencies on (or provide alternatives to) components that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004141 are required to produce a functional system image.
4142
Andrew Geissler615f2f12022-07-15 14:00:58 -05004143 :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS`
4144 Specifies a space-separated list of package and license pairs that
4145 are allowed to be used even if the license is specified in
4146 :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are
4147 separated using a colon. Example::
4148
4149 INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only"
4150
Andrew Geisslerf0343792020-11-18 10:42:21 -06004151 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004152 Causes the named class or classes to be inherited globally. Anonymous
4153 functions in the class or classes are not executed for the base
4154 configuration and in each individual recipe. The OpenEmbedded build
Andrew Geissler09036742021-06-25 14:25:14 -05004155 system ignores changes to :term:`INHERIT` in individual recipes.
Patrick Williams975a06f2022-10-21 14:42:47 -05004156 Classes inherited using :term:`INHERIT` must be located in the
4157 ``classes-global/`` or ``classes/`` subdirectories.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004158
Andrew Geissler09036742021-06-25 14:25:14 -05004159 For more information on :term:`INHERIT`, see the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05004160 :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
Andrew Geisslerd5838332022-05-27 11:33:10 -05004161 section in the BitBake User Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004162
Andrew Geisslerf0343792020-11-18 10:42:21 -06004163 :term:`INHERIT_DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004164 Lists classes that will be inherited at the distribution level. It is
4165 unlikely that you want to edit this variable.
4166
Patrick Williams975a06f2022-10-21 14:42:47 -05004167 Classes specified in :term:`INHERIT_DISTRO` must be located in the
4168 ``classes-global/`` or ``classes/`` subdirectories.
4169
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004170 The default value of the variable is set as follows in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004171 ``meta/conf/distro/defaultsetup.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004172
Patrick Williams2f814a62024-04-16 16:28:03 -05004173 INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004174
Andrew Geisslerf0343792020-11-18 10:42:21 -06004175 :term:`INHIBIT_DEFAULT_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004176 Prevents the default dependencies, namely the C compiler and standard
4177 C library (libc), from being added to :term:`DEPENDS`.
4178 This variable is usually used within recipes that do not require any
4179 compilation using the C compiler.
4180
4181 Set the variable to "1" to prevent the default dependencies from
4182 being added.
4183
Andrew Geisslerf0343792020-11-18 10:42:21 -06004184 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004185 Prevents the OpenEmbedded build system from splitting out debug
4186 information during packaging. By default, the build system splits out
4187 debugging information during the
4188 :ref:`ref-tasks-package` task. For more information on
4189 how debug information is split out, see the
4190 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
4191 variable.
4192
4193 To prevent the build system from splitting out debug information
Andrew Geissler09036742021-06-25 14:25:14 -05004194 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -05004195 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004196
4197 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
4198
Andrew Geisslerf0343792020-11-18 10:42:21 -06004199 :term:`INHIBIT_PACKAGE_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004200 If set to "1", causes the build to not strip binaries in resulting
4201 packages and prevents the ``-dbg`` package from containing the source
4202 files.
4203
4204 By default, the OpenEmbedded build system strips binaries and puts
4205 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
Andrew Geissler09036742021-06-25 14:25:14 -05004206 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004207 plan to debug in general.
4208
Andrew Geisslerf0343792020-11-18 10:42:21 -06004209 :term:`INHIBIT_SYSROOT_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004210 If set to "1", causes the build to not strip binaries in the
4211 resulting sysroot.
4212
4213 By default, the OpenEmbedded build system strips binaries in the
4214 resulting sysroot. When you specifically set the
Andrew Geissler09036742021-06-25 14:25:14 -05004215 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004216 this stripping.
4217
Andrew Geissler517393d2023-01-13 08:55:19 -06004218 If you want to use this variable, include the :ref:`ref-classes-staging`
4219 class. This class uses a ``sys_strip()`` function to test for the variable
4220 and acts accordingly.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004221
4222 .. note::
4223
Andrew Geissler09036742021-06-25 14:25:14 -05004224 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004225 special circumstances. For example, suppose you are building
4226 bare-metal firmware by using an external GCC toolchain. Furthermore,
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004227 even if the toolchain's binaries are strippable, there are other files
4228 needed for the build that are not strippable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004229
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004230 :term:`INIT_MANAGER`
4231 Specifies the system init manager to use. Available options are:
Patrick Williams2194f502022-10-16 14:26:09 -05004232
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004233 - ``sysvinit``
4234 - ``systemd``
4235 - ``mdev-busybox``
Patrick Williams2194f502022-10-16 14:26:09 -05004236
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004237 With ``sysvinit``, the init manager is set to
4238 :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init
4239 system. This is the default choice in the Poky distribution, together with
4240 the Udev device manager (see the ":ref:`device-manager`" section).
Patrick Williams2194f502022-10-16 14:26:09 -05004241
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004242 With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`,
4243 which comes with the :wikipedia:`udev <Udev>` device manager.
Patrick Williams2194f502022-10-16 14:26:09 -05004244
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004245 With ``mdev-busybox``, the init manager becomes the much simpler BusyBox
4246 init, together with the BusyBox mdev device manager. This is the simplest
4247 and lightest solution, and probably the best choice for low-end systems
4248 with a rather slow CPU and a limited amount of RAM.
Patrick Williams2194f502022-10-16 14:26:09 -05004249
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004250 More concretely, this is used to include
4251 ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global
4252 configuration. You can have a look at the
4253 :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>`
4254 files for more information, and also the ":ref:`init-manager`"
Patrick Williams2194f502022-10-16 14:26:09 -05004255 section in the Yocto Project Development Tasks Manual.
4256
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004257 :term:`INITRAMFS_DEPLOY_DIR_IMAGE`
Andrew Geissler517393d2023-01-13 08:55:19 -06004258 Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs`
4259 where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is
4260 set by default to ``${DEPLOY_DIR_IMAGE}`` in the
4261 :ref:`ref-classes-kernel` class and it's only meant to be changed when
4262 building an :term:`Initramfs` image from a separate multiconfig via
4263 :term:`INITRAMFS_MULTICONFIG`.
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004264
Andrew Geisslerf0343792020-11-18 10:42:21 -06004265 :term:`INITRAMFS_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004266 Defines the format for the output image of an initial RAM filesystem
Patrick Williams2194f502022-10-16 14:26:09 -05004267 (:term:`Initramfs`), which is used during boot. Supported formats are the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004268 same as those supported by the
4269 :term:`IMAGE_FSTYPES` variable.
4270
4271 The default value of this variable, which is set in the
4272 ``meta/conf/bitbake.conf`` configuration file in the
4273 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
Patrick Williams2194f502022-10-16 14:26:09 -05004274 :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem
Patrick Williams7784c422022-11-17 07:29:11 -06004275 :wikipedia:`initrd <Initrd>` mechanism, expects
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004276 an optionally compressed cpio archive.
4277
Andrew Geisslerf0343792020-11-18 10:42:21 -06004278 :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004279 Specifies the :term:`PROVIDES` name of an image
Patrick Williams2194f502022-10-16 14:26:09 -05004280 recipe that is used to build an initial RAM filesystem (:term:`Initramfs`)
Andrew Geissler09036742021-06-25 14:25:14 -05004281 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004282 additional recipe to be built as a dependency to whatever root
4283 filesystem recipe you might be using (e.g. ``core-image-sato``). The
Patrick Williams2194f502022-10-16 14:26:09 -05004284 :term:`Initramfs` image recipe you provide should set
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004285 :term:`IMAGE_FSTYPES` to
4286 :term:`INITRAMFS_FSTYPES`.
4287
Patrick Williams2194f502022-10-16 14:26:09 -05004288 An :term:`Initramfs` image provides a temporary root filesystem used for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004289 early system initialization (e.g. loading of modules needed to locate
4290 and mount the "real" root filesystem).
4291
4292 .. note::
4293
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004294 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
4295 recipe in the :term:`Source Directory`
Patrick Williams2194f502022-10-16 14:26:09 -05004296 for an example :term:`Initramfs` recipe. To select this sample recipe as
4297 the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004298 to "core-image-minimal-initramfs".
4299
4300 You can also find more information by referencing the
Andrew Geissler87f5cff2022-09-30 13:13:31 -05004301 ``meta-poky/conf/templates/default/local.conf.sample.extended``
Andrew Geissler517393d2023-01-13 08:55:19 -06004302 configuration file in the Source Directory, the :ref:`ref-classes-image`
4303 class, and the :ref:`ref-classes-kernel` class to see how to use the
4304 :term:`INITRAMFS_IMAGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004305
Andrew Geissler09036742021-06-25 14:25:14 -05004306 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
Patrick Williams2194f502022-10-16 14:26:09 -05004307 :term:`Initramfs` image is built.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004308
4309 For more information, you can also see the
4310 :term:`INITRAMFS_IMAGE_BUNDLE`
4311 variable, which allows the generated image to be bundled inside the
Patrick Williams2194f502022-10-16 14:26:09 -05004312 kernel image. Additionally, for information on creating an :term:`Initramfs`
Andrew Geissler517393d2023-01-13 08:55:19 -06004313 image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004314 in the Yocto Project Development Tasks Manual.
4315
Andrew Geisslerf0343792020-11-18 10:42:21 -06004316 :term:`INITRAMFS_IMAGE_BUNDLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004317 Controls whether or not the image recipe specified by
4318 :term:`INITRAMFS_IMAGE` is run through an
4319 extra pass
4320 (:ref:`ref-tasks-bundle_initramfs`) during
4321 kernel compilation in order to build a single binary that contains
Patrick Williams2194f502022-10-16 14:26:09 -05004322 both the kernel image and the initial RAM filesystem (:term:`Initramfs`)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004323 image. This makes use of the
4324 :term:`CONFIG_INITRAMFS_SOURCE` kernel
4325 feature.
4326
4327 .. note::
4328
Patrick Williams2194f502022-10-16 14:26:09 -05004329 Bundling the :term:`Initramfs` with the kernel conflates the code in the
4330 :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
4331 compatible software may be part of a bundled :term:`Initramfs`.
Patrick Williams93c203f2021-10-06 16:15:23 -05004332
4333 .. note::
4334
Patrick Williams2194f502022-10-16 14:26:09 -05004335 Using an extra compilation pass to bundle the :term:`Initramfs` avoids a
4336 circular dependency between the kernel recipe and the :term:`Initramfs`
4337 recipe should the :term:`Initramfs` include kernel modules. Should that be
4338 the case, the :term:`Initramfs` recipe depends on the kernel for the
4339 kernel modules, and the kernel depends on the :term:`Initramfs` recipe
4340 since the :term:`Initramfs` is bundled inside the kernel image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004341
4342 The combined binary is deposited into the ``tmp/deploy`` directory,
4343 which is part of the :term:`Build Directory`.
4344
4345 Setting the variable to "1" in a configuration file causes the
4346 OpenEmbedded build system to generate a kernel image with the
Patrick Williams2194f502022-10-16 14:26:09 -05004347 :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004348
4349 INITRAMFS_IMAGE_BUNDLE = "1"
4350
Andrew Geissler517393d2023-01-13 08:55:19 -06004351 By default, the :ref:`ref-classes-kernel` class sets this variable to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05004352 null string as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004353
4354 INITRAMFS_IMAGE_BUNDLE ?= ""
4355
4356 .. note::
4357
Andrew Geissler09036742021-06-25 14:25:14 -05004358 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004359 configuration file. You cannot set the variable in a recipe file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004360
4361 See the
Andrew Geissler87f5cff2022-09-30 13:13:31 -05004362 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004363 file for additional information. Also, for information on creating an
Andrew Geissler517393d2023-01-13 08:55:19 -06004364 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004365 in the Yocto Project Development Tasks Manual.
4366
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004367 :term:`INITRAMFS_IMAGE_NAME`
4368
4369 This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with
4370 :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value
4371 is set as follows:
4372
4373 INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}"
4374
4375 That is, if :term:`INITRAMFS_IMAGE` is set, the value of
4376 :term:`INITRAMFS_IMAGE_NAME` will be set based upon
4377 :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`.
4378
4379
Andrew Geisslerf0343792020-11-18 10:42:21 -06004380 :term:`INITRAMFS_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004381 The link name of the initial RAM filesystem image. This variable is
Patrick Williams975a06f2022-10-21 14:42:47 -05004382 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05004383 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004384
4385 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
4386
4387 The value of the
4388 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05004389 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004390
4391 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4392
4393 See the :term:`MACHINE` variable for additional
4394 information.
4395
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004396 :term:`INITRAMFS_MULTICONFIG`
Andrew Geissler517393d2023-01-13 08:55:19 -06004397 Defines the multiconfig to create a multiconfig dependency to be used by
4398 the :ref:`ref-classes-kernel` class.
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004399
4400 This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from
4401 a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`.
4402
Patrick Williams2194f502022-10-16 14:26:09 -05004403 For more information on how to bundle an :term:`Initramfs` image from a separate
Andrew Geissler517393d2023-01-13 08:55:19 -06004404 multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`"
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004405 section in the Yocto Project Development Tasks Manual.
4406
Andrew Geisslerf0343792020-11-18 10:42:21 -06004407 :term:`INITRAMFS_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004408 The base name of the initial RAM filesystem image. This variable is
Patrick Williams975a06f2022-10-21 14:42:47 -05004409 set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05004410 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004411
4412 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
4413
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004414 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004415
Andrew Geisslerf0343792020-11-18 10:42:21 -06004416 :term:`INITRD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004417 Indicates list of filesystem images to concatenate and use as an
4418 initial RAM disk (``initrd``).
4419
Andrew Geissler09036742021-06-25 14:25:14 -05004420 The :term:`INITRD` variable is an optional variable used with the
Andrew Geissler517393d2023-01-13 08:55:19 -06004421 :ref:`ref-classes-image-live` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004422
Andrew Geisslerf0343792020-11-18 10:42:21 -06004423 :term:`INITRD_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004424 When building a "live" bootable image (i.e. when
4425 :term:`IMAGE_FSTYPES` contains "live"),
Andrew Geissler09036742021-06-25 14:25:14 -05004426 :term:`INITRD_IMAGE` specifies the image recipe that should be built to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004427 provide the initial RAM disk image. The default value is
4428 "core-image-minimal-initramfs".
4429
Andrew Geissler517393d2023-01-13 08:55:19 -06004430 See the :ref:`ref-classes-image-live` class for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004431
Andrew Geisslerf0343792020-11-18 10:42:21 -06004432 :term:`INITSCRIPT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004433 The filename of the initialization script as installed to
4434 ``${sysconfdir}/init.d``.
4435
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004436 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004437 The variable is mandatory.
4438
Andrew Geisslerf0343792020-11-18 10:42:21 -06004439 :term:`INITSCRIPT_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004440 A list of the packages that contain initscripts. If multiple packages
4441 are specified, you need to append the package name to the other
4442 ``INITSCRIPT_*`` as an override.
4443
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00004444 This variable is used in recipes when using :ref:`ref-classes-update-rc.d`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004445 The variable is optional and defaults to the :term:`PN`
4446 variable.
4447
Andrew Geisslerf0343792020-11-18 10:42:21 -06004448 :term:`INITSCRIPT_PARAMS`
Andrew Geisslerc926e172021-05-07 16:11:35 -05004449 Specifies the options to pass to ``update-rc.d``. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004450
4451 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
4452
4453 In this example, the script has a runlevel of 99, starts the script
4454 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
4455
4456 The variable's default value is "defaults", which is set in the
Andrew Geissler517393d2023-01-13 08:55:19 -06004457 :ref:`ref-classes-update-rc.d` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004458
Andrew Geissler09036742021-06-25 14:25:14 -05004459 The value in :term:`INITSCRIPT_PARAMS` is passed through to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004460 ``update-rc.d`` command. For more information on valid parameters,
4461 please see the ``update-rc.d`` manual page at
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05004462 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004463
Andrew Geisslerf0343792020-11-18 10:42:21 -06004464 :term:`INSANE_SKIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004465 Specifies the QA checks to skip for a specific package within a
4466 recipe. For example, to skip the check for symbolic link ``.so``
4467 files in the main package of a recipe, add the following to the
4468 recipe. The package name override must be used, which in this example
Andrew Geisslerc926e172021-05-07 16:11:35 -05004469 is ``${PN}``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004470
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004471 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004472
Andrew Geissler595f6302022-01-24 19:11:47 +00004473 See the ":ref:`ref-classes-insane`" section for a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004474 list of the valid QA checks you can specify using this variable.
4475
Andrew Geisslerf0343792020-11-18 10:42:21 -06004476 :term:`INSTALL_TIMEZONE_FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004477 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
Andrew Geissler09036742021-06-25 14:25:14 -05004478 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004479 configuration level to disable this behavior.
4480
Andrew Geisslerf0343792020-11-18 10:42:21 -06004481 :term:`IPK_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004482 When the IPK backend is in use and package management is enabled on
4483 the target, you can use this variable to set up ``opkg`` in the
4484 target image to point to package feeds on a nominated server. Once
4485 the feed is established, you can perform installations or upgrades
4486 using the package manager at runtime.
4487
Andrew Geisslerf0343792020-11-18 10:42:21 -06004488 :term:`KARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004489 Defines the kernel architecture used when assembling the
4490 configuration. Architectures supported for this release are:
4491
4492 - powerpc
4493 - i386
4494 - x86_64
4495 - arm
4496 - qemu
4497 - mips
4498
Andrew Geissler5f350902021-07-23 13:09:54 -04004499 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004500
Andrew Geisslerf0343792020-11-18 10:42:21 -06004501 :term:`KBRANCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004502 A regular expression used by the build process to explicitly identify
4503 the kernel branch that is validated, patched, and configured during a
4504 build. You must set this variable to ensure the exact kernel branch
4505 you want is being used by the build process.
4506
4507 Values for this variable are set in the kernel's recipe file and the
4508 kernel's append file. For example, if you are using the
4509 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
Andrew Geissler09036742021-06-25 14:25:14 -05004510 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
Andrew Geisslerc926e172021-05-07 16:11:35 -05004511 is set as follows in that kernel recipe file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004512
4513 KBRANCH ?= "standard/base"
4514
4515 This variable is also used from the kernel's append file to identify
4516 the kernel branch specific to a particular machine or target
4517 hardware. Continuing with the previous kernel example, the kernel's
Patrick Williamsac13d5f2023-11-24 18:59:46 -06004518 append file is located in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004519 BSP layer for a given machine. For example, the append file for the
Patrick Williamsac13d5f2023-11-24 18:59:46 -06004520 Beaglebone and generic versions of both 32 and 64-bit IA
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004521 machines (``meta-yocto-bsp``) is named
Patrick Williamsac13d5f2023-11-24 18:59:46 -06004522 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``.
Andrew Geisslerc926e172021-05-07 16:11:35 -05004523 Here are the related statements from that append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004524
Patrick Williamsac13d5f2023-11-24 18:59:46 -06004525 KBRANCH:genericx86 = "v6.1/standard/base"
4526 KBRANCH:genericx86-64 = "v6.1/standard/base"
4527 KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004528
Andrew Geissler09036742021-06-25 14:25:14 -05004529 The :term:`KBRANCH` statements
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004530 identify the kernel branch to use when building for each supported
4531 BSP.
4532
Andrew Geisslerf0343792020-11-18 10:42:21 -06004533 :term:`KBUILD_DEFCONFIG`
Andrew Geissler517393d2023-01-13 08:55:19 -06004534 When used with the :ref:`ref-classes-kernel-yocto`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004535 class, specifies an "in-tree" kernel configuration file for use
4536 during a kernel build.
4537
4538 Typically, when using a ``defconfig`` to configure a kernel during a
4539 build, you place the file in your layer in the same manner as you
4540 would place patch files and configuration fragment files (i.e.
4541 "out-of-tree"). However, if you want to use a ``defconfig`` file that
4542 is part of the kernel tree (i.e. "in-tree"), you can use the
Andrew Geissler09036742021-06-25 14:25:14 -05004543 :term:`KBUILD_DEFCONFIG` variable and append the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004544 :term:`KMACHINE` variable to point to the
4545 ``defconfig`` file.
4546
4547 To use the variable, set it in the append file for your kernel recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05004548 using the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004549
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06004550 KBUILD_DEFCONFIG:<machine> ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004551
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06004552 Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses
Andrew Geisslerc926e172021-05-07 16:11:35 -05004553 a ``defconfig`` file named "bcm2709_defconfig"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004554
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004555 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004556
Andrew Geisslerc926e172021-05-07 16:11:35 -05004557 As an alternative, you can use the following within your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004558
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004559 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004560
4561 For more
Andrew Geissler09036742021-06-25 14:25:14 -05004562 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004563 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004564 section in the Yocto Project Linux Kernel Development Manual.
4565
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004566 :term:`KCONFIG_MODE`
Andrew Geissler517393d2023-01-13 08:55:19 -06004567 When used with the :ref:`ref-classes-kernel-yocto`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004568 class, specifies the kernel configuration values to use for options
4569 not specified in the provided ``defconfig`` file. Valid options are::
4570
4571 KCONFIG_MODE = "alldefconfig"
4572 KCONFIG_MODE = "allnoconfig"
4573
4574 In ``alldefconfig`` mode the options not explicitly specified will be
4575 assigned their Kconfig default value. In ``allnoconfig`` mode the
4576 options not explicitly specified will be disabled in the kernel
4577 config.
4578
Andrew Geissler09036742021-06-25 14:25:14 -05004579 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004580 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
4581 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
4582 in ``${WORKDIR}`` through a meta-layer will be handled in
4583 ``allnoconfig`` mode.
4584
4585 An "in-tree" ``defconfig`` file can be selected via the
Andrew Geissler09036742021-06-25 14:25:14 -05004586 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004587 be explicitly set.
4588
4589 A ``defconfig`` file compatible with ``allnoconfig`` mode can be
4590 generated by copying the ``.config`` file from a working Linux kernel
4591 build, renaming it to ``defconfig`` and placing it into the Linux
Andrew Geissler09036742021-06-25 14:25:14 -05004592 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004593 not need to be explicitly set.
4594
4595 A ``defconfig`` file compatible with ``alldefconfig`` mode can be
4596 generated using the
4597 :ref:`ref-tasks-savedefconfig`
4598 task and placed into the Linux kernel ``${WORKDIR}`` through your
Andrew Geissler09036742021-06-25 14:25:14 -05004599 meta-layer. Explicitely set :term:`KCONFIG_MODE`::
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004600
4601 KCONFIG_MODE = "alldefconfig"
4602
Andrew Geisslerf0343792020-11-18 10:42:21 -06004603 :term:`KERNEL_ALT_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004604 Specifies an alternate kernel image type for creation in addition to
Andrew Geissler87f5cff2022-09-30 13:13:31 -05004605 the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and
4606 :term:`KERNEL_IMAGETYPES` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004607
Andrew Geisslerf0343792020-11-18 10:42:21 -06004608 :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004609 Specifies the name of all of the build artifacts. You can change the
Andrew Geissler09036742021-06-25 14:25:14 -05004610 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004611 variable.
4612
Andrew Geissler09036742021-06-25 14:25:14 -05004613 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
Patrick Williams975a06f2022-10-21 14:42:47 -05004614 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004615 following default value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004616
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004617 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004618
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004619 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX`
Andrew Geissler6ce62a22020-11-30 19:58:47 -06004620 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004621
Andrew Geisslerf0343792020-11-18 10:42:21 -06004622 :term:`KERNEL_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004623 A list of classes defining kernel image types that the
Andrew Geissler517393d2023-01-13 08:55:19 -06004624 :ref:`ref-classes-kernel` class should inherit. You typically
4625 append this variable to enable extended image types. An example is
4626 ":ref:`ref-classes-kernel-fitimage`", which enables
Patrick Williamsb542dec2023-06-09 01:26:37 -05004627 FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``.
Andrew Geissler517393d2023-01-13 08:55:19 -06004628 You can register custom kernel image types with the
4629 :ref:`ref-classes-kernel` class using this variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004630
Patrick Williams96e4b4e2025-02-03 15:49:15 -05004631 :term:`KERNEL_CONSOLE`
4632 The :term:`KERNEL_CONSOLE` variable holds the value of the ``console``
4633 parameter of the kernel command line and can be used in places such as a
4634 ``wks`` description file for :ref:`Wic images <dev-manual/wic:creating
4635 partitioned images using wic>`.
4636
4637 The default value of this variable is extracted from the first console
4638 device and setting in :term:`SERIAL_CONSOLES`. If nothing is found in
4639 :term:`SERIAL_CONSOLES`, the default value is set to ``ttyS0,115200``.
4640
4641 For more information, see the `Kernel command-line documentation
4642 <https://www.kernel.org/doc/html/latest/admin-guide/kernel-parameters.html>`__.
4643
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004644 :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY`
4645 When kernel configuration fragments are missing for some
4646 :term:`KERNEL_FEATURES` specified by layers or BSPs,
4647 building and configuring the kernel stops with an error.
Patrick Williams44b3caf2024-04-12 16:51:14 -05004648
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004649 You can turn these errors into warnings by setting the
4650 following in ``conf/local.conf``::
4651
4652 KERNEL_DANGLING_FEATURES_WARN_ONLY = "1"
Patrick Williams44b3caf2024-04-12 16:51:14 -05004653
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004654 You will still be warned that runtime issues may occur,
4655 but at least the kernel configuration and build process will
4656 be allowed to continue.
4657
Patrick Williams03907ee2022-05-01 06:28:52 -05004658 :term:`KERNEL_DEBUG_TIMESTAMPS`
4659 If set to "1", enables timestamping functionality during building
4660 the kernel. The default is "0" to disable this for reproducibility
4661 reasons.
4662
Patrick Williams975a06f2022-10-21 14:42:47 -05004663 :term:`KERNEL_DEPLOY_DEPEND`
4664 Provides a means of controlling the dependency of an image recipe
4665 on the kernel. The default value is "virtual/kernel:do_deploy",
4666 however for a small initramfs image or other images that do not
4667 need the kernel, this can be set to "" in the image recipe.
4668
Andrew Geisslerf0343792020-11-18 10:42:21 -06004669 :term:`KERNEL_DEVICETREE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004670 Specifies the name of the generated Linux kernel device tree (i.e.
4671 the ``.dtb``) file.
4672
4673 .. note::
4674
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004675 There is legacy support for specifying the full path to the device
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004676 tree. However, providing just the ``.dtb`` file is preferred.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004677
Andrew Geissler517393d2023-01-13 08:55:19 -06004678 In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
4679 class must be inherited.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004680
Patrick Williamsb542dec2023-06-09 01:26:37 -05004681 :term:`KERNEL_DEVICETREE_BUNDLE`
4682 When set to "1", this variable allows to bundle the Linux kernel
4683 and the Device Tree Binary together in a single file.
4684
4685 This feature is currently only supported on the "arm" (32 bit)
4686 architecture.
4687
4688 This variable is set to "0" by default by the
4689 :ref:`ref-classes-kernel-devicetree` class.
4690
Andrew Geisslerf0343792020-11-18 10:42:21 -06004691 :term:`KERNEL_DTB_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004692 The link name of the kernel device tree binary (DTB). This variable
Patrick Williams975a06f2022-10-21 14:42:47 -05004693 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05004694 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004695
4696 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4697
4698 The
4699 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004700 the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004701
4702 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4703
4704 See the :term:`MACHINE` variable for additional
4705 information.
4706
Andrew Geisslerf0343792020-11-18 10:42:21 -06004707 :term:`KERNEL_DTB_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004708 The base name of the kernel device tree binary (DTB). This variable
Patrick Williams975a06f2022-10-21 14:42:47 -05004709 is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05004710 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004711
4712 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4713
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004714 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004715
Patrick Williamsb542dec2023-06-09 01:26:37 -05004716 :term:`KERNEL_DTBDEST`
4717 This variable, used by the :ref:`ref-classes-kernel-devicetree`
4718 class, allows to change the installation directory of the DTB
4719 (Device Tree Binary) files.
4720
4721 It is set by default to "${KERNEL_IMAGEDEST}" by the
4722 :ref:`ref-classes-kernel` class.
4723
4724 :term:`KERNEL_DTBVENDORED`
4725 This variable, used by the :ref:`ref-classes-kernel-devicetree`,
4726 allows to ignore vendor subdirectories when installing DTB
4727 (Device Tree Binary) files, when it is set to "false".
4728
4729 To keep vendor subdirectories, set this variable to "true".
4730
4731 It is set by default to "false" by the :ref:`ref-classes-kernel` class.
4732
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004733 :term:`KERNEL_DTC_FLAGS`
4734 Specifies the ``dtc`` flags that are passed to the Linux kernel build
4735 system when generating the device trees (via ``DTC_FLAGS`` environment
4736 variable).
4737
Andrew Geissler517393d2023-01-13 08:55:19 -06004738 In order to use this variable, the :ref:`ref-classes-kernel-devicetree`
4739 class must be inherited.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004740
Andrew Geisslerf0343792020-11-18 10:42:21 -06004741 :term:`KERNEL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004742 Specifies additional ``make`` command-line arguments the OpenEmbedded
4743 build system passes on when compiling the kernel.
4744
Andrew Geisslerf0343792020-11-18 10:42:21 -06004745 :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004746 Includes additional kernel metadata. In the OpenEmbedded build
4747 system, the default Board Support Packages (BSPs)
4748 :term:`Metadata` is provided through the
4749 :term:`KMACHINE` and :term:`KBRANCH`
Andrew Geissler09036742021-06-25 14:25:14 -05004750 variables. You can use the :term:`KERNEL_FEATURES` variable from within
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004751 the kernel recipe or kernel append file to further add metadata for
4752 all BSPs or specific BSPs.
4753
4754 The metadata you add through this variable includes config fragments
4755 and features descriptions, which usually includes patches as well as
Andrew Geissler09036742021-06-25 14:25:14 -05004756 config fragments. You typically override the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004757 variable for a specific machine. In this way, you can provide
4758 validated, but optional, sets of kernel configurations and features.
4759
4760 For example, the following example from the ``linux-yocto-rt_4.12``
4761 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
4762 as well as "virtio" configurations to all QEMU machines. The last two
Andrew Geisslerc926e172021-05-07 16:11:35 -05004763 statements add specific configurations to targeted machine types::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004764
4765 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
Andrew Geisslerd5838332022-05-27 11:33:10 -05004766 KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}"
4767 KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc"
4768 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
4769 KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004770
Andrew Geisslerf0343792020-11-18 10:42:21 -06004771 :term:`KERNEL_FIT_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004772 The link name of the kernel flattened image tree (FIT) image. This
Patrick Williams975a06f2022-10-21 14:42:47 -05004773 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004774 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004775
4776 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4777
4778 The value of the
4779 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05004780 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004781
4782 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4783
4784 See the :term:`MACHINE` variable for additional
4785 information.
4786
Andrew Geisslerf0343792020-11-18 10:42:21 -06004787 :term:`KERNEL_FIT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004788 The base name of the kernel flattened image tree (FIT) image. This
Patrick Williams975a06f2022-10-21 14:42:47 -05004789 variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004790 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004791
4792 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4793
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004794 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004795
Andrew Geisslerf0343792020-11-18 10:42:21 -06004796 :term:`KERNEL_IMAGE_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004797 The link name for the kernel image. This variable is set in the
Patrick Williams975a06f2022-10-21 14:42:47 -05004798 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004799
4800 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4801
4802 The value of
4803 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05004804 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004805
4806 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4807
4808 See the :term:`MACHINE` variable for additional
4809 information.
4810
Andrew Geisslerf0343792020-11-18 10:42:21 -06004811 :term:`KERNEL_IMAGE_MAXSIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004812 Specifies the maximum size of the kernel image file in kilobytes. If
Andrew Geissler09036742021-06-25 14:25:14 -05004813 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004814 checked against the set value during the
4815 :ref:`ref-tasks-sizecheck` task. The task fails if
4816 the kernel image file is larger than the setting.
4817
Andrew Geissler09036742021-06-25 14:25:14 -05004818 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004819 limited amount of space in which the kernel image must be stored.
4820
4821 By default, this variable is not set, which means the size of the
4822 kernel image is not checked.
4823
Andrew Geisslerf0343792020-11-18 10:42:21 -06004824 :term:`KERNEL_IMAGE_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004825 The base name of the kernel image. This variable is set in the
Patrick Williams975a06f2022-10-21 14:42:47 -05004826 ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004827
4828 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4829
Patrick Williams8e7b46e2023-05-01 14:19:06 -05004830 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004831
Andrew Geisslerf0343792020-11-18 10:42:21 -06004832 :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004833 The type of kernel to build for a device, usually set by the machine
4834 configuration files and defaults to "zImage". This variable is used
4835 when building the kernel and is passed to ``make`` as the target to
4836 build.
4837
Andrew Geissler87f5cff2022-09-30 13:13:31 -05004838 To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`.
4839
4840 :term:`KERNEL_IMAGETYPES`
4841 Lists additional types of kernel images to build for a device in addition
4842 to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the
4843 machine configuration files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004844
Andrew Geisslerf0343792020-11-18 10:42:21 -06004845 :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004846 Lists kernel modules that need to be auto-loaded during boot.
4847
4848 .. note::
4849
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004850 This variable replaces the deprecated :term:`module_autoload`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004851 variable.
4852
Andrew Geissler09036742021-06-25 14:25:14 -05004853 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004854 can be recognized by the kernel recipe or by an out-of-tree kernel
4855 module recipe (e.g. a machine configuration file, a distribution
4856 configuration file, an append file for the recipe, or the recipe
4857 itself).
4858
Andrew Geisslerc926e172021-05-07 16:11:35 -05004859 Specify it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004860
4861 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
4862
Andrew Geissler09036742021-06-25 14:25:14 -05004863 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004864 system to populate the ``/etc/modules-load.d/modname.conf`` file with
4865 the list of modules to be auto-loaded on boot. The modules appear
4866 one-per-line in the file. Here is an example of the most common use
Andrew Geisslerc926e172021-05-07 16:11:35 -05004867 case::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004868
4869 KERNEL_MODULE_AUTOLOAD += "module_name"
4870
4871 For information on how to populate the ``modname.conf`` file with
4872 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable.
4873
Andrew Geisslerf0343792020-11-18 10:42:21 -06004874 :term:`KERNEL_MODULE_PROBECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004875 Provides a list of modules for which the OpenEmbedded build system
4876 expects to find ``module_conf_``\ modname values that specify
4877 configuration for each of the modules. For information on how to
4878 provide those module configurations, see the
4879 :term:`module_conf_* <module_conf>` variable.
4880
Patrick Williamsb542dec2023-06-09 01:26:37 -05004881 :term:`KERNEL_PACKAGE_NAME`
4882 Specifies the base name of the kernel packages, such as "kernel"
4883 in the kernel packages such as "kernel-modules", "kernel-image" and
4884 "kernel-dbg".
4885
4886 The default value for this variable is set to "kernel" by the
4887 :ref:`ref-classes-kernel` class.
4888
Andrew Geisslerf0343792020-11-18 10:42:21 -06004889 :term:`KERNEL_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004890 The location of the kernel sources. This variable is set to the value
Andrew Geissler517393d2023-01-13 08:55:19 -06004891 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4892 class. For information on how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004893 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004894 section in the Yocto Project Linux Kernel Development Manual.
4895
4896 To help maximize compatibility with out-of-tree drivers used to build
4897 modules, the OpenEmbedded build system also recognizes and uses the
4898 :term:`KERNEL_SRC` variable, which is identical to
Andrew Geissler09036742021-06-25 14:25:14 -05004899 the :term:`KERNEL_PATH` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004900 used by external Makefiles to point to the kernel source directory.
4901
Andrew Geisslerf0343792020-11-18 10:42:21 -06004902 :term:`KERNEL_SRC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004903 The location of the kernel sources. This variable is set to the value
Andrew Geissler517393d2023-01-13 08:55:19 -06004904 of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module`
4905 class. For information on how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004906 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004907 section in the Yocto Project Linux Kernel Development Manual.
4908
4909 To help maximize compatibility with out-of-tree drivers used to build
4910 modules, the OpenEmbedded build system also recognizes and uses the
4911 :term:`KERNEL_PATH` variable, which is identical
Andrew Geissler09036742021-06-25 14:25:14 -05004912 to the :term:`KERNEL_SRC` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004913 used by external Makefiles to point to the kernel source directory.
4914
Patrick Williamsac13d5f2023-11-24 18:59:46 -06004915 :term:`KERNEL_STRIP`
4916 Allows to specific which ``strip`` command to use to strip the kernel
4917 binary, typically either GNU binutils ``strip`` or ``llvm-strip``.
4918
Andrew Geisslerf0343792020-11-18 10:42:21 -06004919 :term:`KERNEL_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004920 Specifies the version of the kernel as extracted from ``version.h``
4921 or ``utsrelease.h`` within the kernel sources. Effects of setting
Andrew Geissler595f6302022-01-24 19:11:47 +00004922 this variable do not take effect until the kernel has been
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004923 configured. Consequently, attempting to refer to this variable in
4924 contexts prior to configuration will not work.
4925
Andrew Geisslerf0343792020-11-18 10:42:21 -06004926 :term:`KERNELDEPMODDEPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004927 Specifies whether the data referenced through
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004928 :term:`PKGDATA_DIR` is needed or not.
Andrew Geissler09036742021-06-25 14:25:14 -05004929 :term:`KERNELDEPMODDEPEND` does not control whether or not that data
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004930 exists, but simply whether or not it is used. If you do not need to
Andrew Geissler09036742021-06-25 14:25:14 -05004931 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
Patrick Williams2194f502022-10-16 14:26:09 -05004932 :term:`Initramfs` recipe. Setting the variable there when the data is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004933 needed avoids a potential dependency loop.
4934
Andrew Geisslerf0343792020-11-18 10:42:21 -06004935 :term:`KFEATURE_DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004936 Provides a short description of a configuration fragment. You use
4937 this variable in the ``.scc`` file that describes a configuration
4938 fragment file. Here is the variable used in a file named ``smp.scc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004939 to describe SMP being enabled::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004940
4941 define KFEATURE_DESCRIPTION "Enable SMP"
4942
Andrew Geisslerf0343792020-11-18 10:42:21 -06004943 :term:`KMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004944 The machine as known by the kernel. Sometimes the machine name used
4945 by the kernel does not match the machine name used by the
4946 OpenEmbedded build system. For example, the machine name that the
4947 OpenEmbedded build system understands as ``core2-32-intel-common``
4948 goes by a different name in the Linux Yocto kernel. The kernel
4949 understands that machine as ``intel-core2-32``. For cases like these,
Andrew Geissler09036742021-06-25 14:25:14 -05004950 the :term:`KMACHINE` variable maps the kernel machine name to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004951 OpenEmbedded build system machine name.
4952
4953 These mappings between different names occur in the Yocto Linux
4954 Kernel's ``meta`` branch. As an example take a look in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004955 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004956
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004957 LINUX_VERSION:core2-32-intel-common = "3.19.0"
4958 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
4959 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
4960 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
4961 KMACHINE:core2-32-intel-common = "intel-core2-32"
4962 KBRANCH:core2-32-intel-common = "standard/base"
Andrew Geisslerd5838332022-05-27 11:33:10 -05004963 KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004964
Andrew Geissler09036742021-06-25 14:25:14 -05004965 The :term:`KMACHINE` statement says
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004966 that the kernel understands the machine name as "intel-core2-32".
4967 However, the OpenEmbedded build system understands the machine as
4968 "core2-32-intel-common".
4969
Andrew Geisslerf0343792020-11-18 10:42:21 -06004970 :term:`KTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004971 Defines the kernel type to be used in assembling the configuration.
4972 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06004973 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004974 section in the
4975 Yocto Project Linux Kernel Development Manual for more information on
4976 kernel types.
4977
Andrew Geissler09036742021-06-25 14:25:14 -05004978 You define the :term:`KTYPE` variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004979 :ref:`kernel-dev/advanced:bsp descriptions`. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004980 value you use must match the value used for the
4981 :term:`LINUX_KERNEL_TYPE` value used by the
4982 kernel recipe.
4983
Andrew Geisslerf0343792020-11-18 10:42:21 -06004984 :term:`LABELS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004985 Provides a list of targets for automatic configuration.
4986
Andrew Geissler517393d2023-01-13 08:55:19 -06004987 See the :ref:`ref-classes-grub-efi` class for more
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004988 information on how this variable is used.
4989
Andrew Geisslerf0343792020-11-18 10:42:21 -06004990 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004991 Lists the layers, separated by spaces, on which this recipe depends.
4992 Optionally, you can specify a specific layer version for a dependency
Andrew Geisslerc926e172021-05-07 16:11:35 -05004993 by adding it to the end of the layer name. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004994
4995 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4996
4997 In this previous example,
4998 version 3 of "anotherlayer" is compared against
4999 :term:`LAYERVERSION`\ ``_anotherlayer``.
5000
5001 An error is produced if any dependency is missing or the version
5002 numbers (if specified) do not match exactly. This variable is used in
5003 the ``conf/layer.conf`` file and must be suffixed with the name of
5004 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
5005
Andrew Geisslerf0343792020-11-18 10:42:21 -06005006 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005007 When used inside the ``layer.conf`` configuration file, this variable
5008 provides the path of the current layer. This variable is not
5009 available outside of ``layer.conf`` and references are expanded
5010 immediately when parsing of the file completes.
5011
Andrew Geissler517393d2023-01-13 08:55:19 -06005012 :term:`LAYERDIR_RE`
5013 See :term:`bitbake:LAYERDIR_RE` in the BitBake manual.
5014
Andrew Geisslerf0343792020-11-18 10:42:21 -06005015 :term:`LAYERRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005016 Lists the layers, separated by spaces, recommended for use with this
5017 layer.
5018
5019 Optionally, you can specify a specific layer version for a
5020 recommendation by adding the version to the end of the layer name.
Andrew Geisslerc926e172021-05-07 16:11:35 -05005021 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005022
5023 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
5024
5025 In this previous example, version 3 of "anotherlayer" is compared
5026 against ``LAYERVERSION_anotherlayer``.
5027
5028 This variable is used in the ``conf/layer.conf`` file and must be
5029 suffixed with the name of the specific layer (e.g.
5030 ``LAYERRECOMMENDS_mylayer``).
5031
Andrew Geisslerf0343792020-11-18 10:42:21 -06005032 :term:`LAYERSERIES_COMPAT`
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05005033 See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005034
Andrew Geisslerf0343792020-11-18 10:42:21 -06005035 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005036 Optionally specifies the version of a layer as a single number. You
5037 can use this within :term:`LAYERDEPENDS` for
5038 another layer in order to depend on a specific version of the layer.
5039 This variable is used in the ``conf/layer.conf`` file and must be
5040 suffixed with the name of the specific layer (e.g.
5041 ``LAYERVERSION_mylayer``).
5042
Andrew Geisslerf0343792020-11-18 10:42:21 -06005043 :term:`LD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005044 The minimal command and arguments used to run the linker.
5045
Andrew Geisslerf0343792020-11-18 10:42:21 -06005046 :term:`LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005047 Specifies the flags to pass to the linker. This variable is exported
5048 to an environment variable and thus made visible to the software
5049 being built during the compilation step.
5050
Andrew Geissler09036742021-06-25 14:25:14 -05005051 Default initialization for :term:`LDFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005052 being built:
5053
5054 - :term:`TARGET_LDFLAGS` when building for the
5055 target
5056
5057 - :term:`BUILD_LDFLAGS` when building for the
5058 build host (i.e. ``-native``)
5059
5060 - :term:`BUILDSDK_LDFLAGS` when building for
5061 an SDK (i.e. ``nativesdk-``)
5062
Andrew Geisslerf0343792020-11-18 10:42:21 -06005063 :term:`LEAD_SONAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005064 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
Andrew Geissler517393d2023-01-13 08:55:19 -06005065 that the :ref:`ref-classes-debian` class applies its
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005066 naming policy to given a recipe that packages multiple libraries.
5067
Andrew Geissler517393d2023-01-13 08:55:19 -06005068 This variable works in conjunction with the :ref:`ref-classes-debian`
5069 class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005070
Andrew Geisslerf0343792020-11-18 10:42:21 -06005071 :term:`LIC_FILES_CHKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005072 Checksums of the license text in the recipe source code.
5073
5074 This variable tracks changes in license text of the source code
5075 files. If the license text is changed, it will trigger a build
5076 failure, which gives the developer an opportunity to review any
5077 license change.
5078
5079 This variable must be defined for all recipes (unless
5080 :term:`LICENSE` is set to "CLOSED").
5081
Andrew Geissler517393d2023-01-13 08:55:19 -06005082 For more information, see the ":ref:`dev-manual/licenses:tracking license changes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005083 section in the Yocto Project Development Tasks Manual.
5084
Andrew Geisslerf0343792020-11-18 10:42:21 -06005085 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005086 The list of source licenses for the recipe. Follow these rules:
5087
5088 - Do not use spaces within individual license names.
5089
5090 - Separate license names using \| (pipe) when there is a choice
5091 between licenses.
5092
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005093 - Separate license names using & (ampersand) when there are
5094 multiple licenses for different parts of the source.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005095
5096 - You can use spaces between license names.
5097
5098 - For standard licenses, use the names of the files in
5099 ``meta/files/common-licenses/`` or the
5100 :term:`SPDXLICENSEMAP` flag names defined in
5101 ``meta/conf/licenses.conf``.
5102
Andrew Geisslerc926e172021-05-07 16:11:35 -05005103 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005104
Andrew Geissler9aee5002022-03-30 16:27:02 +00005105 LICENSE = "LGPL-2.1-only | GPL-3.0-only"
5106 LICENSE = "MPL-1.0 & LGPL-2.1-only"
5107 LICENSE = "GPL-2.0-or-later"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005108
5109 The first example is from the
5110 recipes for Qt, which the user may choose to distribute under either
5111 the LGPL version 2.1 or GPL version 3. The second example is from
5112 Cairo where two licenses cover different parts of the source code.
5113 The final example is from ``sysstat``, which presents a single
5114 license.
5115
5116 You can also specify licenses on a per-package basis to handle
5117 situations where components of the output have different licenses.
5118 For example, a piece of software whose code is licensed under GPLv2
5119 but has accompanying documentation licensed under the GNU Free
Andrew Geisslerc926e172021-05-07 16:11:35 -05005120 Documentation License 1.2 could be specified as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005121
Andrew Geissler9aee5002022-03-30 16:27:02 +00005122 LICENSE = "GFDL-1.2 & GPL-2.0-only"
5123 LICENSE:${PN} = "GPL-2.0.only"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005124 LICENSE:${PN}-doc = "GFDL-1.2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005125
Andrew Geisslerf0343792020-11-18 10:42:21 -06005126 :term:`LICENSE_CREATE_PACKAGE`
Andrew Geissler09036742021-06-25 14:25:14 -05005127 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005128 build system to create an extra package (i.e.
5129 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
5130 those packages to the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005131 :term:`RRECOMMENDS`\ ``:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005132
5133 The ``${PN}-lic`` package installs a directory in
5134 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
5135 name, and installs files in that directory that contain license and
5136 copyright information (i.e. copies of the appropriate license files
5137 from ``meta/common-licenses`` that match the licenses specified in
5138 the :term:`LICENSE` variable of the recipe metadata
5139 and copies of files marked in
5140 :term:`LIC_FILES_CHKSUM` as containing
5141 license text).
5142
5143 For related information on providing license text, see the
5144 :term:`COPY_LIC_DIRS` variable, the
5145 :term:`COPY_LIC_MANIFEST` variable, and the
Andrew Geissler517393d2023-01-13 08:55:19 -06005146 ":ref:`dev-manual/licenses:providing license text`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005147 section in the Yocto Project Development Tasks Manual.
5148
Andrew Geisslerf0343792020-11-18 10:42:21 -06005149 :term:`LICENSE_FLAGS`
Andrew Geissler595f6302022-01-24 19:11:47 +00005150 Specifies additional flags for a recipe you must allow through
Andrew Geissler9aee5002022-03-30 16:27:02 +00005151 :term:`LICENSE_FLAGS_ACCEPTED` in
Andrew Geissler595f6302022-01-24 19:11:47 +00005152 order for the recipe to be built. When providing multiple flags,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005153 separate them with spaces.
5154
5155 This value is independent of :term:`LICENSE` and is
5156 typically used to mark recipes that might require additional licenses
5157 in order to be used in a commercial product. For more information,
5158 see the
Andrew Geissler517393d2023-01-13 08:55:19 -06005159 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005160 section in the Yocto Project Development Tasks Manual.
5161
Andrew Geissler9aee5002022-03-30 16:27:02 +00005162 :term:`LICENSE_FLAGS_ACCEPTED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005163 Lists license flags that when specified in
5164 :term:`LICENSE_FLAGS` within a recipe should not
Andrew Geissler595f6302022-01-24 19:11:47 +00005165 prevent that recipe from being built. For more information, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06005166 ":ref:`dev-manual/licenses:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005167 section in the Yocto Project Development Tasks Manual.
5168
Andrew Geissler220dafd2023-10-04 10:18:08 -05005169 :term:`LICENSE_FLAGS_DETAILS`
5170 Adds details about a flag in :term:`LICENSE_FLAGS`. This way,
5171 if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`,
5172 the error message will be more informative, containing the specified
5173 extra details.
5174
5175 For example, a recipe with an EULA may set::
5176
5177 LICENSE_FLAGS = "FooBar-EULA"
5178 LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula."
5179
5180 If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the
5181 error message is more useful::
5182
5183 Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED.
5184 For further details, see https://example.com/eula.
5185
Andrew Geisslerf0343792020-11-18 10:42:21 -06005186 :term:`LICENSE_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005187 Path to additional licenses used during the build. By default, the
Andrew Geissler09036742021-06-25 14:25:14 -05005188 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005189 directory that holds common license text used during the build. The
Andrew Geissler09036742021-06-25 14:25:14 -05005190 :term:`LICENSE_PATH` variable allows you to extend that location to other
Andrew Geisslerc926e172021-05-07 16:11:35 -05005191 areas that have additional licenses::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005192
5193 LICENSE_PATH += "path-to-additional-common-licenses"
5194
Andrew Geisslerf0343792020-11-18 10:42:21 -06005195 :term:`LINUX_KERNEL_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005196 Defines the kernel type to be used in assembling the configuration.
5197 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06005198 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005199 section in the
5200 Yocto Project Linux Kernel Development Manual for more information on
5201 kernel types.
5202
Andrew Geissler09036742021-06-25 14:25:14 -05005203 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005204 "standard". Together with :term:`KMACHINE`, the
Andrew Geissler09036742021-06-25 14:25:14 -05005205 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005206 the kernel tools to find the appropriate description within the
5207 kernel :term:`Metadata` with which to build out the sources
5208 and configuration.
5209
Andrew Geisslerf0343792020-11-18 10:42:21 -06005210 :term:`LINUX_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005211 The Linux version from ``kernel.org`` on which the Linux kernel image
5212 being built using the OpenEmbedded build system is based. You define
5213 this variable in the kernel recipe. For example, the
5214 ``linux-yocto-3.4.bb`` kernel recipe found in
Andrew Geisslerc926e172021-05-07 16:11:35 -05005215 ``meta/recipes-kernel/linux`` defines the variables as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005216
5217 LINUX_VERSION ?= "3.4.24"
5218
Andrew Geissler09036742021-06-25 14:25:14 -05005219 The :term:`LINUX_VERSION` variable is used to define :term:`PV`
Andrew Geisslerc926e172021-05-07 16:11:35 -05005220 for the recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005221
Patrick Williams96e4b4e2025-02-03 15:49:15 -05005222 PV = "${LINUX_VERSION}+git"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005223
Andrew Geisslerf0343792020-11-18 10:42:21 -06005224 :term:`LINUX_VERSION_EXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005225 A string extension compiled into the version string of the Linux
5226 kernel built with the OpenEmbedded build system. You define this
5227 variable in the kernel recipe. For example, the linux-yocto kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05005228 recipes all define the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005229
5230 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
5231
5232 Defining this variable essentially sets the Linux kernel
5233 configuration item ``CONFIG_LOCALVERSION``, which is visible through
5234 the ``uname`` command. Here is an example that shows the extension
Andrew Geisslerc926e172021-05-07 16:11:35 -05005235 assuming it was set as previously shown::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005236
5237 $ uname -r
5238 3.7.0-rc8-custom
5239
Andrew Geisslerf0343792020-11-18 10:42:21 -06005240 :term:`LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005241 Specifies the directory to which the OpenEmbedded build system writes
5242 overall log files. The default directory is ``${TMPDIR}/log``.
5243
5244 For the directory containing logs specific to each task, see the
5245 :term:`T` variable.
5246
Andrew Geisslerf0343792020-11-18 10:42:21 -06005247 :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005248 Specifies the target device for which the image is built. You define
Andrew Geissler09036742021-06-25 14:25:14 -05005249 :term:`MACHINE` in the ``local.conf`` file found in the
5250 :term:`Build Directory`. By default, :term:`MACHINE` is set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005251 "qemux86", which is an x86-based architecture machine to be emulated
Andrew Geisslerc926e172021-05-07 16:11:35 -05005252 using QEMU::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005253
5254 MACHINE ?= "qemux86"
5255
5256 The variable corresponds to a machine configuration file of the same
5257 name, through which machine-specific configurations are set. Thus,
Andrew Geissler09036742021-06-25 14:25:14 -05005258 when :term:`MACHINE` is set to "qemux86", the corresponding
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005259 ``qemux86.conf`` machine configuration file can be found in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005260 the :term:`Source Directory` in
5261 ``meta/conf/machine``.
5262
5263 The list of machines supported by the Yocto Project as shipped
Andrew Geisslerc926e172021-05-07 16:11:35 -05005264 include the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005265
5266 MACHINE ?= "qemuarm"
5267 MACHINE ?= "qemuarm64"
5268 MACHINE ?= "qemumips"
5269 MACHINE ?= "qemumips64"
5270 MACHINE ?= "qemuppc"
5271 MACHINE ?= "qemux86"
5272 MACHINE ?= "qemux86-64"
5273 MACHINE ?= "genericx86"
5274 MACHINE ?= "genericx86-64"
5275 MACHINE ?= "beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005276
5277 The last five are Yocto Project reference hardware
5278 boards, which are provided in the ``meta-yocto-bsp`` layer.
5279
5280 .. note::
5281
5282 Adding additional Board Support Package (BSP) layers to your
Andrew Geissler09036742021-06-25 14:25:14 -05005283 configuration adds new possible settings for :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005284
Andrew Geisslerf0343792020-11-18 10:42:21 -06005285 :term:`MACHINE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005286 Specifies the name of the machine-specific architecture. This
5287 variable is set automatically from :term:`MACHINE` or
5288 :term:`TUNE_PKGARCH`. You should not hand-edit
Andrew Geissler09036742021-06-25 14:25:14 -05005289 the :term:`MACHINE_ARCH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005290
Andrew Geisslerf0343792020-11-18 10:42:21 -06005291 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005292 A list of required machine-specific packages to install as part of
5293 the image being built. The build process depends on these packages
5294 being present. Furthermore, because this is a "machine-essential"
5295 variable, the list of packages are essential for the machine to boot.
5296 The impact of this variable affects images based on
5297 ``packagegroup-core-boot``, including the ``core-image-minimal``
5298 image.
5299
5300 This variable is similar to the
Andrew Geissler09036742021-06-25 14:25:14 -05005301 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005302 that the image being built has a build dependency on the variable's
5303 list of packages. In other words, the image will not build if a file
5304 in this list is not found.
5305
5306 As an example, suppose the machine for which you are building
5307 requires ``example-init`` to be run during boot to initialize the
5308 hardware. In this case, you would use the following in the machine's
Andrew Geisslerc926e172021-05-07 16:11:35 -05005309 ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005310
5311 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
5312
Andrew Geisslerf0343792020-11-18 10:42:21 -06005313 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005314 A list of recommended machine-specific packages to install as part of
5315 the image being built. The build process does not depend on these
5316 packages being present. However, because this is a
5317 "machine-essential" variable, the list of packages are essential for
5318 the machine to boot. The impact of this variable affects images based
5319 on ``packagegroup-core-boot``, including the ``core-image-minimal``
5320 image.
5321
Andrew Geissler09036742021-06-25 14:25:14 -05005322 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005323 variable with the exception that the image being built does not have
5324 a build dependency on the variable's list of packages. In other
5325 words, the image will still build if a package in this list is not
5326 found. Typically, this variable is used to handle essential kernel
5327 modules, whose functionality may be selected to be built into the
5328 kernel rather than as a module, in which case a package will not be
5329 produced.
5330
5331 Consider an example where you have a custom kernel where a specific
5332 touchscreen driver is required for the machine to be usable. However,
5333 the driver can be built as a module or into the kernel depending on
5334 the kernel configuration. If the driver is built as a module, you
5335 want it to be installed. But, when the driver is built into the
5336 kernel, you still want the build to succeed. This variable sets up a
5337 "recommends" relationship so that in the latter case, the build will
5338 not fail due to the missing package. To accomplish this, assuming the
5339 package for the module was called ``kernel-module-ab123``, you would
Andrew Geisslerc926e172021-05-07 16:11:35 -05005340 use the following in the machine's ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005341
5342 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
5343
5344 .. note::
5345
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005346 In this example, the ``kernel-module-ab123`` recipe needs to
5347 explicitly set its :term:`PACKAGES` variable to ensure that BitBake
5348 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to
5349 satisfy the dependency.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005350
5351 Some examples of these machine essentials are flash, screen,
5352 keyboard, mouse, or touchscreen drivers (depending on the machine).
5353
Andrew Geisslerf0343792020-11-18 10:42:21 -06005354 :term:`MACHINE_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005355 A list of machine-specific packages to install as part of the image
5356 being built that are not essential for the machine to boot. However,
5357 the build process for more fully-featured images depends on the
5358 packages being present.
5359
5360 This variable affects all images based on ``packagegroup-base``,
5361 which does not include the ``core-image-minimal`` or
5362 ``core-image-full-cmdline`` images.
5363
Andrew Geissler09036742021-06-25 14:25:14 -05005364 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005365 with the exception that the image being built has a build dependency
5366 on the variable's list of packages. In other words, the image will
5367 not build if a file in this list is not found.
5368
5369 An example is a machine that has WiFi capability but is not essential
5370 for the machine to boot the image. However, if you are building a
5371 more fully-featured image, you want to enable the WiFi. The package
5372 containing the firmware for the WiFi hardware is always expected to
5373 exist, so it is acceptable for the build process to depend upon
5374 finding the package. In this case, assuming the package for the
5375 firmware was called ``wifidriver-firmware``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005376 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005377
5378 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
5379
Andrew Geisslerf0343792020-11-18 10:42:21 -06005380 :term:`MACHINE_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005381 A list of machine-specific packages to install as part of the image
5382 being built that are not essential for booting the machine. The image
5383 being built has no build dependency on this list of packages.
5384
5385 This variable affects only images based on ``packagegroup-base``,
5386 which does not include the ``core-image-minimal`` or
5387 ``core-image-full-cmdline`` images.
5388
Andrew Geissler09036742021-06-25 14:25:14 -05005389 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005390 with the exception that the image being built does not have a build
5391 dependency on the variable's list of packages. In other words, the
5392 image will build if a file in this list is not found.
5393
5394 An example is a machine that has WiFi capability but is not essential
5395 For the machine to boot the image. However, if you are building a
5396 more fully-featured image, you want to enable WiFi. In this case, the
5397 package containing the WiFi kernel module will not be produced if the
5398 WiFi driver is built into the kernel, in which case you still want
5399 the build to succeed instead of failing as a result of the package
5400 not being found. To accomplish this, assuming the package for the
5401 module was called ``kernel-module-examplewifi``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005402 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005403
5404 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
5405
Andrew Geisslerf0343792020-11-18 10:42:21 -06005406 :term:`MACHINE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005407 Specifies the list of hardware features the
5408 :term:`MACHINE` is capable of supporting. For related
5409 information on enabling features, see the
5410 :term:`DISTRO_FEATURES`,
5411 :term:`COMBINED_FEATURES`, and
5412 :term:`IMAGE_FEATURES` variables.
5413
5414 For a list of hardware features supported by the Yocto Project as
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005415 shipped, see the ":ref:`ref-features-machine`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005416
Andrew Geisslerf0343792020-11-18 10:42:21 -06005417 :term:`MACHINE_FEATURES_BACKFILL`
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05005418 A list of space-separated features to be added to
5419 :term:`MACHINE_FEATURES` if not also present in
Andrew Geissler09036742021-06-25 14:25:14 -05005420 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005421
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05005422 This variable is set in the ``meta/conf/bitbake.conf`` file. It is not
5423 intended to be user-configurable. It is best to just reference the
5424 variable to see which machine features are being
5425 :ref:`backfilled <ref-features-backfill>` for all machine configurations.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005426
Andrew Geisslerf0343792020-11-18 10:42:21 -06005427 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05005428 A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL`
5429 that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added
5430 to :term:`MACHINE_FEATURES`) during the build.
5431
5432 This corresponds to an opt-out mechanism. When new default machine
5433 features are introduced, machine definition maintainers can review
5434 (`consider`) them and decide to exclude them from the
5435 :ref:`backfilled <ref-features-backfill>` features. Therefore, the
5436 combination of :term:`MACHINE_FEATURES_BACKFILL` and
5437 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to
5438 add new default features without breaking existing machine definitions.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005439
Andrew Geisslerf0343792020-11-18 10:42:21 -06005440 :term:`MACHINEOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005441 A colon-separated list of overrides that apply to the current
5442 machine. By default, this list includes the value of
5443 :term:`MACHINE`.
5444
Andrew Geissler09036742021-06-25 14:25:14 -05005445 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005446 should apply to a machine. For example, all machines emulated in QEMU
5447 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
5448 ``meta/conf/machine/include/qemu.inc`` that prepends the following
Andrew Geissler09036742021-06-25 14:25:14 -05005449 override to :term:`MACHINEOVERRIDES`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005450
5451 MACHINEOVERRIDES =. "qemuall:"
5452
5453 This
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005454 override allows variables to be overridden for all machines emulated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005455 in QEMU, like in the following example from the ``connman-conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05005456 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005457
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005458 SRC_URI:append:qemuall = " file://wired.config \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005459 file://wired-setup \
5460 "
5461
5462 The underlying mechanism behind
Andrew Geissler09036742021-06-25 14:25:14 -05005463 :term:`MACHINEOVERRIDES` is simply that it is included in the default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005464 value of :term:`OVERRIDES`.
5465
Andrew Geisslerf0343792020-11-18 10:42:21 -06005466 :term:`MAINTAINER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005467 The email address of the distribution maintainer.
5468
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06005469 :term:`MESON_BUILDTYPE`
5470 Value of the Meson ``--buildtype`` argument used by the
5471 :ref:`ref-classes-meson` class. It defaults to ``debug`` if
5472 :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise.
5473
5474 See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__
5475 for the values you could set in a recipe. Values such as ``plain``,
5476 ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow
5477 you to specify the inclusion of debugging symbols and the compiler
5478 optimizations (none, performance or size).
5479
Patrick Williamsac13d5f2023-11-24 18:59:46 -06005480 :term:`MESON_TARGET`
5481 A variable for the :ref:`ref-classes-meson` class, allowing to choose
5482 a Meson target to build in :ref:`ref-tasks-compile`. Otherwise, the
5483 default targets are built.
5484
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005485 :term:`METADATA_BRANCH`
5486 The branch currently checked out for the OpenEmbedded-Core layer (path
5487 determined by :term:`COREBASE`).
5488
5489 :term:`METADATA_REVISION`
5490 The revision currently checked out for the OpenEmbedded-Core layer (path
5491 determined by :term:`COREBASE`).
5492
Patrick Williams7784c422022-11-17 07:29:11 -06005493 :term:`MIME_XDG_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -06005494 The current implementation of the :ref:`ref-classes-mime-xdg`
Patrick Williams7784c422022-11-17 07:29:11 -06005495 class cannot detect ``.desktop`` files installed through absolute
5496 symbolic links. Use this setting to make the class create post-install
5497 and post-remove scripts for these packages anyway, to invoke the
5498 ``update-destop-database`` command.
5499
Andrew Geisslerf0343792020-11-18 10:42:21 -06005500 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005501 Specifies additional paths from which the OpenEmbedded build system
5502 gets source code. When the build system searches for source code, it
5503 first tries the local download directory. If that location fails, the
5504 build system tries locations defined by
5505 :term:`PREMIRRORS`, the upstream source, and then
Andrew Geissler09036742021-06-25 14:25:14 -05005506 locations specified by :term:`MIRRORS` in that order.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005507
Patrick Williamsac13d5f2023-11-24 18:59:46 -06005508 The default value for :term:`MIRRORS` is defined in the
5509 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005510
Andrew Geisslerf0343792020-11-18 10:42:21 -06005511 :term:`MLPREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005512 Specifies a prefix has been added to :term:`PN` to create a
5513 special version of a recipe or package (i.e. a Multilib version). The
5514 variable is used in places where the prefix needs to be added to or
Andrew Geisslerc5535c92023-01-27 16:10:19 -06005515 removed from a name (e.g. the :term:`BPN` variable).
Andrew Geissler09036742021-06-25 14:25:14 -05005516 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005517
5518 .. note::
5519
Andrew Geissler517393d2023-01-13 08:55:19 -06005520 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation
5521 is historical and comes from a time when ":ref:`ref-classes-nativesdk`"
5522 was a suffix rather than a prefix on the recipe name. When
5523 ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense
5524 to set :term:`MLPREFIX` for it as well.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005525
Andrew Geissler09036742021-06-25 14:25:14 -05005526 To help understand when :term:`MLPREFIX` might be needed, consider when
Andrew Geissler517393d2023-01-13 08:55:19 -06005527 :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk`
5528 version of a recipe in addition to the target version. If that recipe
5529 declares build-time dependencies on tasks in other recipes by using
5530 :term:`DEPENDS`, then a dependency on "foo" will automatically get
5531 rewritten to a dependency on "nativesdk-foo". However, dependencies like
5532 the following will not get rewritten automatically::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005533
5534 do_foo[depends] += "recipe:do_foo"
5535
5536 If you want such a dependency to also get transformed, you can do the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005537 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005538
5539 do_foo[depends] += "${MLPREFIX}recipe:do_foo"
5540
Andrew Geissler09036742021-06-25 14:25:14 -05005541 :term:`module_autoload`
5542 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geissler5f350902021-07-23 13:09:54 -04005543 variable. You should replace all occurrences of :term:`module_autoload`
Andrew Geissler09036742021-06-25 14:25:14 -05005544 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005545
5546 module_autoload_rfcomm = "rfcomm"
5547
Andrew Geisslerc926e172021-05-07 16:11:35 -05005548 should now be replaced with::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005549
5550 KERNEL_MODULE_AUTOLOAD += "rfcomm"
5551
5552 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
5553
Andrew Geissler09036742021-06-25 14:25:14 -05005554 :term:`module_conf`
Patrick Williams2390b1b2022-11-03 13:47:49 -05005555 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005556 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
5557 file.
5558
5559 You can use this variable anywhere that it can be recognized by the
5560 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
5561 configuration file, a distribution configuration file, an append file
5562 for the recipe, or the recipe itself). If you use this variable, you
5563 must also be sure to list the module name in the
Andrew Geissler595f6302022-01-24 19:11:47 +00005564 :term:`KERNEL_MODULE_PROBECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005565 variable.
5566
Andrew Geisslerc926e172021-05-07 16:11:35 -05005567 Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005568
5569 module_conf_module_name = "modprobe.d-syntax"
5570
5571 You must use the kernel module name override.
5572
5573 Run ``man modprobe.d`` in the shell to find out more information on
Andrew Geissler5f350902021-07-23 13:09:54 -04005574 the exact syntax you want to provide with :term:`module_conf`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005575
Andrew Geissler5f350902021-07-23 13:09:54 -04005576 Including :term:`module_conf` causes the OpenEmbedded build system to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005577 populate the ``/etc/modprobe.d/modname.conf`` file with
5578 ``modprobe.d`` syntax lines. Here is an example that adds the options
Andrew Geisslerc926e172021-05-07 16:11:35 -05005579 ``arg1`` and ``arg2`` to a module named ``mymodule``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005580
5581 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
5582
5583 For information on how to specify kernel modules to auto-load on
5584 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable.
5585
Andrew Geisslerf0343792020-11-18 10:42:21 -06005586 :term:`MODULE_TARBALL_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005587 Controls creation of the ``modules-*.tgz`` file. Set this variable to
5588 "0" to disable creation of this file, which contains all of the
5589 kernel modules resulting from a kernel build.
5590
Andrew Geisslerf0343792020-11-18 10:42:21 -06005591 :term:`MODULE_TARBALL_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005592 The link name of the kernel module tarball. This variable is set in
Patrick Williams975a06f2022-10-21 14:42:47 -05005593 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005594
5595 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
5596
5597 The value
5598 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005599 same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005600
5601 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
5602
5603 See the :term:`MACHINE` variable for additional information.
5604
Andrew Geisslerf0343792020-11-18 10:42:21 -06005605 :term:`MODULE_TARBALL_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005606 The base name of the kernel module tarball. This variable is set in
Patrick Williams975a06f2022-10-21 14:42:47 -05005607 the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005608
5609 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
5610
Patrick Williams8e7b46e2023-05-01 14:19:06 -05005611 See :term:`KERNEL_ARTIFACT_NAME` for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005612
Patrick Williams975a06f2022-10-21 14:42:47 -05005613 :term:`MOUNT_BASE`
5614 On non-systemd systems (where ``udev-extraconf`` is being used),
5615 specifies the base directory for auto-mounting filesystems. The
5616 default value is "/run/media".
5617
Andrew Geisslerf0343792020-11-18 10:42:21 -06005618 :term:`MULTIMACH_TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005619 Uniquely identifies the type of the target system for which packages
5620 are being built. This variable allows output for different types of
5621 target systems to be put into different subdirectories of the same
5622 output directory.
5623
Andrew Geisslerc926e172021-05-07 16:11:35 -05005624 The default value of this variable is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005625
5626 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
5627
Andrew Geissler517393d2023-01-13 08:55:19 -06005628 Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the
Andrew Geissler09036742021-06-25 14:25:14 -05005629 :term:`MULTIMACH_TARGET_SYS` value.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005630
5631 See the :term:`STAMP` variable for an example. See the
5632 :term:`STAGING_DIR_TARGET` variable for more information.
5633
Andrew Geisslerf0343792020-11-18 10:42:21 -06005634 :term:`NATIVELSBSTRING`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005635 A string identifying the host distribution. Strings consist of the
5636 host distributor ID followed by the release, as reported by the
5637 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
5638 example, when running a build on Ubuntu 12.10, the value is
5639 "Ubuntu-12.10". If this information is unable to be determined, the
5640 value resolves to "Unknown".
5641
5642 This variable is used by default to isolate native shared state
5643 packages for different distributions (e.g. to avoid problems with
5644 ``glibc`` version incompatibilities). Additionally, the variable is
5645 checked against
5646 :term:`SANITY_TESTED_DISTROS` if that
5647 variable is set.
5648
Andrew Geisslerf0343792020-11-18 10:42:21 -06005649 :term:`NM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005650 The minimal command and arguments to run ``nm``.
5651
Andrew Geisslerf0343792020-11-18 10:42:21 -06005652 :term:`NO_GENERIC_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005653 Avoids QA errors when you use a non-common, non-CLOSED license in a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005654 recipe. There are packages, such as the linux-firmware package, with many
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005655 licenses that are not in any way common. Also, new licenses are added
5656 occasionally to avoid introducing a lot of common license files,
5657 which are only applicable to a specific package.
Andrew Geissler09036742021-06-25 14:25:14 -05005658 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005659 not exist in common licenses.
5660
Andrew Geissler09036742021-06-25 14:25:14 -05005661 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05005662 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005663
5664 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
5665
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005666 Here is an example that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005667 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
Andrew Geisslerc926e172021-05-07 16:11:35 -05005668 source::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005669
5670 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
5671
Andrew Geisslerf0343792020-11-18 10:42:21 -06005672 :term:`NO_RECOMMENDATIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005673 Prevents installation of all "recommended-only" packages.
5674 Recommended-only packages are packages installed only through the
5675 :term:`RRECOMMENDS` variable). Setting the
Andrew Geissler09036742021-06-25 14:25:14 -05005676 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005677
5678 NO_RECOMMENDATIONS = "1"
5679
5680 You can set this variable globally in your ``local.conf`` file or you
5681 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05005682 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005683
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005684 NO_RECOMMENDATIONS:pn-target_image = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005685
5686 It is important to realize that if you choose to not install packages
5687 using this variable and some other packages are dependent on them
5688 (i.e. listed in a recipe's :term:`RDEPENDS`
5689 variable), the OpenEmbedded build system ignores your request and
5690 will install the packages to avoid dependency errors.
5691
5692 .. note::
5693
5694 Some recommended packages might be required for certain system
5695 functionality, such as kernel modules. It is up to you to add
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005696 packages with the :term:`IMAGE_INSTALL` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005697
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005698 This variable is only supported when using the IPK and RPM
5699 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005700
5701 See the :term:`BAD_RECOMMENDATIONS` and
5702 the :term:`PACKAGE_EXCLUDE` variables for
5703 related information.
5704
Andrew Geisslerf0343792020-11-18 10:42:21 -06005705 :term:`NOAUTOPACKAGEDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005706 Disables auto package from splitting ``.debug`` files. If a recipe
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005707 requires ``FILES:${PN}-dbg`` to be set manually, the
Andrew Geissler09036742021-06-25 14:25:14 -05005708 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005709 content of the debug package. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005710
5711 NOAUTOPACKAGEDEBUG = "1"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005712 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
5713 FILES:${PN}-dbg = "/usr/src/debug/"
5714 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005715
Andrew Geissler09036742021-06-25 14:25:14 -05005716 :term:`NON_MULTILIB_RECIPES`
5717 A list of recipes that should not be built for multilib. OE-Core's
5718 ``multilib.conf`` file defines a reasonable starting point for this
5719 list with::
5720
5721 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
5722
Andrew Geissleredff4922024-06-19 14:12:16 -04005723 :term:`NVDCVE_API_KEY`
5724 The NVD API key used to retrieve data from the CVE database when
5725 using :ref:`ref-classes-cve-check`.
5726
5727 By default, no API key is used, which results in larger delays between API
5728 requests and limits the number of queries to the public rate limits posted
5729 at the `NVD developer's page <https://nvd.nist.gov/developers/start-here>`__.
5730
5731 NVD API keys can be requested through the
5732 `Request an API Key <https://nvd.nist.gov/developers/request-an-api-key>`__
5733 page. You can set this variable to the NVD API key in your ``local.conf`` file.
5734 Example::
5735
5736 NVDCVE_API_KEY = "fe753&7a2-1427-347d-23ff-b2e2b7ca5f3"
5737
Andrew Geisslerf0343792020-11-18 10:42:21 -06005738 :term:`OBJCOPY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005739 The minimal command and arguments to run ``objcopy``.
5740
Andrew Geisslerf0343792020-11-18 10:42:21 -06005741 :term:`OBJDUMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005742 The minimal command and arguments to run ``objdump``.
5743
Andrew Geisslerf0343792020-11-18 10:42:21 -06005744 :term:`OE_BINCONFIG_EXTRA_MANGLE`
Andrew Geissler517393d2023-01-13 08:55:19 -06005745 When inheriting the :ref:`ref-classes-binconfig` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005746 this variable specifies additional arguments passed to the "sed"
5747 command. The sed command alters any paths in configuration scripts
5748 that have been set up during compilation. Inheriting this class
5749 results in all paths in these scripts being changed to point into the
5750 ``sysroots/`` directory so that all builds that use the script will
5751 use the correct directories for the cross compiling layout.
5752
Patrick Williams975a06f2022-10-21 14:42:47 -05005753 See the ``meta/classes-recipe/binconfig.bbclass`` in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005754 :term:`Source Directory` for details on how this class
Andrew Geissler595f6302022-01-24 19:11:47 +00005755 applies these additional sed command arguments.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005756
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06005757 :term:`OECMAKE_GENERATOR`
5758 A variable for the :ref:`ref-classes-cmake` class, allowing to choose
5759 which back-end will be generated by CMake to build an application.
5760
5761 By default, this variable is set to ``Ninja``, which is faster than GNU
5762 make, but if building is broken with Ninja, a recipe can use this
5763 variable to use GNU make instead::
5764
5765 OECMAKE_GENERATOR = "Unix Makefiles"
5766
Andrew Geisslerf0343792020-11-18 10:42:21 -06005767 :term:`OE_IMPORTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005768 An internal variable used to tell the OpenEmbedded build system what
5769 Python modules to import for every Python function run by the system.
5770
5771 .. note::
5772
5773 Do not set this variable. It is for internal use only.
5774
Andrew Geisslerf0343792020-11-18 10:42:21 -06005775 :term:`OE_INIT_ENV_SCRIPT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005776 The name of the build environment setup script for the purposes of
5777 setting up the environment within the extensible SDK. The default
5778 value is "oe-init-build-env".
5779
5780 If you use a custom script to set up your build environment, set the
Andrew Geissler09036742021-06-25 14:25:14 -05005781 :term:`OE_INIT_ENV_SCRIPT` variable to its name.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005782
Andrew Geisslerf0343792020-11-18 10:42:21 -06005783 :term:`OE_TERMINAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005784 Controls how the OpenEmbedded build system spawns interactive
5785 terminals on the host development system (e.g. using the BitBake
5786 command with the ``-c devshell`` command-line option). For more
Andrew Geissler517393d2023-01-13 08:55:19 -06005787 information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005788 the Yocto Project Development Tasks Manual.
5789
Andrew Geissler5f350902021-07-23 13:09:54 -04005790 You can use the following values for the :term:`OE_TERMINAL` variable:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005791
5792 - auto
5793 - gnome
5794 - xfce
5795 - rxvt
5796 - screen
5797 - konsole
5798 - none
5799
Andrew Geisslerf0343792020-11-18 10:42:21 -06005800 :term:`OEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005801 The directory from which the top-level build environment setup script
5802 is sourced. The Yocto Project provides a top-level build environment
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005803 setup script: :ref:`structure-core-script`. When you run this
Andrew Geissler09036742021-06-25 14:25:14 -05005804 script, the :term:`OEROOT` variable resolves to the directory that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005805 contains the script.
5806
5807 For additional information on how this variable is used, see the
5808 initialization script.
5809
Patrick Williamsac13d5f2023-11-24 18:59:46 -06005810 :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE`
5811 Set the package manager(s) for build reproducibility testing.
5812 See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>`
5813 and :doc:`/test-manual/reproducible-builds`.
5814
Patrick Williams520786c2023-06-25 16:20:36 -05005815 :term:`OEQA_REPRODUCIBLE_TEST_TARGET`
5816 Set build target for build reproducibility testing. By default
5817 all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD`
5818 and :doc:`/test-manual/reproducible-builds`.
5819
5820 :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS`
5821 Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>`
5822 when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`.
5823
Andrew Geisslerf0343792020-11-18 10:42:21 -06005824 :term:`OLDEST_KERNEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005825 Declares the oldest version of the Linux kernel that the produced
5826 binaries must support. This variable is passed into the build of the
5827 Embedded GNU C Library (``glibc``).
5828
5829 The default for this variable comes from the
5830 ``meta/conf/bitbake.conf`` configuration file. You can override this
5831 default by setting the variable in a custom distribution
5832 configuration file.
5833
Patrick Williams44b3caf2024-04-12 16:51:14 -05005834 :term:`OPKG_MAKE_INDEX_EXTRA_PARAMS`
5835 Specifies extra parameters for the ``opkg-make-index`` command.
5836
Patrick Williams84603582024-12-14 08:00:57 -05005837 :term:`OPKGBUILDCMD`
5838 The variable :term:`OPKGBUILDCMD` specifies the command used to build opkg
5839 packages when using the :ref:`ref-classes-package_ipk` class. It is
5840 defined in :ref:`ref-classes-package_ipk` as::
5841
5842 OPKGBUILDCMD ??= 'opkg-build -Z zstd -a "${ZSTD_DEFAULTS}"'
5843
Patrick Williams975a06f2022-10-21 14:42:47 -05005844 :term:`OVERLAYFS_ETC_DEVICE`
Andrew Geissler517393d2023-01-13 08:55:19 -06005845 When the :ref:`ref-classes-overlayfs-etc` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005846 inherited, specifies the device to be mounted for the read/write
5847 layer of ``/etc``. There is no default, so you must set this if you
Andrew Geissler517393d2023-01-13 08:55:19 -06005848 wish to enable :ref:`ref-classes-overlayfs-etc`, for
Patrick Williams975a06f2022-10-21 14:42:47 -05005849 example, assuming ``/dev/mmcblk0p2`` was the desired device::
5850
5851 OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2"
5852
5853 :term:`OVERLAYFS_ETC_EXPOSE_LOWER`
Andrew Geissler517393d2023-01-13 08:55:19 -06005854 When the :ref:`ref-classes-overlayfs-etc` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005855 inherited, if set to "1" then a read-only access to the original
5856 ``/etc`` content will be provided as a ``lower/`` subdirectory of
5857 :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0".
5858
5859 :term:`OVERLAYFS_ETC_FSTYPE`
Andrew Geissler517393d2023-01-13 08:55:19 -06005860 When the :ref:`ref-classes-overlayfs-etc` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005861 inherited, specifies the file system type for the read/write
5862 layer of ``/etc``. There is no default, so you must set this if you
Andrew Geissler517393d2023-01-13 08:55:19 -06005863 wish to enable :ref:`ref-classes-overlayfs-etc`,
Patrick Williams975a06f2022-10-21 14:42:47 -05005864 for example, assuming the file system is ext4::
5865
5866 OVERLAYFS_ETC_FSTYPE = "ext4"
5867
5868 :term:`OVERLAYFS_ETC_MOUNT_OPTIONS`
Andrew Geissler517393d2023-01-13 08:55:19 -06005869 When the :ref:`ref-classes-overlayfs-etc` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005870 inherited, specifies the mount options for the read-write layer.
5871 The default value is "defaults".
5872
5873 :term:`OVERLAYFS_ETC_MOUNT_POINT`
Andrew Geissler517393d2023-01-13 08:55:19 -06005874 When the :ref:`ref-classes-overlayfs-etc` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005875 inherited, specifies the parent mount path for the filesystem layers.
5876 There is no default, so you must set this if you wish to enable
Andrew Geissler517393d2023-01-13 08:55:19 -06005877 :ref:`ref-classes-overlayfs-etc`, for example if the desired path is
5878 "/data"::
Patrick Williams975a06f2022-10-21 14:42:47 -05005879
5880 OVERLAYFS_ETC_MOUNT_POINT = "/data"
5881
5882 :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME`
Andrew Geissler517393d2023-01-13 08:55:19 -06005883 When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls
5884 how the generated init will be named. For more information, see the
5885 :ref:`ref-classes-overlayfs-etc` class documentation. The default value
5886 is "1".
Patrick Williams975a06f2022-10-21 14:42:47 -05005887
5888 :term:`OVERLAYFS_MOUNT_POINT`
Andrew Geissler517393d2023-01-13 08:55:19 -06005889 When inheriting the :ref:`ref-classes-overlayfs` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05005890 specifies mount point(s) to be used. For example::
5891
5892 OVERLAYFS_MOUNT_POINT[data] = "/data"
5893
Andrew Geissler517393d2023-01-13 08:55:19 -06005894 The assumes you have a ``data.mount`` systemd unit defined elsewhere in
5895 your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed
5896 into the image. For more information see :ref:`ref-classes-overlayfs`.
Patrick Williams975a06f2022-10-21 14:42:47 -05005897
5898 .. note::
5899
Andrew Geissler517393d2023-01-13 08:55:19 -06005900 Although the :ref:`ref-classes-overlayfs` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005901 inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT`
5902 should be set in your machine configuration.
5903
5904 :term:`OVERLAYFS_QA_SKIP`
Andrew Geissler517393d2023-01-13 08:55:19 -06005905 When inheriting the :ref:`ref-classes-overlayfs` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05005906 provides the ability to disable QA checks for particular overlayfs
5907 mounts. For example::
5908
5909 OVERLAYFS_QA_SKIP[data] = "mount-configured"
5910
5911 .. note::
5912
Andrew Geissler517393d2023-01-13 08:55:19 -06005913 Although the :ref:`ref-classes-overlayfs` class is
Patrick Williams975a06f2022-10-21 14:42:47 -05005914 inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP`
5915 should be set in your machine configuration.
5916
5917 :term:`OVERLAYFS_WRITABLE_PATHS`
Andrew Geissler517393d2023-01-13 08:55:19 -06005918 When inheriting the :ref:`ref-classes-overlayfs` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05005919 specifies writable paths used at runtime for the recipe. For
5920 example::
5921
5922 OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application"
5923
Andrew Geisslerf0343792020-11-18 10:42:21 -06005924 :term:`OVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005925 A colon-separated list of overrides that currently apply. Overrides
5926 are a BitBake mechanism that allows variables to be selectively
5927 overridden at the end of parsing. The set of overrides in
Andrew Geissler09036742021-06-25 14:25:14 -05005928 :term:`OVERRIDES` represents the "state" during building, which includes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005929 the current recipe being built, the machine for which it is being
5930 built, and so forth.
5931
5932 As an example, if the string "an-override" appears as an element in
Andrew Geissler09036742021-06-25 14:25:14 -05005933 the colon-separated list in :term:`OVERRIDES`, then the following
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005934 assignment will override ``FOO`` with the value "overridden" at the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005935 end of parsing::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005936
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005937 FOO:an-override = "overridden"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005938
5939 See the
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05005940 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005941 section in the BitBake User Manual for more information on the
5942 overrides mechanism.
5943
Andrew Geissler09036742021-06-25 14:25:14 -05005944 The default value of :term:`OVERRIDES` includes the values of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005945 :term:`CLASSOVERRIDE`,
5946 :term:`MACHINEOVERRIDES`, and
5947 :term:`DISTROOVERRIDES` variables. Another
5948 important override included by default is ``pn-${PN}``. This override
5949 allows variables to be set for a single recipe within configuration
Andrew Geisslerc926e172021-05-07 16:11:35 -05005950 (``.conf``) files. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005951
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005952 FOO:pn-myrecipe = "myrecipe-specific value"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005953
5954 .. note::
5955
Andrew Geissler09036742021-06-25 14:25:14 -05005956 An easy way to see what overrides apply is to search for :term:`OVERRIDES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005957 in the output of the ``bitbake -e`` command. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06005958 ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005959 Project Development Tasks Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005960
Andrew Geisslerf0343792020-11-18 10:42:21 -06005961 :term:`P`
Andrew Geissler09036742021-06-25 14:25:14 -05005962 The recipe name and version. :term:`P` is comprised of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005963
5964 ${PN}-${PV}
5965
Andrew Geissler517393d2023-01-13 08:55:19 -06005966 :term:`P4DIR`
5967 See :term:`bitbake:P4DIR` in the BitBake manual.
5968
Andrew Geisslerf0343792020-11-18 10:42:21 -06005969 :term:`PACKAGE_ADD_METADATA`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005970 This variable defines additional metadata to add to packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005971
5972 You may find you need to inject additional metadata into packages.
5973 This variable allows you to do that by setting the injected data as
5974 the value. Multiple fields can be added by splitting the content with
5975 the literal separator "\n".
5976
5977 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
5978 to do package type specific settings. It can also be made package
5979 specific by using the package name as a suffix.
5980
5981 You can find out more about applying this variable in the
Andrew Geissler517393d2023-01-13 08:55:19 -06005982 ":ref:`dev-manual/packages:adding custom metadata to packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005983 section in the Yocto Project Development Tasks Manual.
5984
Andrew Geisslerf0343792020-11-18 10:42:21 -06005985 :term:`PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005986 The architecture of the resulting package or packages.
5987
5988 By default, the value of this variable is set to
5989 :term:`TUNE_PKGARCH` when building for the
5990 target, :term:`BUILD_ARCH` when building for the
5991 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
5992 SDK.
5993
5994 .. note::
5995
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005996 See :term:`SDK_ARCH` for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005997
5998 However, if your recipe's output packages are built specific to the
5999 target machine rather than generally for the architecture of the
Andrew Geissler09036742021-06-25 14:25:14 -05006000 machine, you should set :term:`PACKAGE_ARCH` to the value of
Andrew Geisslerc926e172021-05-07 16:11:35 -05006001 :term:`MACHINE_ARCH` in the recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006002
6003 PACKAGE_ARCH = "${MACHINE_ARCH}"
6004
Andrew Geisslerf0343792020-11-18 10:42:21 -06006005 :term:`PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006006 Specifies a list of architectures compatible with the target machine.
6007 This variable is set automatically and should not normally be
6008 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05006009 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006010 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
6011
Andrew Geisslerf0343792020-11-18 10:42:21 -06006012 :term:`PACKAGE_BEFORE_PN`
Andrew Geissler09036742021-06-25 14:25:14 -05006013 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006014 that those added packages can pick up files that would normally be
6015 included in the default package.
6016
Andrew Geisslerf0343792020-11-18 10:42:21 -06006017 :term:`PACKAGE_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006018 This variable, which is set in the ``local.conf`` configuration file
6019 found in the ``conf`` folder of the
6020 :term:`Build Directory`, specifies the package manager the
6021 OpenEmbedded build system uses when packaging data.
6022
6023 You can provide one or more of the following arguments for the
Andrew Geissler517393d2023-01-13 08:55:19 -06006024 variable::
6025
Patrick Williams8e7b46e2023-05-01 14:19:06 -05006026 PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006027
6028 The build system uses only the first argument in the list as the
6029 package manager when creating your image or SDK. However, packages
6030 will be created using any additional packaging classes you specify.
Andrew Geisslerc926e172021-05-07 16:11:35 -05006031 For example, if you use the following in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006032
6033 PACKAGE_CLASSES ?= "package_ipk"
6034
6035 The OpenEmbedded build system uses
6036 the IPK package manager to create your image or SDK.
6037
6038 For information on packaging and build performance effects as a
6039 result of the package manager in use, see the
Andrew Geissler595f6302022-01-24 19:11:47 +00006040 ":ref:`ref-classes-package`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006041
Andrew Geisslerf0343792020-11-18 10:42:21 -06006042 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
Patrick Williams93c203f2021-10-06 16:15:23 -05006043 Determines how to split up and package debug and source information
6044 when creating debugging packages to be used with the GNU Project
6045 Debugger (GDB). In general, based on the value of this variable,
6046 you can combine the source and debug info in a single package,
6047 you can break out the source into a separate package that can be
6048 installed independently, or you can choose to not have the source
6049 packaged at all.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006050
Patrick Williams93c203f2021-10-06 16:15:23 -05006051 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006052
Patrick Williams93c203f2021-10-06 16:15:23 -05006053 - "``.debug``": All debugging and source info is placed in a single
6054 ``*-dbg`` package; debug symbol files are placed next to the
6055 binary in a ``.debug`` directory so that, if a binary is installed
6056 into ``/bin``, the corresponding debug symbol file is installed
6057 in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
6058 package under ``/usr/src/debug``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006059
Patrick Williams93c203f2021-10-06 16:15:23 -05006060 - "``debug-file-directory``": As above, all debugging and source info
6061 is placed in a single ``*-dbg`` package; debug symbol files are
6062 placed entirely under the directory ``/usr/lib/debug`` and separated
6063 by the path from where the binary is installed, so that if a binary
6064 is installed in ``/bin``, the corresponding debug symbols are installed
6065 in ``/usr/lib/debug/bin``, and so on. As above, source is installed
6066 in the same package under ``/usr/src/debug``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006067
Patrick Williams93c203f2021-10-06 16:15:23 -05006068 - "``debug-with-srcpkg``": Debugging info is placed in the standard
6069 ``*-dbg`` package as with the ``.debug`` value, while source is
6070 placed in a separate ``*-src`` package, which can be installed
6071 independently. This is the default setting for this variable,
6072 as defined in Poky's ``bitbake.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006073
Patrick Williams93c203f2021-10-06 16:15:23 -05006074 - "``debug-without-src``": The same behavior as with the ``.debug``
6075 setting, but no source is packaged at all.
6076
6077 .. note::
6078
6079 Much of the above package splitting can be overridden via
6080 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006081
6082 You can find out more about debugging using GDB by reading the
Andrew Geissler517393d2023-01-13 08:55:19 -06006083 ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006084 in the Yocto Project Development Tasks Manual.
6085
Andrew Geisslerf0343792020-11-18 10:42:21 -06006086 :term:`PACKAGE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006087 Lists packages that should not be installed into an image. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05006088 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006089
6090 PACKAGE_EXCLUDE = "package_name package_name package_name ..."
6091
6092 You can set this variable globally in your ``local.conf`` file or you
6093 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05006094 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006095
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006096 PACKAGE_EXCLUDE:pn-target_image = "package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006097
6098 If you choose to not install a package using this variable and some
6099 other package is dependent on it (i.e. listed in a recipe's
6100 :term:`RDEPENDS` variable), the OpenEmbedded build
6101 system generates a fatal installation error. Because the build system
6102 halts the process with a fatal error, you can use the variable with
6103 an iterative development process to remove specific components from a
6104 system.
6105
William A. Kennington IIIac69b482021-06-02 12:28:27 -07006106 This variable is supported only when using the IPK and RPM
6107 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006108
6109 See the :term:`NO_RECOMMENDATIONS` and the
6110 :term:`BAD_RECOMMENDATIONS` variables for
6111 related information.
6112
Andrew Geissler9aee5002022-03-30 16:27:02 +00006113 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY`
6114 Prevents specific packages from being installed when you are
6115 installing complementary packages.
6116
6117 You might find that you want to prevent installing certain packages
6118 when you are installing complementary packages. For example, if you
6119 are using :term:`IMAGE_FEATURES` to install
6120 ``dev-pkgs``, you might not want to install all packages from a
6121 particular multilib. If you find yourself in this situation, you can
6122 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular
6123 expressions to match the packages you want to exclude.
6124
Andrew Geisslerf0343792020-11-18 10:42:21 -06006125 :term:`PACKAGE_EXTRA_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006126 Specifies the list of architectures compatible with the device CPU.
6127 This variable is useful when you build for several different devices
6128 that use miscellaneous processors such as XScale and ARM926-EJS.
6129
Andrew Geisslerf0343792020-11-18 10:42:21 -06006130 :term:`PACKAGE_FEED_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006131 Optionally specifies the package architectures used as part of the
6132 package feed URIs during the build. When used, the
Andrew Geissler09036742021-06-25 14:25:14 -05006133 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006134 URI, which is constructed using the
6135 :term:`PACKAGE_FEED_URIS` and
6136 :term:`PACKAGE_FEED_BASE_PATHS`
6137 variables.
6138
6139 .. note::
6140
Andrew Geissler09036742021-06-25 14:25:14 -05006141 You can use the :term:`PACKAGE_FEED_ARCHS`
Andrew Geissler595f6302022-01-24 19:11:47 +00006142 variable to allow specific package architectures. If you do
6143 not need to allow specific architectures, which is a common
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006144 case, you can omit this variable. Omitting the variable results in
6145 all available architectures for the current machine being included
6146 into remote package feeds.
6147
Andrew Geissler09036742021-06-25 14:25:14 -05006148 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6149 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05006150 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006151
6152 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6153 https://example.com/packagerepos/updates"
6154 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6155 PACKAGE_FEED_ARCHS = "all core2-64"
6156
6157 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006158
6159 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006160
6161 https://example.com/packagerepos/release/rpm/all
6162 https://example.com/packagerepos/release/rpm/core2-64
6163 https://example.com/packagerepos/release/rpm-dev/all
6164 https://example.com/packagerepos/release/rpm-dev/core2-64
6165 https://example.com/packagerepos/updates/rpm/all
6166 https://example.com/packagerepos/updates/rpm/core2-64
6167 https://example.com/packagerepos/updates/rpm-dev/all
6168 https://example.com/packagerepos/updates/rpm-dev/core2-64
6169
Andrew Geisslerf0343792020-11-18 10:42:21 -06006170 :term:`PACKAGE_FEED_BASE_PATHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006171 Specifies the base path used when constructing package feed URIs. The
Andrew Geissler09036742021-06-25 14:25:14 -05006172 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006173 package feed URI used by the OpenEmbedded build system. The base path
6174 lies between the :term:`PACKAGE_FEED_URIS`
6175 and :term:`PACKAGE_FEED_ARCHS` variables.
6176
Andrew Geissler09036742021-06-25 14:25:14 -05006177 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6178 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05006179 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006180
6181 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6182 https://example.com/packagerepos/updates"
6183 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6184 PACKAGE_FEED_ARCHS = "all core2-64"
6185
6186 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006187
6188 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006189
6190 https://example.com/packagerepos/release/rpm/all
6191 https://example.com/packagerepos/release/rpm/core2-64
6192 https://example.com/packagerepos/release/rpm-dev/all
6193 https://example.com/packagerepos/release/rpm-dev/core2-64
6194 https://example.com/packagerepos/updates/rpm/all
6195 https://example.com/packagerepos/updates/rpm/core2-64
6196 https://example.com/packagerepos/updates/rpm-dev/all
6197 https://example.com/packagerepos/updates/rpm-dev/core2-64
6198
Andrew Geisslerf0343792020-11-18 10:42:21 -06006199 :term:`PACKAGE_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006200 Specifies the front portion of the package feed URI used by the
6201 OpenEmbedded build system. Each final package feed URI is comprised
Andrew Geissler09036742021-06-25 14:25:14 -05006202 of :term:`PACKAGE_FEED_URIS`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006203 :term:`PACKAGE_FEED_BASE_PATHS`, and
6204 :term:`PACKAGE_FEED_ARCHS` variables.
6205
Andrew Geissler09036742021-06-25 14:25:14 -05006206 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
6207 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05006208 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006209
6210 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
6211 https://example.com/packagerepos/updates"
6212 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
6213 PACKAGE_FEED_ARCHS = "all core2-64"
6214
6215 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006216
6217 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006218
6219 https://example.com/packagerepos/release/rpm/all
6220 https://example.com/packagerepos/release/rpm/core2-64
6221 https://example.com/packagerepos/release/rpm-dev/all
6222 https://example.com/packagerepos/release/rpm-dev/core2-64
6223 https://example.com/packagerepos/updates/rpm/all
6224 https://example.com/packagerepos/updates/rpm/core2-64
6225 https://example.com/packagerepos/updates/rpm-dev/all
6226 https://example.com/packagerepos/updates/rpm-dev/core2-64
6227
Andrew Geisslerf0343792020-11-18 10:42:21 -06006228 :term:`PACKAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006229 The final list of packages passed to the package manager for
6230 installation into the image.
6231
6232 Because the package manager controls actual installation of all
Andrew Geissler09036742021-06-25 14:25:14 -05006233 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006234 not the final list of packages that are actually installed. This
6235 variable is internal to the image construction code. Consequently, in
6236 general, you should use the
6237 :term:`IMAGE_INSTALL` variable to specify
6238 packages for installation. The exception to this is when working with
Andrew Geissler09209ee2020-12-13 08:44:15 -06006239 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Patrick Williams2194f502022-10-16 14:26:09 -05006240 image. When working with an initial RAM filesystem (:term:`Initramfs`) image,
Andrew Geissler09036742021-06-25 14:25:14 -05006241 use the :term:`PACKAGE_INSTALL` variable. For information on creating an
Andrew Geissler517393d2023-01-13 08:55:19 -06006242 :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006243 in the Yocto Project Development Tasks Manual.
6244
Andrew Geisslerf0343792020-11-18 10:42:21 -06006245 :term:`PACKAGE_INSTALL_ATTEMPTONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006246 Specifies a list of packages the OpenEmbedded build system attempts
6247 to install when creating an image. If a listed package fails to
6248 install, the build system does not generate an error. This variable
6249 is generally not user-defined.
6250
Andrew Geisslerf0343792020-11-18 10:42:21 -06006251 :term:`PACKAGE_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006252 Specifies a list of functions run to pre-process the
6253 :term:`PKGD` directory prior to splitting the files out
6254 to individual packages.
6255
Andrew Geisslerf0343792020-11-18 10:42:21 -06006256 :term:`PACKAGE_WRITE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006257 Specifies a list of dependencies for post-installation and
6258 pre-installation scripts on native/cross tools. If your
Andrew Geissler595f6302022-01-24 19:11:47 +00006259 post-installation or pre-installation script can execute at root filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006260 creation time rather than on the target but depends on a native tool
6261 in order to execute, you need to list the tools in
Andrew Geissler09036742021-06-25 14:25:14 -05006262 :term:`PACKAGE_WRITE_DEPS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006263
6264 For information on running post-installation scripts, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06006265 ":ref:`dev-manual/new-recipe:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006266 section in the Yocto Project Development Tasks Manual.
6267
Andrew Geisslerf0343792020-11-18 10:42:21 -06006268 :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006269 This variable provides a means of enabling or disabling features of a
Andrew Geissler09036742021-06-25 14:25:14 -05006270 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006271 recipes when you specify features and then arguments that define
6272 feature behaviors. Here is the basic block structure (broken over
Andrew Geisslerc926e172021-05-07 16:11:35 -05006273 multiple lines for readability)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006274
6275 PACKAGECONFIG ??= "f1 f2 f3 ..."
6276 PACKAGECONFIG[f1] = "\
6277 --with-f1, \
6278 --without-f1, \
6279 build-deps-for-f1, \
6280 runtime-deps-for-f1, \
6281 runtime-recommends-for-f1, \
6282 packageconfig-conflicts-for-f1"
6283 PACKAGECONFIG[f2] = "\
6284 ... and so on and so on ...
6285
Andrew Geissler5f350902021-07-23 13:09:54 -04006286 The :term:`PACKAGECONFIG` variable itself specifies a space-separated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006287 list of the features to enable. Following the features, you can
6288 determine the behavior of each feature by providing up to six
6289 order-dependent arguments, which are separated by commas. You can
6290 omit any argument you like but must retain the separating commas. The
6291 order is important and specifies the following:
6292
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006293 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
6294 if the feature is enabled.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006295
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006296 #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS`
6297 if the feature is disabled.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006298
Andrew Geissler517393d2023-01-13 08:55:19 -06006299 #. Additional build dependencies (:term:`DEPENDS`)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006300 that should be added if the feature is enabled.
6301
Andrew Geissler517393d2023-01-13 08:55:19 -06006302 #. Additional runtime dependencies (:term:`RDEPENDS`)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006303 that should be added if the feature is enabled.
6304
Andrew Geissler517393d2023-01-13 08:55:19 -06006305 #. Additional runtime recommendations
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006306 (:term:`RRECOMMENDS`) that should be added if
6307 the feature is enabled.
6308
Andrew Geissler517393d2023-01-13 08:55:19 -06006309 #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006310 settings for this feature.
6311
Andrew Geissler09036742021-06-25 14:25:14 -05006312 Consider the following :term:`PACKAGECONFIG` block taken from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006313 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
Andrew Geissler517393d2023-01-13 08:55:19 -06006314 three arguments that determine the feature's behavior::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006315
6316 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
6317
6318 The
6319 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
6320 enabled. In this case, ``--with-gtk3`` is added to the configure
Andrew Geissler09036742021-06-25 14:25:14 -05006321 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006322 other hand, if the feature is disabled say through a ``.bbappend``
6323 file in another layer, then the second argument ``--without-gtk3`` is
6324 added to the configure script instead.
6325
Andrew Geissler09036742021-06-25 14:25:14 -05006326 The basic :term:`PACKAGECONFIG` structure previously described holds true
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006327 regardless of whether you are creating a block or changing a block.
6328 When creating a block, use the structure inside your recipe.
6329
Andrew Geissler09036742021-06-25 14:25:14 -05006330 If you want to change an existing :term:`PACKAGECONFIG` block, you can do
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006331 so one of two ways:
6332
6333 - *Append file:* Create an append file named
Andrew Geisslereff27472021-10-29 15:35:00 -05006334 ``recipename.bbappend`` in your layer and override the value of
Andrew Geissler09036742021-06-25 14:25:14 -05006335 :term:`PACKAGECONFIG`. You can either completely override the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006336 variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006337
6338 PACKAGECONFIG = "f4 f5"
6339
Andrew Geisslerc926e172021-05-07 16:11:35 -05006340 Or, you can just append the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006341
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006342 PACKAGECONFIG:append = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006343
6344 - *Configuration file:* This method is identical to changing the
6345 block through an append file except you edit your ``local.conf``
6346 or ``mydistro.conf`` file. As with append files previously
Andrew Geisslerc926e172021-05-07 16:11:35 -05006347 described, you can either completely override the variable::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006348
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006349 PACKAGECONFIG:pn-recipename = "f4 f5"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006350
Andrew Geisslerc926e172021-05-07 16:11:35 -05006351 Or, you can just amend the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006352
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006353 PACKAGECONFIG:append:pn-recipename = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006354
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006355 Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service
6356 in which :term:`PACKAGECONFIG` is used to transform the systemd service
6357 into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`::
6358
6359 example.c
6360 example.service
6361 CMakeLists.txt
6362
6363 The ``CMakeLists.txt`` file contains::
6364
6365 if(WITH_SYSTEMD)
6366 install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd)
6367 endif(WITH_SYSTEMD)
6368
6369 In order to enable the installation of ``example.service`` we need to
6370 ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command
6371 execution. Recipes that have ``CMakeLists.txt`` generally inherit the
6372 :ref:`ref-classes-cmake` class, that runs ``cmake`` with
6373 :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be
6374 appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is
6375 automatically filled with either the first or second element of
6376 :term:`PACKAGECONFIG` flag value, the recipe would be like::
6377
6378 inherit cmake
6379 PACKAGECONFIG = "systemd"
6380 PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF"
6381
6382 A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER`
6383 or not::
6384
6385 PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}"
6386
Andrew Geisslerf0343792020-11-18 10:42:21 -06006387 :term:`PACKAGECONFIG_CONFARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006388 A space-separated list of configuration options generated from the
6389 :term:`PACKAGECONFIG` setting.
6390
Andrew Geissler517393d2023-01-13 08:55:19 -06006391 Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake`
6392 use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options
6393 to ``configure`` and ``cmake``, respectively. If you are using
6394 :term:`PACKAGECONFIG` but not a class that handles the
6395 :ref:`ref-tasks-configure` task, then you need to use
Andrew Geissler09036742021-06-25 14:25:14 -05006396 :term:`PACKAGECONFIG_CONFARGS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006397
Andrew Geisslerf0343792020-11-18 10:42:21 -06006398 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY`
Andrew Geissler517393d2023-01-13 08:55:19 -06006399 For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting
Andrew Geissler09036742021-06-25 14:25:14 -05006400 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006401 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
6402 should not be automatically created by the ``packagegroup`` recipe,
6403 which is the default behavior.
6404
Andrew Geisslerf0343792020-11-18 10:42:21 -06006405 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006406 The list of packages the recipe creates. The default value is the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006407 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006408
Andrew Geissler5199d832021-09-24 16:47:35 -05006409 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006410
6411 During packaging, the :ref:`ref-tasks-package` task
Andrew Geissler09036742021-06-25 14:25:14 -05006412 goes through :term:`PACKAGES` and uses the :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006413 variable corresponding to each package to assign files to the
Andrew Geissler09036742021-06-25 14:25:14 -05006414 package. If a file matches the :term:`FILES` variable for more than one
6415 package in :term:`PACKAGES`, it will be assigned to the earliest
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006416 (leftmost) package.
6417
6418 Packages in the variable's list that are empty (i.e. where none of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006419 the patterns in ``FILES:``\ pkg match any files installed by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006420 :ref:`ref-tasks-install` task) are not generated,
6421 unless generation is forced through the
6422 :term:`ALLOW_EMPTY` variable.
6423
Andrew Geisslerf0343792020-11-18 10:42:21 -06006424 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006425 A promise that your recipe satisfies runtime dependencies for
6426 optional modules that are found in other recipes.
Andrew Geissler09036742021-06-25 14:25:14 -05006427 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006428 only states that they should be satisfied. For example, if a hard,
6429 runtime dependency (:term:`RDEPENDS`) of another
Andrew Geissler09036742021-06-25 14:25:14 -05006430 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006431 variable, but a package with the module name is never actually
6432 produced, then the other package will be broken. Thus, if you attempt
6433 to include that package in an image, you will get a dependency
6434 failure from the packaging system during the
6435 :ref:`ref-tasks-rootfs` task.
6436
6437 Typically, if there is a chance that such a situation can occur and
6438 the package that is not created is valid without the dependency being
6439 satisfied, then you should use :term:`RRECOMMENDS`
Andrew Geissler09036742021-06-25 14:25:14 -05006440 (a soft runtime dependency) instead of :term:`RDEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006441
Andrew Geissler09036742021-06-25 14:25:14 -05006442 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006443 you are splitting packages, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06006444 ":ref:`dev-manual/packages:handling optional module packaging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006445 section in the Yocto Project Development Tasks Manual.
6446
Andrew Geisslerf0343792020-11-18 10:42:21 -06006447 :term:`PACKAGESPLITFUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006448 Specifies a list of functions run to perform additional splitting of
6449 files into individual packages. Recipes can either prepend to this
6450 variable or prepend to the ``populate_packages`` function in order to
6451 perform additional package splitting. In either case, the function
6452 should set :term:`PACKAGES`,
6453 :term:`FILES`, :term:`RDEPENDS` and
6454 other packaging variables appropriately in order to perform the
6455 desired splitting.
6456
Andrew Geisslerf0343792020-11-18 10:42:21 -06006457 :term:`PARALLEL_MAKE`
Patrick Williams7784c422022-11-17 07:29:11 -06006458
6459 Extra options passed to the build tool command (``make``,
6460 ``ninja`` or more specific build engines, like the Go language one)
6461 during the :ref:`ref-tasks-compile` task, to specify parallel compilation
6462 on the local build host. This variable is usually in the form "-j x",
6463 where x represents the maximum number of parallel threads such engines
6464 can run.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006465
6466 .. note::
6467
Patrick Williams7784c422022-11-17 07:29:11 -06006468 For software compiled by ``make``, in order for :term:`PARALLEL_MAKE`
6469 to be effective, ``make`` must be called with
6470 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6471 way to ensure this is to use the ``oe_runmake`` function.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006472
6473 By default, the OpenEmbedded build system automatically sets this
6474 variable to be equal to the number of cores the build system uses.
6475
6476 .. note::
6477
6478 If the software being built experiences dependency issues during
Patrick Williams2194f502022-10-16 14:26:09 -05006479 the :ref:`ref-tasks-compile` task that result in race conditions, you can clear
Andrew Geissler09036742021-06-25 14:25:14 -05006480 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006481 information on addressing race conditions, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06006482 ":ref:`dev-manual/debugging:debugging parallel make races`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006483 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006484
6485 For single socket systems (i.e. one CPU), you should not have to
6486 override this variable to gain optimal parallelism during builds.
6487 However, if you have very large systems that employ multiple physical
Andrew Geissler09036742021-06-25 14:25:14 -05006488 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006489 not set higher than "-j 20".
6490
6491 For more information on speeding up builds, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06006492 ":ref:`dev-manual/speeding-up-build:speeding up a build`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006493 section in the Yocto Project Development Tasks Manual.
6494
Andrew Geisslerf0343792020-11-18 10:42:21 -06006495 :term:`PARALLEL_MAKEINST`
Patrick Williams7784c422022-11-17 07:29:11 -06006496 Extra options passed to the build tool install command
6497 (``make install``, ``ninja install`` or more specific ones)
6498 during the :ref:`ref-tasks-install` task in order to specify
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006499 parallel installation. This variable defaults to the value of
6500 :term:`PARALLEL_MAKE`.
6501
6502 .. note::
6503
Patrick Williams7784c422022-11-17 07:29:11 -06006504 For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST`
6505 to be effective, ``make`` must be called with
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006506 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6507 way to ensure this is to use the ``oe_runmake`` function.
6508
6509 If the software being built experiences dependency issues during
Patrick Williams2194f502022-10-16 14:26:09 -05006510 the :ref:`ref-tasks-install` task that result in race conditions, you can
Andrew Geissler09036742021-06-25 14:25:14 -05006511 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006512 workaround. For information on addressing race conditions, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06006513 ":ref:`dev-manual/debugging:debugging parallel make races`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006514 section in the Yocto Project Development Tasks Manual.
6515
Andrew Geisslerf0343792020-11-18 10:42:21 -06006516 :term:`PATCHRESOLVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006517 Determines the action to take when a patch fails. You can set this
6518 variable to one of two values: "noop" and "user".
6519
6520 The default value of "noop" causes the build to simply fail when the
6521 OpenEmbedded build system cannot successfully apply a patch. Setting
6522 the value to "user" causes the build system to launch a shell and
6523 places you in the right location so that you can manually resolve the
6524 conflicts.
6525
6526 Set this variable in your ``local.conf`` file.
6527
Andrew Geisslerf0343792020-11-18 10:42:21 -06006528 :term:`PATCHTOOL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006529 Specifies the utility used to apply patches for a recipe during the
6530 :ref:`ref-tasks-patch` task. You can specify one of
6531 three utilities: "patch", "quilt", or "git". The default utility used
6532 is "quilt" except for the quilt-native recipe itself. Because the
6533 quilt tool is not available at the time quilt-native is being
6534 patched, it uses "patch".
6535
6536 If you wish to use an alternative patching tool, set the variable in
Andrew Geisslerc926e172021-05-07 16:11:35 -05006537 the recipe using one of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006538
6539 PATCHTOOL = "patch"
6540 PATCHTOOL = "quilt"
6541 PATCHTOOL = "git"
6542
Andrew Geisslerf0343792020-11-18 10:42:21 -06006543 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006544 The epoch of the recipe. By default, this variable is unset. The
6545 variable is used to make upgrades possible when the versioning scheme
6546 changes in some backwards incompatible way.
6547
Andrew Geissler09036742021-06-25 14:25:14 -05006548 :term:`PE` is the default value of the :term:`PKGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006549
Andrew Geissler9aee5002022-03-30 16:27:02 +00006550 :term:`PEP517_WHEEL_PATH`
Andrew Geissler517393d2023-01-13 08:55:19 -06006551 When used by recipes that inherit the :ref:`ref-classes-python_pep517`
6552 class, denotes the path to ``dist/`` (short for distribution) where the
Andrew Geissler9aee5002022-03-30 16:27:02 +00006553 binary archive ``wheel`` is built.
6554
Andrew Geissler517393d2023-01-13 08:55:19 -06006555 :term:`PERSISTENT_DIR`
6556 See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual.
6557
Andrew Geisslerf0343792020-11-18 10:42:21 -06006558 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006559 Specifies the recipe or package name and includes all version and
6560 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
6561 ``bash-4.2-r1/``). This variable is comprised of the following:
6562 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
6563
Andrew Geisslerf0343792020-11-18 10:42:21 -06006564 :term:`PIXBUF_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -06006565 When inheriting the :ref:`ref-classes-pixbufcache`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006566 class, this variable identifies packages that contain the pixbuf
Andrew Geissler517393d2023-01-13 08:55:19 -06006567 loaders used with ``gdk-pixbuf``. By default, the
6568 :ref:`ref-classes-pixbufcache` class assumes that
6569 the loaders are in the recipe's main package (i.e.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006570 ``${``\ :term:`PN`\ ``}``). Use this variable if the
6571 loaders you need are in a package other than that main package.
6572
Andrew Geisslerf0343792020-11-18 10:42:21 -06006573 :term:`PKG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006574 The name of the resulting package created by the OpenEmbedded build
6575 system.
6576
6577 .. note::
6578
Andrew Geissler09036742021-06-25 14:25:14 -05006579 When using the :term:`PKG` variable, you must use a package name override.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006580
Andrew Geissler517393d2023-01-13 08:55:19 -06006581 For example, when the :ref:`ref-classes-debian` class renames the output
6582 package, it does so by setting ``PKG:packagename``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006583
Andrew Geisslerf0343792020-11-18 10:42:21 -06006584 :term:`PKG_CONFIG_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006585 The path to ``pkg-config`` files for the current build context.
6586 ``pkg-config`` reads this variable from the environment.
6587
Andrew Geisslerf0343792020-11-18 10:42:21 -06006588 :term:`PKGD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006589 Points to the destination directory for files to be packaged before
6590 they are split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006591 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006592
6593 ${WORKDIR}/package
6594
6595 Do not change this default.
6596
Andrew Geisslerf0343792020-11-18 10:42:21 -06006597 :term:`PKGDATA_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006598 Points to a shared, global-state directory that holds data generated
6599 during the packaging process. During the packaging process, the
6600 :ref:`ref-tasks-packagedata` task packages data
6601 for each recipe and installs it into this temporary, shared area.
6602 This directory defaults to the following, which you should not
Andrew Geisslerc926e172021-05-07 16:11:35 -05006603 change::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006604
6605 ${STAGING_DIR_HOST}/pkgdata
6606
6607 For examples of how this data is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006608 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006609 section in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler517393d2023-01-13 08:55:19 -06006610 ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006611 section in the Yocto Project Development Tasks Manual. For more
6612 information on the shared, global-state directory, see
6613 :term:`STAGING_DIR_HOST`.
6614
Andrew Geisslerf0343792020-11-18 10:42:21 -06006615 :term:`PKGDEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006616 Points to the parent directory for files to be packaged after they
6617 have been split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006618 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006619
6620 ${WORKDIR}/packages-split
6621
6622 Under this directory, the build system creates directories for each
6623 package specified in :term:`PACKAGES`. Do not change
6624 this default.
6625
Andrew Geisslerf0343792020-11-18 10:42:21 -06006626 :term:`PKGDESTWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006627 Points to a temporary work area where the
6628 :ref:`ref-tasks-package` task saves package metadata.
Andrew Geissler09036742021-06-25 14:25:14 -05006629 The :term:`PKGDESTWORK` location defaults to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006630
6631 ${WORKDIR}/pkgdata
6632
6633 Do not change this default.
6634
6635 The :ref:`ref-tasks-packagedata` task copies the
Andrew Geissler09036742021-06-25 14:25:14 -05006636 package metadata from :term:`PKGDESTWORK` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006637 :term:`PKGDATA_DIR` to make it available globally.
6638
Andrew Geisslerf0343792020-11-18 10:42:21 -06006639 :term:`PKGE`
Andrew Geissler09036742021-06-25 14:25:14 -05006640 The epoch of the package(s) built by the recipe. By default, :term:`PKGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006641 is set to :term:`PE`.
6642
Andrew Geisslerf0343792020-11-18 10:42:21 -06006643 :term:`PKGR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006644 The revision of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05006645 :term:`PKGR` is set to :term:`PR`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006646
Andrew Geisslerf0343792020-11-18 10:42:21 -06006647 :term:`PKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006648 The version of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05006649 :term:`PKGV` is set to :term:`PV`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006650
Andrew Geisslerf0343792020-11-18 10:42:21 -06006651 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006652 This variable can have two separate functions depending on the
6653 context: a recipe name or a resulting package name.
6654
Andrew Geissler09036742021-06-25 14:25:14 -05006655 :term:`PN` refers to a recipe name in the context of a file used by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006656 OpenEmbedded build system as input to create a package. The name is
6657 normally extracted from the recipe file name. For example, if the
Andrew Geissler09036742021-06-25 14:25:14 -05006658 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006659 will be "expat".
6660
6661 The variable refers to a package name in the context of a file
6662 created or produced by the OpenEmbedded build system.
6663
Andrew Geissler09036742021-06-25 14:25:14 -05006664 If applicable, the :term:`PN` variable also contains any special suffix
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006665 or prefix. For example, using ``bash`` to build packages for the
Andrew Geissler5f350902021-07-23 13:09:54 -04006666 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build
Andrew Geissler09036742021-06-25 14:25:14 -05006667 packages for the target and for Multilib, :term:`PN` would be ``bash``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006668 and ``lib64-bash``, respectively.
6669
Andrew Geisslerf0343792020-11-18 10:42:21 -06006670 :term:`POPULATE_SDK_POST_HOST_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006671 Specifies a list of functions to call once the OpenEmbedded build
6672 system has created the host part of the SDK. You can specify
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006673 functions separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006674
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006675 POPULATE_SDK_POST_HOST_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006676
6677 If you need to pass the SDK path to a command within a function, you
6678 can use ``${SDK_DIR}``, which points to the parent directory used by
6679 the OpenEmbedded build system when creating SDK output. See the
6680 :term:`SDK_DIR` variable for more information.
6681
Andrew Geisslerf0343792020-11-18 10:42:21 -06006682 :term:`POPULATE_SDK_POST_TARGET_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006683 Specifies a list of functions to call once the OpenEmbedded build
6684 system has created the target part of the SDK. You can specify
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006685 functions separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006686
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006687 POPULATE_SDK_POST_TARGET_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006688
6689 If you need to pass the SDK path to a command within a function, you
6690 can use ``${SDK_DIR}``, which points to the parent directory used by
6691 the OpenEmbedded build system when creating SDK output. See the
6692 :term:`SDK_DIR` variable for more information.
6693
Andrew Geisslerf0343792020-11-18 10:42:21 -06006694 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006695 The revision of the recipe. The default value for this variable is
6696 "r0". Subsequent revisions of the recipe conventionally have the
6697 values "r1", "r2", and so forth. When :term:`PV` increases,
Andrew Geissler09036742021-06-25 14:25:14 -05006698 :term:`PR` is conventionally reset to "r0".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006699
6700 .. note::
6701
Andrew Geissler09036742021-06-25 14:25:14 -05006702 The OpenEmbedded build system does not need the aid of :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006703 to know when to rebuild a recipe. The build system uses the task
Andrew Geissler09209ee2020-12-13 08:44:15 -06006704 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006705 :ref:`stamp <structure-build-tmp-stamps>` and
Andrew Geissler09209ee2020-12-13 08:44:15 -06006706 :ref:`overview-manual/concepts:shared state cache`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006707 mechanisms.
6708
Andrew Geissler09036742021-06-25 14:25:14 -05006709 The :term:`PR` variable primarily becomes significant when a package
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006710 manager dynamically installs packages on an already built image. In
Andrew Geissler09036742021-06-25 14:25:14 -05006711 this case, :term:`PR`, which is the default value of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006712 :term:`PKGR`, helps the package manager distinguish which
6713 package is the most recent one in cases where many packages have the
Andrew Geissler09036742021-06-25 14:25:14 -05006714 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with
6715 the same :term:`PV` usually means that the packages all install the same
6716 upstream version, but with later (:term:`PR`) version packages including
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006717 packaging fixes.
6718
6719 .. note::
6720
Andrew Geissler09036742021-06-25 14:25:14 -05006721 :term:`PR` does not need to be increased for changes that do not change the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006722 package contents or metadata.
6723
Andrew Geissler5f350902021-07-23 13:09:54 -04006724 Because manually managing :term:`PR` can be cumbersome and error-prone,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006725 an automated solution exists. See the
Andrew Geissler517393d2023-01-13 08:55:19 -06006726 ":ref:`dev-manual/packages:working with a pr service`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006727 in the Yocto Project Development Tasks Manual for more information.
6728
Andrew Geisslerf0343792020-11-18 10:42:21 -06006729 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006730 If multiple recipes provide the same item, this variable determines
6731 which recipe is preferred and thus provides the item (i.e. the
6732 preferred provider). You should always suffix this variable with the
6733 name of the provided item. And, you should define the variable using
6734 the preferred recipe's name (:term:`PN`). Here is a common
Andrew Geisslerc926e172021-05-07 16:11:35 -05006735 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006736
6737 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
6738
6739 In the previous example, multiple recipes are providing "virtual/kernel".
Andrew Geissler09036742021-06-25 14:25:14 -05006740 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006741 the recipe you prefer to provide "virtual/kernel".
6742
Patrick Williams39653562024-03-01 08:54:02 -06006743 Here are more examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006744
6745 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
6746 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
6747
6748 For more
Andrew Geissler517393d2023-01-13 08:55:19 -06006749 information, see the ":ref:`dev-manual/new-recipe:using virtual providers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006750 section in the Yocto Project Development Tasks Manual.
6751
6752 .. note::
6753
Andrew Geissler09036742021-06-25 14:25:14 -05006754 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006755 recipe that :term:`PROVIDES` that item but is not selected (defined)
Andrew Geissler09036742021-06-25 14:25:14 -05006756 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006757 desirable since this mechanism is designed to select between mutually
6758 exclusive alternative providers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006759
Andrew Geissler517393d2023-01-13 08:55:19 -06006760 :term:`PREFERRED_PROVIDERS`
6761 See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual.
6762
Patrick Williams96e4b4e2025-02-03 15:49:15 -05006763 :term:`PREFERRED_RPROVIDER`
6764 The :term:`PREFERRED_RPROVIDER` variable works like the
6765 :term:`PREFERRED_PROVIDER` variable, but it denotes packages that provide a
6766 *runtime* component. Runtime providers are declared in recipes that set
6767 the :term:`RPROVIDES` variable for a specific package.
6768
6769 For example::
6770
6771 PREFERRED_RPROVIDER_virtual-x-terminal-emulator = "rxvt-unicode"
6772
6773 This statement sets the runtime provider for the X terminal emulator to
6774 ``rxvt-unicode``. The ``rxvt-unicode`` package is a runtime provider of
6775 this component because the ``rxvt-unicode`` recipe set the following
6776 :term:`RPROVIDES` definition for the ``rxvt-unicode`` (``${PN}``)
6777 package::
6778
6779 RPROVIDES:${PN} = "virtual-x-terminal-emulator"
6780
6781 For more information on virtual providers, see the
6782 ":ref:`dev-manual/new-recipe:using virtual providers`" section in the
6783 Yocto Project Development Tasks Manual.
6784
Andrew Geisslerf0343792020-11-18 10:42:21 -06006785 :term:`PREFERRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006786 If there are multiple versions of a recipe available, this variable
6787 determines which version should be given preference. You must always
6788 suffix the variable with the :term:`PN` you want to select (`python` in
6789 the first example below), and you should specify the :term:`PV`
6790 accordingly (`3.4.0` in the example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006791
Andrew Geissler09036742021-06-25 14:25:14 -05006792 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006793 through the "``%``" character. You can use the character to match any
6794 number of characters, which can be useful when specifying versions
6795 that contain long revision numbers that potentially change. Here are
Andrew Geisslerc926e172021-05-07 16:11:35 -05006796 two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006797
6798 PREFERRED_VERSION_python = "3.4.0"
6799 PREFERRED_VERSION_linux-yocto = "5.0%"
6800
6801 .. note::
6802
6803 The use of the "%" character is limited in that it only works at the end of the
6804 string. You cannot use the wildcard character in any other
6805 location of the string.
6806
Patrick Williams96e4b4e2025-02-03 15:49:15 -05006807 The specified version is matched against :term:`PV`, which does not
6808 necessarily match the version part of the recipe's filename.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006809
Patrick Williams96e4b4e2025-02-03 15:49:15 -05006810 If you want to select a recipe named ``foo_git.bb`` which has :term:`PV`
6811 set to ``1.2.3+git``, you can do so by setting ```PREFERRED_VERSION_foo``
6812 to ``1.2.3%`` (i.e. simply setting ``PREFERRED_VERSION_foo`` to ``git``
6813 will not work as the name of the recipe isn't used, but rather its
6814 :term:`PV` definition).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006815
Andrew Geissler09036742021-06-25 14:25:14 -05006816 Sometimes the :term:`PREFERRED_VERSION` variable can be set by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006817 configuration files in a way that is hard to change. You can use
6818 :term:`OVERRIDES` to set a machine-specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05006819 override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006820
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006821 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006822
6823 Although not recommended, worst case, you can also use the
6824 "forcevariable" override, which is the strongest override possible.
Andrew Geisslerc926e172021-05-07 16:11:35 -05006825 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006826
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006827 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006828
6829 .. note::
6830
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006831 The ``:forcevariable`` override is not handled specially. This override
Andrew Geissler09036742021-06-25 14:25:14 -05006832 only works because the default value of :term:`OVERRIDES` includes "forcevariable".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006833
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006834 If a recipe with the specified version is not available, a warning
6835 message will be shown. See :term:`REQUIRED_VERSION` if you want this
6836 to be an error instead.
6837
Andrew Geisslerf0343792020-11-18 10:42:21 -06006838 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006839 Specifies additional paths from which the OpenEmbedded build system
6840 gets source code. When the build system searches for source code, it
6841 first tries the local download directory. If that location fails, the
Andrew Geissler09036742021-06-25 14:25:14 -05006842 build system tries locations defined by :term:`PREMIRRORS`, the upstream
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006843 source, and then locations specified by
6844 :term:`MIRRORS` in that order.
6845
Patrick Williamsac13d5f2023-11-24 18:59:46 -06006846 The default value for :term:`PREMIRRORS` is defined in the
6847 ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006848
6849 Typically, you could add a specific server for the build system to
6850 attempt before any others by adding something like the following to
6851 the ``local.conf`` configuration file in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006852 :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006853
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006854 PREMIRRORS:prepend = "\
Andrew Geissler595f6302022-01-24 19:11:47 +00006855 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6856 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6857 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \
6858 https://.*/.* &YOCTO_DL_URL;/mirror/sources/"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006859
6860 These changes cause the
6861 build system to intercept Git, FTP, HTTP, and HTTPS requests and
6862 direct them to the ``http://`` sources mirror. You can use
6863 ``file://`` URLs to point to local directories or network shares as
6864 well.
6865
Andrew Geisslerf0343792020-11-18 10:42:21 -06006866 :term:`PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006867 Indicates the importance of a package.
6868
Andrew Geissler09036742021-06-25 14:25:14 -05006869 :term:`PRIORITY` is considered to be part of the distribution policy
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006870 because the importance of any given recipe depends on the purpose for
Andrew Geissler09036742021-06-25 14:25:14 -05006871 which the distribution is being produced. Thus, :term:`PRIORITY` is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006872 normally set within recipes.
6873
Andrew Geissler09036742021-06-25 14:25:14 -05006874 You can set :term:`PRIORITY` to "required", "standard", "extra", and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006875 "optional", which is the default.
6876
Andrew Geisslerf0343792020-11-18 10:42:21 -06006877 :term:`PRIVATE_LIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006878 Specifies libraries installed within a recipe that should be ignored
6879 by the OpenEmbedded build system's shared library resolver. This
6880 variable is typically used when software being built by a recipe has
6881 its own private versions of a library normally provided by another
6882 recipe. In this case, you would not want the package containing the
6883 private libraries to be set as a dependency on other unrelated
6884 packages that should instead depend on the package providing the
6885 standard version of the library.
6886
6887 Libraries specified in this variable should be specified by their
Andrew Geisslerc926e172021-05-07 16:11:35 -05006888 file name. For example, from the Firefox recipe in meta-browser::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006889
6890 PRIVATE_LIBS = "libmozjs.so \
6891 libxpcom.so \
6892 libnspr4.so \
6893 libxul.so \
6894 libmozalloc.so \
6895 libplc4.so \
6896 libplds4.so"
6897
6898 For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006899 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006900 section in the Yocto Project Overview and Concepts Manual.
6901
Andrew Geisslerf0343792020-11-18 10:42:21 -06006902 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006903 A list of aliases by which a particular recipe can be known. By
Andrew Geissler09036742021-06-25 14:25:14 -05006904 default, a recipe's own :term:`PN` is implicitly already in its
6905 :term:`PROVIDES` list and therefore does not need to mention that it
6906 provides itself. If a recipe uses :term:`PROVIDES`, the additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006907 aliases are synonyms for the recipe and can be useful for satisfying
6908 dependencies of other recipes during the build as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05006909 :term:`DEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006910
Andrew Geissler09036742021-06-25 14:25:14 -05006911 Consider the following example :term:`PROVIDES` statement from the recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05006912 file ``eudev_3.2.9.bb``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006913
Andrew Geisslerd1e89492021-02-12 15:35:20 -06006914 PROVIDES += "udev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006915
Andrew Geissler09036742021-06-25 14:25:14 -05006916 The :term:`PROVIDES` statement
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006917 results in the "eudev" recipe also being available as simply "udev".
6918
6919 .. note::
6920
Andrew Geisslerd1e89492021-02-12 15:35:20 -06006921 A recipe's own recipe name (:term:`PN`) is always implicitly prepended
Andrew Geissler517393d2023-01-13 08:55:19 -06006922 to :term:`PROVIDES`, so while using "+=" in the above example may not be
Andrew Geisslerd1e89492021-02-12 15:35:20 -06006923 strictly necessary it is recommended to avoid confusion.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006924
6925 In addition to providing recipes under alternate names, the
Andrew Geissler09036742021-06-25 14:25:14 -05006926 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006927 virtual target is a name that corresponds to some particular
6928 functionality (e.g. a Linux kernel). Recipes that provide the
Andrew Geissler09036742021-06-25 14:25:14 -05006929 functionality in question list the virtual target in :term:`PROVIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006930 Recipes that depend on the functionality in question can include the
Andrew Geissler09036742021-06-25 14:25:14 -05006931 virtual target in :term:`DEPENDS` to leave the choice of provider open.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006932
6933 Conventionally, virtual targets have names on the form
6934 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
6935 of the name and has no syntactical significance.
6936
6937 The :term:`PREFERRED_PROVIDER` variable is
6938 used to select which particular recipe provides a virtual target.
6939
6940 .. note::
6941
Patrick Williamsb58112e2024-03-07 11:16:36 -06006942 A corresponding mechanism for virtual runtime dependencies (packages)
6943 exists. However, the mechanism does not depend on any special
6944 functionality beyond ordinary variable assignments. For example,
6945 :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the
6946 package of the component that manages the ``/dev`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006947
6948 Setting the "preferred provider" for runtime dependencies is as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006949 simple as using the following assignment in a configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006950
6951 VIRTUAL-RUNTIME_dev_manager = "udev"
6952
6953
Andrew Geisslerf0343792020-11-18 10:42:21 -06006954 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006955 The network based :term:`PR` service host and port.
6956
Andrew Geissler87f5cff2022-09-30 13:13:31 -05006957 The ``conf/templates/default/local.conf.sample.extended`` configuration
6958 file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST`
6959 variable is set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006960
6961 PRSERV_HOST = "localhost:0"
6962
6963 You must
6964 set the variable if you want to automatically start a local :ref:`PR
Andrew Geissler517393d2023-01-13 08:55:19 -06006965 service <dev-manual/packages:working with a pr service>`. You can
Andrew Geissler09036742021-06-25 14:25:14 -05006966 set :term:`PRSERV_HOST` to other values to use a remote PR service.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006967
Patrick Williams84603582024-12-14 08:00:57 -05006968 :term:`PRSERV_UPSTREAM`
6969 This variable can be used to specify an upstream PR server for the local
6970 PR server to connect to, in the form of ``host:port``.
6971
6972 This makes it possible to implement local fixes to an upstream package.
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006973
6974 :term:`PSEUDO_IGNORE_PATHS`
6975 A comma-separated (without spaces) list of path prefixes that should be ignored
6976 by pseudo when monitoring and recording file operations, in order to avoid
6977 problems with files being written to outside of the pseudo context and
6978 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list
6979 and can include partial directory (or file) names.
6980
6981
Andrew Geisslerf0343792020-11-18 10:42:21 -06006982 :term:`PTEST_ENABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006983 Specifies whether or not :ref:`Package
Patrick Williams96e4b4e2025-02-03 15:49:15 -05006984 Test <test-manual/ptest:testing packages with ptest>` (ptest)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006985 functionality is enabled when building a recipe. You should not set
6986 this variable directly. Enabling and disabling building Package Tests
6987 at build time should be done by adding "ptest" to (or removing it
6988 from) :term:`DISTRO_FEATURES`.
6989
Andrew Geisslerf0343792020-11-18 10:42:21 -06006990 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006991 The version of the recipe. The version is normally extracted from the
6992 recipe filename. For example, if the recipe is named
Andrew Geissler09036742021-06-25 14:25:14 -05006993 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1".
6994 :term:`PV` is generally not overridden within a recipe unless it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006995 building an unstable (i.e. development) version from a source code
6996 repository (e.g. Git or Subversion).
6997
Andrew Geissler09036742021-06-25 14:25:14 -05006998 :term:`PV` is the default value of the :term:`PKGV` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006999
Patrick Williams975a06f2022-10-21 14:42:47 -05007000 :term:`PYPI_PACKAGE`
Andrew Geissler517393d2023-01-13 08:55:19 -06007001 When inheriting the :ref:`ref-classes-pypi` class, specifies the
Patrick Williams975a06f2022-10-21 14:42:47 -05007002 `PyPI <https://pypi.org/>`__ package name to be built. The default value
7003 is set based upon :term:`BPN` (stripping any "python-" or "python3-"
7004 prefix off if present), however for some packages it will need to be set
7005 explicitly if that will not match the package name (e.g. where the
7006 package name has a prefix, underscores, uppercase letters etc.)
7007
Andrew Geissleredff4922024-06-19 14:12:16 -04007008 :term:`PYPI_PACKAGE_EXT`
7009 When inheriting the :ref:`ref-classes-pypi` class, specifies the
7010 file extension to use when fetching a package from `PyPI
7011 <https://pypi.org/>`__. Default is ``tar.gz``.
7012
7013 :term:`PYPI_SRC_URI`
7014 When inheriting the :ref:`ref-classes-pypi` class, specifies the
7015 full `pythonhosted <https://files.pythonhosted.org/>`__ URI for
7016 fetching the package to be built. The default value is constructed
7017 based upon :term:`PYPI_PACKAGE`, :term:`PYPI_PACKAGE_EXT`, and
7018 :term:`PV`. Most recipes will not need to set this variable unless
7019 they are building an unstable (i.e. development) version.
7020
Andrew Geisslerf0343792020-11-18 10:42:21 -06007021 :term:`PYTHON_ABI`
Andrew Geissler517393d2023-01-13 08:55:19 -06007022 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7023 class, denotes the Application Binary Interface (ABI) currently in use
7024 for Python. By default, the ABI is "m". You do not have to set this
7025 variable as the OpenEmbedded build system sets it for you.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007026
7027 The OpenEmbedded build system uses the ABI to construct directory
7028 names used when installing the Python headers and libraries in
7029 sysroot (e.g. ``.../python3.3m/...``).
7030
Patrick Williams03907ee2022-05-01 06:28:52 -05007031 :term:`QA_EMPTY_DIRS`
7032 Specifies a list of directories that are expected to be empty when
7033 packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or
7034 :term:`WARN_QA` these will be checked and an error or warning
7035 (respectively) will be produced.
7036
7037 The default :term:`QA_EMPTY_DIRS` value is set in
7038 :ref:`insane.bbclass <ref-classes-insane>`.
7039
7040 :term:`QA_EMPTY_DIRS_RECOMMENDATION`
7041 Specifies a recommendation for why a directory must be empty,
7042 which will be included in the error message if a specific directory
7043 is found to contain files. Must be overridden with the directory
7044 path to match on.
7045
7046 If no recommendation is specified for a directory, then the default
7047 "but it is expected to be empty" will be used.
7048
7049 An example message shows if files were present in '/dev'::
7050
7051 QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"
7052
Andrew Geisslerf0343792020-11-18 10:42:21 -06007053 :term:`RANLIB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007054 The minimal command and arguments to run ``ranlib``.
7055
Andrew Geisslerf0343792020-11-18 10:42:21 -06007056 :term:`RCONFLICTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007057 The list of packages that conflict with packages. Note that packages
7058 will not be installed if conflicting packages are not first removed.
7059
7060 Like all package-controlling variables, you must always use them in
Andrew Geisslerc926e172021-05-07 16:11:35 -05007061 conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007062
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007063 RCONFLICTS:${PN} = "another_conflicting_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007064
7065 BitBake, which the OpenEmbedded build system uses, supports
7066 specifying versioned dependencies. Although the syntax varies
7067 depending on the packaging format, BitBake hides these differences
7068 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05007069 :term:`RCONFLICTS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007070
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007071 RCONFLICTS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007072
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007073 For ``operator``, you can specify the following:
7074
7075 - =
7076 - <
7077 - >
7078 - <=
7079 - >=
7080
7081 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05007082 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007083
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007084 RCONFLICTS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007085
Andrew Geisslerf0343792020-11-18 10:42:21 -06007086 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007087 Lists runtime dependencies of a package. These dependencies are other
7088 packages that must be installed in order for the package to function
7089 correctly. As an example, the following assignment declares that the
7090 package ``foo`` needs the packages ``bar`` and ``baz`` to be
Andrew Geisslerc926e172021-05-07 16:11:35 -05007091 installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007092
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007093 RDEPENDS:foo = "bar baz"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007094
7095 The most common types of package
7096 runtime dependencies are automatically detected and added. Therefore,
Andrew Geissler09036742021-06-25 14:25:14 -05007097 most recipes do not need to set :term:`RDEPENDS`. For more information,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007098 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007099 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007100 section in the Yocto Project Overview and Concepts Manual.
7101
Andrew Geissler09036742021-06-25 14:25:14 -05007102 The practical effect of the above :term:`RDEPENDS` assignment is that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007103 ``bar`` and ``baz`` will be declared as dependencies inside the
7104 package ``foo`` when it is written out by one of the
Patrick Williams2194f502022-10-16 14:26:09 -05007105 :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007106 Exactly how this is done depends on which package format is used,
7107 which is determined by
7108 :term:`PACKAGE_CLASSES`. When the
7109 corresponding package manager installs the package, it will know to
7110 also install the packages on which it depends.
7111
7112 To ensure that the packages ``bar`` and ``baz`` get built, the
Andrew Geissler09036742021-06-25 14:25:14 -05007113 previous :term:`RDEPENDS` assignment also causes a task dependency to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007114 added. This dependency is from the recipe's
7115 :ref:`ref-tasks-build` (not to be confused with
7116 :ref:`ref-tasks-compile`) task to the
Patrick Williams2194f502022-10-16 14:26:09 -05007117 :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007118 ``baz``.
7119
Andrew Geissler09036742021-06-25 14:25:14 -05007120 The names of the packages you list within :term:`RDEPENDS` must be the
Andrew Geissler615f2f12022-07-15 14:00:58 -05007121 names of other packages --- they cannot be recipe names. Although
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007122 package names and recipe names usually match, the important point
Andrew Geissler09036742021-06-25 14:25:14 -05007123 here is that you are providing package names within the :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007124 variable. For an example of the default list of packages created from
7125 a recipe, see the :term:`PACKAGES` variable.
7126
Andrew Geissler09036742021-06-25 14:25:14 -05007127 Because the :term:`RDEPENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007128 you should always use the variable in a form with an attached package
7129 name (remember that a single recipe can build multiple packages). For
7130 example, suppose you are building a development package that depends
7131 on the ``perl`` package. In this case, you would use the following
Andrew Geissler09036742021-06-25 14:25:14 -05007132 :term:`RDEPENDS` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007133
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007134 RDEPENDS:${PN}-dev += "perl"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007135
7136 In the example,
7137 the development package depends on the ``perl`` package. Thus, the
Andrew Geissler5f350902021-07-23 13:09:54 -04007138 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007139 the variable.
7140
7141 .. note::
7142
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007143 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007144 by default. This default is set in the BitBake configuration file
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007145 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007146 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007147 rather than the "=" operator.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007148
Andrew Geissler09036742021-06-25 14:25:14 -05007149 The package names you use with :term:`RDEPENDS` must appear as they would
7150 in the :term:`PACKAGES` variable. The :term:`PKG` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007151 allows a different name to be used for the final package (e.g. the
Andrew Geissler517393d2023-01-13 08:55:19 -06007152 :ref:`ref-classes-debian` class uses this to rename
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007153 packages), but this final package name cannot be used with
Andrew Geissler09036742021-06-25 14:25:14 -05007154 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007155 independent of the package format used.
7156
7157 BitBake, which the OpenEmbedded build system uses, supports
7158 specifying versioned dependencies. Although the syntax varies
7159 depending on the packaging format, BitBake hides these differences
7160 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05007161 :term:`RDEPENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007162
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007163 RDEPENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007164
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007165 For ``operator``, you can specify the following:
7166
7167 - =
7168 - <
7169 - >
7170 - <=
7171 - >=
7172
7173 For version, provide the version number.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007174
7175 .. note::
7176
Andrew Geissler09036742021-06-25 14:25:14 -05007177 You can use :term:`EXTENDPKGV` to provide a full package version
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007178 specification.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007179
7180 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05007181 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007182
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007183 RDEPENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007184
Andrew Geisslerfc113ea2023-03-31 09:59:46 -05007185 For information on build-time dependencies, see the :term:`DEPENDS`
7186 variable. You can also see the
7187 ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
7188 ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
7189 BitBake User Manual for additional information on tasks and dependencies.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007190
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007191 :term:`RECIPE_MAINTAINER`
7192 This variable defines the name and e-mail address of the maintainer of a
7193 recipe. Such information can be used by human users submitted changes,
7194 and by automated tools to send notifications, for example about
7195 vulnerabilities or source updates.
7196
7197 The variable can be defined in a global distribution :oe_git:`maintainers.inc
7198 </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file::
7199
7200 meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>"
7201
7202 It can also be directly defined in a recipe,
7203 for example in the ``libgpiod`` one::
7204
7205 RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>"
7206
Andrew Geissler5199d832021-09-24 16:47:35 -05007207 :term:`RECIPE_NO_UPDATE_REASON`
7208 If a recipe should not be replaced by a more recent upstream version,
7209 putting the reason why in this variable in a recipe allows
7210 ``devtool check-upgrade-status`` command to display it, as explained
7211 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`"
7212 section.
7213
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007214 :term:`RECIPE_SYSROOT`
7215 This variable points to the directory that holds all files populated from
7216 recipes specified in :term:`DEPENDS`. As the name indicates,
7217 think of this variable as a custom root (``/``) for the recipe that will be
7218 used by the compiler in order to find headers and other files needed to complete
7219 its job.
7220
7221 This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET`
7222 according to the type of the recipe and the build target.
7223
7224 To better understand this variable, consider the following examples:
7225
7226 - For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"``
7227
7228 - For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"``
7229 or other library sysroot directories.
7230
7231 The default value is ``"${WORKDIR}/recipe-sysroot"``.
7232 Do not modify it.
7233
7234 :term:`RECIPE_SYSROOT_NATIVE`
7235 This is similar to :term:`RECIPE_SYSROOT` but the populated files are from
7236 ``-native`` recipes. This allows a recipe built for the target machine to
7237 use ``native`` tools.
7238
7239 This variable is related to :term:`STAGING_DIR_NATIVE`.
7240
7241 The default value is ``"${WORKDIR}/recipe-sysroot-native"``.
7242 Do not modify it.
7243
Patrick Williams84603582024-12-14 08:00:57 -05007244 :term:`RECIPE_UPGRADE_EXTRA_TASKS`
7245 When upgrading a recipe with ``devtool upgrade``, the variable
7246 :term:`RECIPE_UPGRADE_EXTRA_TASKS` specifies a space-delimited list of
7247 tasks to run after the new sources have been unpacked.
7248
Andrew Geissleredff4922024-06-19 14:12:16 -04007249 For some recipes, after the new source has been unpacked, additional tasks
7250 may need to be run during an upgrade. A good example of this is recipes
7251 which inherit :ref:`ref-classes-cargo-update-recipe-crates`, where the
7252 `do_update_crates` task needs to be run whenever Cargo.toml/Cargo.lock have
7253 changed in the source.
7254
Andrew Geissler517393d2023-01-13 08:55:19 -06007255 :term:`REPODIR`
7256 See :term:`bitbake:REPODIR` in the BitBake manual.
7257
Andrew Geisslerf0343792020-11-18 10:42:21 -06007258 :term:`REQUIRED_DISTRO_FEATURES`
Andrew Geissler517393d2023-01-13 08:55:19 -06007259 When inheriting the :ref:`ref-classes-features_check`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007260 class, this variable identifies distribution features that must exist
7261 in the current configuration in order for the OpenEmbedded build
7262 system to build the recipe. In other words, if the
Andrew Geissler09036742021-06-25 14:25:14 -05007263 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not
7264 appear in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -06007265 the recipe will be skipped, and if the build system attempts to build
7266 the recipe then an error will be triggered.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007267
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007268 :term:`REQUIRED_VERSION`
7269 If there are multiple versions of a recipe available, this variable
7270 determines which version should be given preference.
7271 :term:`REQUIRED_VERSION` works in exactly the same manner as
7272 :term:`PREFERRED_VERSION`, except that if the specified version is not
7273 available then an error message is shown and the build fails
7274 immediately.
7275
7276 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
7277 for the same recipe, the :term:`REQUIRED_VERSION` value applies.
7278
Patrick Williams84603582024-12-14 08:00:57 -05007279 :term:`RETAIN_DIRS_ALWAYS`
7280 When inheriting the :ref:`ref-classes-retain` class, this variable holds
7281 space-separated recipe-specific directories to always save in a tarball
7282 whether the recipe build has failed or not.
7283
7284 :term:`RETAIN_DIRS_FAILURE`
7285 When inheriting the :ref:`ref-classes-retain` class, this variable holds
7286 space-separated recipe-specific directories to save in a tarball on
7287 failure of the recipe's build.
7288
7289 :term:`RETAIN_DIRS_GLOBAL_ALWAYS`
7290 When inheriting the :ref:`ref-classes-retain` class, this variable holds
7291 space-separated directories that are not specific to a recipe to save in a
7292 tarball whether the build has failed or not.
7293
7294 :term:`RETAIN_DIRS_GLOBAL_FAILURE`
7295 When inheriting the :ref:`ref-classes-retain` class, this variable holds
7296 space-separated directories that are not specific to a recipe to save in a
7297 tarball on build failure.
7298
7299 :term:`RETAIN_ENABLED`
7300 Disables the creation of a tarball of the work directory done by the
7301 :ref:`ref-classes-retain` class. Can be set to specific recipes to disable
7302 the class when the class was inherited globally with :term:`INHERIT`.
7303
7304 :term:`RETAIN_OUTDIR`
7305 When inheriting the :ref:`ref-classes-retain` class, this variable
7306 specifies the directory where to save the tarball of the work directory.
7307 The default directory is ``${TMPDIR}/retain``.
7308
7309 :term:`RETAIN_TARBALL_SUFFIX`
7310 When inheriting the :ref:`ref-classes-retain` class, this variable
7311 specifies the suffix of the tarball of the work directory. The default
7312 suffix is ``${DATETIME}.tar.gz``.
7313
Andrew Geisslerf0343792020-11-18 10:42:21 -06007314 :term:`RM_WORK_EXCLUDE`
Andrew Geissler517393d2023-01-13 08:55:19 -06007315 With :ref:`ref-classes-rm-work` enabled, this variable
7316 specifies a list of recipes whose work directories should not be removed.
7317 See the ":ref:`ref-classes-rm-work`" section for more details.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007318
Andrew Geisslerf0343792020-11-18 10:42:21 -06007319 :term:`ROOT_HOME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007320 Defines the root home directory. By default, this directory is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007321 follows in the BitBake configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007322
7323 ROOT_HOME ??= "/home/root"
7324
7325 .. note::
7326
7327 This default value is likely used because some embedded solutions
7328 prefer to have a read-only root filesystem and prefer to keep
7329 writeable data in one place.
7330
7331 You can override the default by setting the variable in any layer or
7332 in the ``local.conf`` file. Because the default is set using a "weak"
7333 assignment (i.e. "??="), you can use either of the following forms to
Andrew Geisslerc926e172021-05-07 16:11:35 -05007334 define your override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007335
7336 ROOT_HOME = "/root"
7337 ROOT_HOME ?= "/root"
7338
7339 These
7340 override examples use ``/root``, which is probably the most commonly
7341 used override.
7342
Andrew Geisslerf0343792020-11-18 10:42:21 -06007343 :term:`ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007344 Indicates a filesystem image to include as the root filesystem.
7345
Andrew Geissler09036742021-06-25 14:25:14 -05007346 The :term:`ROOTFS` variable is an optional variable used with the
Andrew Geissler517393d2023-01-13 08:55:19 -06007347 :ref:`ref-classes-image-live` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007348
Andrew Geisslerf0343792020-11-18 10:42:21 -06007349 :term:`ROOTFS_POSTINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007350 Specifies a list of functions to call after the OpenEmbedded build
7351 system has installed packages. You can specify functions separated by
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007352 spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007353
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007354 ROOTFS_POSTINSTALL_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007355
7356 If you need to pass the root filesystem path to a command within a
7357 function, you can use ``${IMAGE_ROOTFS}``, which points to the
7358 directory that becomes the root filesystem image. See the
7359 :term:`IMAGE_ROOTFS` variable for more
7360 information.
7361
Andrew Geisslerf0343792020-11-18 10:42:21 -06007362 :term:`ROOTFS_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007363 Specifies a list of functions to call once the OpenEmbedded build
7364 system has created the root filesystem. You can specify functions
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007365 separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007366
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007367 ROOTFS_POSTPROCESS_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007368
7369 If you need to pass the root filesystem path to a command within a
7370 function, you can use ``${IMAGE_ROOTFS}``, which points to the
7371 directory that becomes the root filesystem image. See the
7372 :term:`IMAGE_ROOTFS` variable for more
7373 information.
7374
Andrew Geisslerf0343792020-11-18 10:42:21 -06007375 :term:`ROOTFS_POSTUNINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007376 Specifies a list of functions to call after the OpenEmbedded build
7377 system has removed unnecessary packages. When runtime package
7378 management is disabled in the image, several packages are removed
7379 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007380 You can specify functions separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007381
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007382 ROOTFS_POSTUNINSTALL_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007383
7384 If you need to pass the root filesystem path to a command within a
7385 function, you can use ``${IMAGE_ROOTFS}``, which points to the
7386 directory that becomes the root filesystem image. See the
7387 :term:`IMAGE_ROOTFS` variable for more
7388 information.
7389
Andrew Geisslerf0343792020-11-18 10:42:21 -06007390 :term:`ROOTFS_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007391 Specifies a list of functions to call before the OpenEmbedded build
7392 system has created the root filesystem. You can specify functions
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007393 separated by spaces::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007394
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007395 ROOTFS_PREPROCESS_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007396
7397 If you need to pass the root filesystem path to a command within a
7398 function, you can use ``${IMAGE_ROOTFS}``, which points to the
7399 directory that becomes the root filesystem image. See the
7400 :term:`IMAGE_ROOTFS` variable for more
7401 information.
7402
Patrick Williams44b3caf2024-04-12 16:51:14 -05007403 :term:`RPMBUILD_EXTRA_PARAMS`
7404 Specifies extra user-defined parameters for the ``rpmbuild`` command.
7405
Andrew Geisslerf0343792020-11-18 10:42:21 -06007406 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007407 A list of package name aliases that a package also provides. These
7408 aliases are useful for satisfying runtime dependencies of other
7409 packages both during the build and on the target (as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05007410 :term:`RDEPENDS`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007411
7412 .. note::
7413
Andrew Geissler09036742021-06-25 14:25:14 -05007414 A package's own name is implicitly already in its :term:`RPROVIDES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007415
7416 As with all package-controlling variables, you must always use the
7417 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05007418 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007419
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007420 RPROVIDES:${PN} = "widget-abi-2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007421
Andrew Geisslerf0343792020-11-18 10:42:21 -06007422 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007423 A list of packages that extends the usability of a package being
7424 built. The package being built does not depend on this list of
7425 packages in order to successfully build, but rather uses them for
7426 extended usability. To specify runtime dependencies for packages, see
Andrew Geissler09036742021-06-25 14:25:14 -05007427 the :term:`RDEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007428
Andrew Geissler09036742021-06-25 14:25:14 -05007429 The package manager will automatically install the :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007430 list of packages when installing the built package. However, you can
7431 prevent listed packages from being installed by using the
7432 :term:`BAD_RECOMMENDATIONS`,
7433 :term:`NO_RECOMMENDATIONS`, and
7434 :term:`PACKAGE_EXCLUDE` variables.
7435
Andrew Geissler09036742021-06-25 14:25:14 -05007436 Packages specified in :term:`RRECOMMENDS` need not actually be produced.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007437 However, there must be a recipe providing each package, either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007438 through the :term:`PACKAGES` or
7439 :term:`PACKAGES_DYNAMIC` variables or the
7440 :term:`RPROVIDES` variable, or an error will occur
7441 during the build. If such a recipe does exist and the package is not
7442 produced, the build continues without error.
7443
Andrew Geissler09036742021-06-25 14:25:14 -05007444 Because the :term:`RRECOMMENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007445 you should always attach an override to the variable to specify the
7446 particular package whose usability is being extended. For example,
7447 suppose you are building a development package that is extended to
7448 support wireless functionality. In this case, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007449 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007450
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007451 RRECOMMENDS:${PN}-dev += "wireless_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007452
7453 In the
7454 example, the package name (``${PN}-dev``) must appear as it would in
Andrew Geissler09036742021-06-25 14:25:14 -05007455 the :term:`PACKAGES` namespace before any renaming of the output package
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00007456 by classes such as :ref:`ref-classes-debian`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007457
7458 BitBake, which the OpenEmbedded build system uses, supports
7459 specifying versioned recommends. Although the syntax varies depending
7460 on the packaging format, BitBake hides these differences from you.
7461 Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05007462 :term:`RRECOMMENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007463
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007464 RRECOMMENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007465
7466 For ``operator``, you can specify the following:
7467
7468 - =
7469 - <
7470 - >
7471 - <=
7472 - >=
7473
7474 For example, the following sets up a recommend on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05007475 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007476
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007477 RRECOMMENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007478
Andrew Geisslerf0343792020-11-18 10:42:21 -06007479 :term:`RREPLACES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007480 A list of packages replaced by a package. The package manager uses
7481 this variable to determine which package should be installed to
7482 replace other package(s) during an upgrade. In order to also have the
7483 other package(s) removed at the same time, you must add the name of
Andrew Geissler09036742021-06-25 14:25:14 -05007484 the other package to the :term:`RCONFLICTS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007485
7486 As with all package-controlling variables, you must use this variable
Andrew Geisslerc926e172021-05-07 16:11:35 -05007487 in conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007488
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007489 RREPLACES:${PN} = "other_package_being_replaced"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007490
7491 BitBake, which the OpenEmbedded build system uses, supports
7492 specifying versioned replacements. Although the syntax varies
7493 depending on the packaging format, BitBake hides these differences
7494 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05007495 :term:`RREPLACES` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007496
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007497 RREPLACES:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007498
7499 For ``operator``, you can specify the following:
7500
7501 - =
7502 - <
7503 - >
7504 - <=
7505 - >=
7506
7507 For example, the following sets up a replacement using version 1.2
Andrew Geisslerc926e172021-05-07 16:11:35 -05007508 or greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007509
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007510 RREPLACES:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007511
Andrew Geisslerf0343792020-11-18 10:42:21 -06007512 :term:`RSUGGESTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007513 A list of additional packages that you can suggest for installation
7514 by the package manager at the time a package is installed. Not all
7515 package managers support this functionality.
7516
7517 As with all package-controlling variables, you must always use this
7518 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05007519 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007520
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007521 RSUGGESTS:${PN} = "useful_package another_package"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007522
Patrick Williams8e7b46e2023-05-01 14:19:06 -05007523 :term:`RUST_CHANNEL`
7524 Specifies which version of Rust to build - "stable", "beta" or "nightly".
7525 The default value is "stable". Set this at your own risk, as values other
7526 than "stable" are not guaranteed to work at a given time.
7527
Andrew Geisslerf0343792020-11-18 10:42:21 -06007528 :term:`S`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007529 The location in the :term:`Build Directory` where
7530 unpacked recipe source code resides. By default, this directory is
7531 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
7532 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
7533 version. If the source tarball extracts the code to a directory named
7534 anything other than ``${BPN}-${PV}``, or if the source code is
7535 fetched from an SCM such as Git or Subversion, then you must set
Andrew Geissler09036742021-06-25 14:25:14 -05007536 :term:`S` in the recipe so that the OpenEmbedded build system knows where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007537 to find the unpacked source.
7538
7539 As an example, assume a :term:`Source Directory`
Patrick Williams2390b1b2022-11-03 13:47:49 -05007540 top-level folder named ``poky`` and a default :term:`Build Directory` at
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007541 ``poky/build``. In this case, the work directory the build system
Andrew Geisslerc926e172021-05-07 16:11:35 -05007542 uses to keep the unpacked recipe for ``db`` is the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007543
7544 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
7545
7546 The unpacked source code resides in the ``db-5.1.19`` folder.
7547
7548 This next example assumes a Git repository. By default, Git
7549 repositories are cloned to ``${WORKDIR}/git`` during
7550 :ref:`ref-tasks-fetch`. Since this path is different
Andrew Geissler09036742021-06-25 14:25:14 -05007551 from the default value of :term:`S`, you must set it specifically so the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007552 source can be located::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007553
Andrew Geissler9aee5002022-03-30 16:27:02 +00007554 SRC_URI = "git://path/to/repo.git;branch=main"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007555 S = "${WORKDIR}/git"
7556
Andrew Geisslerf0343792020-11-18 10:42:21 -06007557 :term:`SANITY_REQUIRED_UTILITIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007558 Specifies a list of command-line utilities that should be checked for
7559 during the initial sanity checking process when running BitBake. If
7560 any of the utilities are not installed on the build host, then
7561 BitBake immediately exits with an error.
7562
Andrew Geisslerf0343792020-11-18 10:42:21 -06007563 :term:`SANITY_TESTED_DISTROS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007564 A list of the host distribution identifiers that the build system has
7565 been tested against. Identifiers consist of the host distributor ID
7566 followed by the release, as reported by the ``lsb_release`` tool or
7567 as read from ``/etc/lsb-release``. Separate the list items with
Andrew Geissler09036742021-06-25 14:25:14 -05007568 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007569 not empty and the current value of
7570 :term:`NATIVELSBSTRING` does not appear in the
7571 list, then the build system reports a warning that indicates the
7572 current host distribution has not been tested as a build host.
7573
Andrew Geisslerf0343792020-11-18 10:42:21 -06007574 :term:`SDK_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007575 The target architecture for the SDK. Typically, you do not directly
7576 set this variable. Instead, use :term:`SDKMACHINE`.
7577
Patrick Williams8e7b46e2023-05-01 14:19:06 -05007578 :term:`SDK_ARCHIVE_TYPE`
7579 Specifies the type of archive to create for the SDK. Valid values:
7580
7581 - ``tar.xz`` (default)
Patrick Williams96e4b4e2025-02-03 15:49:15 -05007582 - ``tar.zst``
7583 - ``7zip``
Patrick Williams8e7b46e2023-05-01 14:19:06 -05007584 - ``zip``
7585
7586 Only one archive type can be specified.
7587
Patrick Williams975a06f2022-10-21 14:42:47 -05007588 :term:`SDK_BUILDINFO_FILE`
Andrew Geissler517393d2023-01-13 08:55:19 -06007589 When using the :ref:`ref-classes-image-buildinfo` class,
Patrick Williams975a06f2022-10-21 14:42:47 -05007590 specifies the file in the SDK to write the build information into. The
7591 default value is "``/buildinfo``".
7592
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007593 :term:`SDK_CUSTOM_TEMPLATECONF`
Andrew Geissler09036742021-06-25 14:25:14 -05007594 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
Patrick Williams2390b1b2022-11-03 13:47:49 -05007595 "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007596 (:term:`TOPDIR`) then this will be copied into the SDK.
7597
Andrew Geisslerf0343792020-11-18 10:42:21 -06007598 :term:`SDK_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007599 The directory set up and used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06007600 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the
7601 SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>`
7602 class defines :term:`SDK_DEPLOY` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007603
7604 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
7605
Andrew Geisslerf0343792020-11-18 10:42:21 -06007606 :term:`SDK_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007607 The parent directory used by the OpenEmbedded build system when
7608 creating SDK output. The
7609 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
Andrew Geisslerc926e172021-05-07 16:11:35 -05007610 the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007611
7612 SDK_DIR = "${WORKDIR}/sdk"
7613
7614 .. note::
7615
Andrew Geissler09036742021-06-25 14:25:14 -05007616 The :term:`SDK_DIR` directory is a temporary directory as it is part of
7617 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007618
Andrew Geisslerf0343792020-11-18 10:42:21 -06007619 :term:`SDK_EXT_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007620 Controls whether or not shared state artifacts are copied into the
7621 extensible SDK. The default value of "full" copies all of the
7622 required shared state artifacts into the extensible SDK. The value
7623 "minimal" leaves these artifacts out of the SDK.
7624
7625 .. note::
7626
7627 If you set the variable to "minimal", you need to ensure
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007628 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the
7629 artifacts to be fetched as needed.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007630
Andrew Geisslerf0343792020-11-18 10:42:21 -06007631 :term:`SDK_HOST_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007632 The manifest file for the host part of the SDK. This file lists all
7633 the installed packages that make up the host part of the SDK. The
7634 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007635 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007636
7637 packagename packagearch version
7638
7639 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05007640 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007641
7642 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
7643
7644 The location is derived using the :term:`SDK_DEPLOY` and
7645 :term:`TOOLCHAIN_OUTPUTNAME` variables.
7646
Andrew Geisslerf0343792020-11-18 10:42:21 -06007647 :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007648 When set to "1", specifies to include the packagedata for all recipes
7649 in the "world" target in the extensible SDK. Including this data
7650 allows the ``devtool search`` command to find these recipes in search
7651 results, as well as allows the ``devtool add`` command to map
7652 dependencies more effectively.
7653
7654 .. note::
7655
Andrew Geissler09036742021-06-25 14:25:14 -05007656 Enabling the :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007657 variable significantly increases build time because all of world
7658 needs to be built. Enabling the variable also slightly increases
7659 the size of the extensible SDK.
7660
Andrew Geisslerf0343792020-11-18 10:42:21 -06007661 :term:`SDK_INCLUDE_TOOLCHAIN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007662 When set to "1", specifies to include the toolchain in the extensible
7663 SDK. Including the toolchain is useful particularly when
7664 :term:`SDK_EXT_TYPE` is set to "minimal" to keep
7665 the SDK reasonably small but you still want to provide a usable
7666 toolchain. For example, suppose you want to use the toolchain from an
7667 IDE or from other tools and you do not want to perform additional
7668 steps to install the toolchain.
7669
Andrew Geissler09036742021-06-25 14:25:14 -05007670 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if
7671 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
7672 :term:`SDK_EXT_TYPE` is set to "full".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007673
Andrew Geisslerf0343792020-11-18 10:42:21 -06007674 :term:`SDK_NAME`
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007675 The base name for SDK output files. The default value (as set in
7676 ``meta-poky/conf/distro/poky.conf``) is derived from the
7677 :term:`DISTRO`,
7678 :term:`TCLIBC`,
7679 :term:`SDKMACHINE`,
7680 :term:`IMAGE_BASENAME`,
7681 :term:`TUNE_PKGARCH`, and
7682 :term:`MACHINE` variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007683
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007684 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007685
Andrew Geisslerf0343792020-11-18 10:42:21 -06007686 :term:`SDK_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007687 Specifies the operating system for which the SDK will be built. The
7688 default value is the value of :term:`BUILD_OS`.
7689
Andrew Geisslerf0343792020-11-18 10:42:21 -06007690 :term:`SDK_OUTPUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007691 The location used by the OpenEmbedded build system when creating SDK
7692 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -05007693 class defines the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007694
7695 SDK_DIR = "${WORKDIR}/sdk"
7696 SDK_OUTPUT = "${SDK_DIR}/image"
7697 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
7698
7699 .. note::
7700
Andrew Geissler09036742021-06-25 14:25:14 -05007701 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007702 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is
7703 :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007704
Andrew Geisslerf0343792020-11-18 10:42:21 -06007705 :term:`SDK_PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007706 Specifies a list of architectures compatible with the SDK machine.
7707 This variable is set automatically and should not normally be
7708 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05007709 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007710 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
7711
Andrew Geisslerf0343792020-11-18 10:42:21 -06007712 :term:`SDK_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007713 Specifies a list of functions to call once the OpenEmbedded build
7714 system creates the SDK. You can specify functions separated by
Patrick Williamsac13d5f2023-11-24 18:59:46 -06007715 spaces:
7716
7717 SDK_POSTPROCESS_COMMAND += "function"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007718
7719 If you need to pass an SDK path to a command within a function, you
7720 can use ``${SDK_DIR}``, which points to the parent directory used by
7721 the OpenEmbedded build system when creating SDK output. See the
7722 :term:`SDK_DIR` variable for more information.
7723
Andrew Geisslerf0343792020-11-18 10:42:21 -06007724 :term:`SDK_PREFIX`
Andrew Geissler517393d2023-01-13 08:55:19 -06007725 The toolchain binary prefix used for
7726 :ref:`ref-classes-nativesdk` recipes. The
Andrew Geissler09036742021-06-25 14:25:14 -05007727 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007728 :term:`TARGET_PREFIX` when building
7729 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
7730
Andrew Geisslerf0343792020-11-18 10:42:21 -06007731 :term:`SDK_RECRDEP_TASKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007732 A list of shared state tasks added to the extensible SDK. By default,
7733 the following tasks are added:
7734
Patrick Williams2194f502022-10-16 14:26:09 -05007735 - :ref:`ref-tasks-populate_lic`
7736 - :ref:`ref-tasks-package_qa`
7737 - :ref:`ref-tasks-populate_sysroot`
7738 - :ref:`ref-tasks-deploy`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007739
7740 Despite the default value of "" for the
Andrew Geissler09036742021-06-25 14:25:14 -05007741 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007742 to the SDK. To specify tasks beyond these four, you need to use the
Andrew Geissler09036742021-06-25 14:25:14 -05007743 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007744 tasks that are needed in order to build
7745 :term:`SDK_TARGETS`).
7746
Andrew Geisslerf0343792020-11-18 10:42:21 -06007747 :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007748 Specifies the system, including the architecture and the operating
7749 system, for which the SDK will be built.
7750
7751 The OpenEmbedded build system automatically sets this variable based
7752 on :term:`SDK_ARCH`,
7753 :term:`SDK_VENDOR`, and
Andrew Geissler09036742021-06-25 14:25:14 -05007754 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007755 variable yourself.
7756
Andrew Geisslerf0343792020-11-18 10:42:21 -06007757 :term:`SDK_TARGET_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007758 The manifest file for the target part of the SDK. This file lists all
7759 the installed packages that make up the target part of the SDK. The
7760 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007761 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007762
7763 packagename packagearch version
7764
7765 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05007766 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007767
7768 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
7769
7770 The location is derived using the :term:`SDK_DEPLOY` and
7771 :term:`TOOLCHAIN_OUTPUTNAME` variables.
7772
Andrew Geisslerf0343792020-11-18 10:42:21 -06007773 :term:`SDK_TARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007774 A list of targets to install from shared state as part of the
7775 standard or extensible SDK installation. The default value is "${PN}"
7776 (i.e. the image from which the SDK is built).
7777
Andrew Geissler09036742021-06-25 14:25:14 -05007778 The :term:`SDK_TARGETS` variable is an internal variable and typically
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007779 would not be changed.
7780
Andrew Geisslerf0343792020-11-18 10:42:21 -06007781 :term:`SDK_TITLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007782 The title to be printed when running the SDK installer. By default,
7783 this title is based on the :term:`DISTRO_NAME` or
7784 :term:`DISTRO` variable and is set in the
7785 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007786 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007787
7788 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
7789
7790 For the default distribution "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05007791 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007792
7793 For information on how to change this default title, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007794 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007795 section in the Yocto Project Application Development and the
7796 Extensible Software Development Kit (eSDK) manual.
7797
Patrick Williams975a06f2022-10-21 14:42:47 -05007798 :term:`SDK_TOOLCHAIN_LANGS`
7799 Specifies programming languages to support in the SDK, as a
7800 space-separated list. Currently supported items are ``rust`` and ``go``.
7801
Andrew Geisslerf0343792020-11-18 10:42:21 -06007802 :term:`SDK_UPDATE_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007803 An optional URL for an update server for the extensible SDK. If set,
7804 the value is used as the default update server when running
7805 ``devtool sdk-update`` within the extensible SDK.
7806
Andrew Geisslerf0343792020-11-18 10:42:21 -06007807 :term:`SDK_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007808 Specifies the name of the SDK vendor.
7809
Andrew Geisslerf0343792020-11-18 10:42:21 -06007810 :term:`SDK_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007811 Specifies the version of the SDK. The Poky distribution configuration file
7812 (``/meta-poky/conf/distro/poky.conf``) sets the default
Andrew Geissler09036742021-06-25 14:25:14 -05007813 :term:`SDK_VERSION` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007814
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007815 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007816
7817 For additional information, see the
7818 :term:`DISTRO_VERSION` and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007819 :term:`METADATA_REVISION` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007820
Patrick Williams8e7b46e2023-05-01 14:19:06 -05007821 :term:`SDK_ZIP_OPTIONS`
7822 Specifies extra options to pass to the ``zip`` command when zipping the SDK
7823 (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is
7824 "-y".
7825
Andrew Geisslerf0343792020-11-18 10:42:21 -06007826 :term:`SDKEXTPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007827 The default installation directory for the Extensible SDK. By
7828 default, this directory is based on the :term:`DISTRO`
7829 variable and is set in the
7830 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007831 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007832
7833 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
7834
7835 For the
Andrew Geissler09036742021-06-25 14:25:14 -05007836 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007837
7838 For information on how to change this default directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007839 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007840 section in the Yocto Project Application Development and the
7841 Extensible Software Development Kit (eSDK) manual.
7842
Andrew Geisslerf0343792020-11-18 10:42:21 -06007843 :term:`SDKIMAGE_FEATURES`
Andrew Geissler09036742021-06-25 14:25:14 -05007844 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to
Andrew Geisslerc926e172021-05-07 16:11:35 -05007845 the SDK generated from an image using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007846
7847 $ bitbake -c populate_sdk imagename
7848
Andrew Geisslerf0343792020-11-18 10:42:21 -06007849 :term:`SDKMACHINE`
Andrew Geissler595f6302022-01-24 19:11:47 +00007850 The machine for which the SDK is built. In other words, the SDK is built
7851 such that it runs on the target you specify with the :term:`SDKMACHINE`
7852 value. The value points to a corresponding ``.conf`` file under
7853 ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``,
7854 ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are
7855 :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007856
Andrew Geissler595f6302022-01-24 19:11:47 +00007857 The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the
7858 architecture of the build machine.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007859
7860 .. note::
7861
Andrew Geissler09036742021-06-25 14:25:14 -05007862 You cannot set the :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007863 variable in your distribution configuration file. If you do, the
Andrew Geissler595f6302022-01-24 19:11:47 +00007864 configuration will not take effect.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007865
Andrew Geisslerf0343792020-11-18 10:42:21 -06007866 :term:`SDKPATH`
Patrick Williamsb58112e2024-03-07 11:16:36 -06007867 Defines the path used to collect the SDK components and build the
7868 installer.
7869
7870 :term:`SDKPATHINSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007871 Defines the path offered to the user for installation of the SDK that
7872 is generated by the OpenEmbedded build system. The path appears as
7873 the default location for installing the SDK when you run the SDK's
7874 installation script. You can override the offered path when you run
7875 the script.
7876
Andrew Geisslerf0343792020-11-18 10:42:21 -06007877 :term:`SDKTARGETSYSROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007878 The full path to the sysroot used for cross-compilation within an SDK
7879 as it will be when installed into the default
Patrick Williamsb58112e2024-03-07 11:16:36 -06007880 :term:`SDKPATHINSTALL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007881
Andrew Geisslerf0343792020-11-18 10:42:21 -06007882 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007883 The section in which packages should be categorized. Package
7884 management utilities can make use of this variable.
7885
Andrew Geisslerf0343792020-11-18 10:42:21 -06007886 :term:`SELECTED_OPTIMIZATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007887 Specifies the optimization flags passed to the C compiler when
7888 building for the target. The flags are passed through the default
7889 value of the :term:`TARGET_CFLAGS` variable.
7890
Andrew Geissler09036742021-06-25 14:25:14 -05007891 The :term:`SELECTED_OPTIMIZATION` variable takes the value of
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007892 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which
7893 case the value of :term:`DEBUG_OPTIMIZATION` is used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007894
Andrew Geisslerf0343792020-11-18 10:42:21 -06007895 :term:`SERIAL_CONSOLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007896 Defines a serial console (TTY) to enable using
Patrick Williams8e7b46e2023-05-01 14:19:06 -05007897 :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the
7898 baud rate followed by the TTY device name separated by a semicolon.
7899 Use spaces to separate multiple devices::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007900
7901 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
7902
Andrew Geissler595f6302022-01-24 19:11:47 +00007903 :term:`SETUPTOOLS_BUILD_ARGS`
Andrew Geissler517393d2023-01-13 08:55:19 -06007904 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7905 class, this variable can be used to specify additional arguments to be
7906 passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task.
Andrew Geissler595f6302022-01-24 19:11:47 +00007907
Andrew Geissler595f6302022-01-24 19:11:47 +00007908 :term:`SETUPTOOLS_SETUP_PATH`
Andrew Geissler517393d2023-01-13 08:55:19 -06007909 When used by recipes that inherit the :ref:`ref-classes-setuptools3`
7910 class, this variable should be used to specify the directory in which
7911 the ``setup.py`` file is located if it is not at the root of the source
7912 tree (as specified by :term:`S`). For example, in a recipe where the
7913 sources are fetched from a Git repository and ``setup.py`` is in a
7914 ``python/pythonmodule`` subdirectory, you would have this::
Andrew Geissler595f6302022-01-24 19:11:47 +00007915
7916 S = "${WORKDIR}/git"
7917 SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule"
7918
Andrew Geisslerf0343792020-11-18 10:42:21 -06007919 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007920 A list of recipe dependencies that should not be used to determine
7921 signatures of tasks from one recipe when they depend on tasks from
Andrew Geisslerc926e172021-05-07 16:11:35 -05007922 another recipe. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007923
7924 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
7925
7926 In the previous example, ``intone`` depends on ``mplayer2``.
7927
7928 You can use the special token ``"*"`` on the left-hand side of the
7929 dependency to match all recipes except the one on the right-hand
Andrew Geisslerc926e172021-05-07 16:11:35 -05007930 side. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007931
7932 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
7933
7934 In the previous example, all recipes except ``quilt-native`` ignore
7935 task signatures from the ``quilt-native`` recipe when determining
7936 their task signatures.
7937
7938 Use of this variable is one mechanism to remove dependencies that
7939 affect task signatures and thus force rebuilds when a recipe changes.
7940
7941 .. note::
7942
7943 If you add an inappropriate dependency for a recipe relationship,
7944 the software might break during runtime if the interface of the
7945 second recipe was changed after the first recipe had been built.
7946
Andrew Geisslerf0343792020-11-18 10:42:21 -06007947 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007948 A list of recipes that are completely stable and will never change.
7949 The ABI for the recipes in the list are presented by output from the
7950 tasks run to build the recipe. Use of this variable is one way to
7951 remove dependencies from one recipe on another that affect task
7952 signatures and thus force rebuilds when the recipe changes.
7953
7954 .. note::
7955
7956 If you add an inappropriate variable to this list, the software
7957 might break at runtime if the interface of the recipe was changed
7958 after the other had been built.
7959
Patrick Williams84603582024-12-14 08:00:57 -05007960 :term:`SIGGEN_LOCKEDSIGS`
7961 The list of locked tasks, with the form::
7962
7963 SIGGEN_LOCKEDSIGS += "<package>:<task>:<signature>"
7964
7965 If ``<signature>`` exists for the specified ``<task>`` and ``<package>``
7966 in the sstate cache, BitBake will use the cached output instead of
7967 rebuilding the ``<task>``. If it does not exist, BitBake will build the
7968 ``<task>`` and the sstate cache will be used next time.
7969
7970 Example::
7971
7972 SIGGEN_LOCKEDSIGS += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
7973
7974 You can obtain the signature of all the tasks for the recipe ``bc`` using::
7975
7976 bitbake -S none bc
7977
7978 Then you can look at files in ``build/tmp/stamps/<arch>/bc`` and look for
7979 files like: ``<PV>.do_compile.sigdata.09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0``.
7980
7981 Alternatively, you can also use :doc:`bblock </dev-manual/bblock>` to
7982 generate this line for you.
7983
7984 :term:`SIGGEN_LOCKEDSIGS_TASKSIG_CHECK`
7985 Specifies the debug level of task signature check. 3 levels are supported:
7986
7987 * ``info``: displays a "Note" message to remind the user that a task is locked
7988 and the current signature matches the locked one.
7989 * ``warn``: displays a "Warning" message if a task is locked and the current
7990 signature does not match the locked one.
7991 * ``error``: same as warn but displays an "Error" message and aborts.
7992
7993 :term:`SIGGEN_LOCKEDSIGS_TYPES`
7994 Allowed overrides for :term:`SIGGEN_LOCKEDSIGS`. This is mainly used
7995 for architecture specific locks. A common value for
7996 :term:`SIGGEN_LOCKEDSIGS_TYPES` is ``${PACKAGE_ARCHS}``::
7997
7998 SIGGEN_LOCKEDSIGS_TYPES += "${PACKAGE_ARCHS}"
7999
8000 SIGGEN_LOCKEDSIGS_core2-64 += "bc:do_compile:09772aa4532512baf96d433484f27234d4b7c11dd9cda0d6f56fa1b7ce6f25f0"
8001 SIGGEN_LOCKEDSIGS_cortexa57 += "bc:do_compile:12178eb6d55ef602a8fe638e49862fd247e07b228f0f08967697b655bfe4bb61"
8002
8003 Here, the ``do_compile`` task from ``bc`` will be locked only for
8004 ``core2-64`` and ``cortexa57`` but not for other architectures such as
8005 ``mips32r2``.
8006
Andrew Geisslerf0343792020-11-18 10:42:21 -06008007 :term:`SITEINFO_BITS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008008 Specifies the number of bits for the target system CPU. The value
8009 should be either "32" or "64".
8010
Andrew Geisslerf0343792020-11-18 10:42:21 -06008011 :term:`SITEINFO_ENDIANNESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008012 Specifies the endian byte order of the target system. The value
8013 should be either "le" for little-endian or "be" for big-endian.
8014
Andrew Geisslerf0343792020-11-18 10:42:21 -06008015 :term:`SKIP_FILEDEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008016 Enables removal of all files from the "Provides" section of an RPM
8017 package. Removal of these files is required for packages containing
8018 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
8019
8020 To enable file removal, set the variable to "1" in your
8021 ``conf/local.conf`` configuration file in your:
Patrick Williams2390b1b2022-11-03 13:47:49 -05008022 :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008023
8024 SKIP_FILEDEPS = "1"
8025
Andrew Geissler9aee5002022-03-30 16:27:02 +00008026 :term:`SKIP_RECIPE`
8027 Used to prevent the OpenEmbedded build system from building a given
8028 recipe. Specify the :term:`PN` value as a variable flag (``varflag``)
8029 and provide a reason, which will be reported when attempting to
8030 build the recipe.
8031
8032 To prevent a recipe from being built, use the :term:`SKIP_RECIPE`
8033 variable in your ``local.conf`` file or distribution configuration.
8034 Here is an example which prevents ``myrecipe`` from being built::
8035
8036 SKIP_RECIPE[myrecipe] = "Not supported by our organization."
8037
Andrew Geisslerf0343792020-11-18 10:42:21 -06008038 :term:`SOC_FAMILY`
Patrick Williams520786c2023-06-25 16:20:36 -05008039 A colon-separated list grouping together machines based upon the same
8040 family of SoC (System On Chip). You typically set this variable in a
8041 common ``.inc`` file that you include in the configuration files of all
8042 the machines.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008043
8044 .. note::
8045
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008046 You must include ``conf/machine/include/soc-family.inc`` for this
8047 variable to appear in :term:`MACHINEOVERRIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008048
Andrew Geisslerf0343792020-11-18 10:42:21 -06008049 :term:`SOLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008050 Defines the suffix for shared libraries used on the target platform.
8051 By default, this suffix is ".so.*" for all Linux-based systems and is
8052 defined in the ``meta/conf/bitbake.conf`` configuration file.
8053
8054 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008055 ``FILES:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008056
Andrew Geisslerf0343792020-11-18 10:42:21 -06008057 :term:`SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008058 Defines the suffix for the development symbolic link (symlink) for
8059 shared libraries on the target platform. By default, this suffix is
8060 ".so" for Linux-based systems and is defined in the
8061 ``meta/conf/bitbake.conf`` configuration file.
8062
8063 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008064 ``FILES:${PN}-dev``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008065
Andrew Geisslereff27472021-10-29 15:35:00 -05008066 :term:`SOURCE_DATE_EPOCH`
8067 This defines a date expressed in number of seconds since
8068 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by
8069 multiple build systems to force a timestamp in built binaries.
8070 Many upstream projects already support this variable.
8071
8072 You will find more details in the `official specifications
8073 <https://reproducible-builds.org/specs/source-date-epoch/>`__.
8074
8075 A value for each recipe is computed from the sources by
8076 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`.
8077
8078 If a recipe wishes to override the default behavior, it should set its
8079 own :term:`SOURCE_DATE_EPOCH` value::
8080
8081 SOURCE_DATE_EPOCH = "1613559011"
8082
Andrew Geisslerf0343792020-11-18 10:42:21 -06008083 :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008084 When you are fetching files to create a mirror of sources (i.e.
Andrew Geissler09036742021-06-25 14:25:14 -05008085 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008086 your ``local.conf`` configuration file ensures the source for all
8087 recipes are fetched regardless of whether or not a recipe is
8088 compatible with the configuration. A recipe is considered
8089 incompatible with the currently configured machine when either or
8090 both the :term:`COMPATIBLE_MACHINE`
8091 variable and :term:`COMPATIBLE_HOST` variables
8092 specify compatibility with a machine other than that of the current
8093 machine or host.
8094
8095 .. note::
8096
Andrew Geissler09036742021-06-25 14:25:14 -05008097 Do not set the :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008098 variable unless you are creating a source mirror. In other words,
8099 do not set the variable during a normal build.
8100
Andrew Geisslerf0343792020-11-18 10:42:21 -06008101 :term:`SOURCE_MIRROR_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008102 Defines your own :term:`PREMIRRORS` from which to
8103 first fetch source before attempting to fetch from the upstream
8104 specified in :term:`SRC_URI`.
8105
8106 To use this variable, you must globally inherit the
Andrew Geissler517393d2023-01-13 08:55:19 -06008107 :ref:`ref-classes-own-mirrors` class and then provide
Andrew Geisslerc926e172021-05-07 16:11:35 -05008108 the URL to your mirrors. Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008109
8110 INHERIT += "own-mirrors"
8111 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
8112
8113 .. note::
8114
Andrew Geissler09036742021-06-25 14:25:14 -05008115 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008116
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008117 .. note::
8118
8119 If the mirror is protected behind a username and password, the
8120 :term:`build host` needs to be configured so the :term:`build system
8121 <OpenEmbedded Build System>` is able to fetch from the mirror.
8122
8123 The recommended way to do that is by setting the following parameters
8124 in ``$HOME/.netrc`` (``$HOME`` being the :term:`build host` home
8125 directory)::
8126
8127 machine example.com
8128 login <user>
8129 password <password>
8130
8131 This file requires permissions set to ``400`` or ``600`` to prevent
8132 other users from reading the file::
8133
8134 chmod 600 "$HOME/.netrc"
8135
8136 Another method to configure the username and password is from the URL
8137 in :term:`SOURCE_MIRROR_URL` directly, with the ``user`` and ``pswd``
8138 parameters::
8139
8140 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror;user=<user>;pswd=<password>"
8141
Patrick Williams7784c422022-11-17 07:29:11 -06008142 :term:`SPDX_ARCHIVE_PACKAGED`
8143 This option allows to add to :term:`SPDX` output compressed archives
8144 of the files in the generated target packages.
8145
8146 Such archives are available in
8147 ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst``
8148 under the :term:`Build Directory`.
8149
8150 Enable this option as follows::
8151
8152 SPDX_ARCHIVE_PACKAGED = "1"
8153
8154 According to our tests on release 4.1 "langdale", building
8155 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this
8156 option multiplied the size of the ``tmp/deploy/spdx`` directory by a
8157 factor of 13 (+1.6 GiB for this image), compared to just using the
Andrew Geissler517393d2023-01-13 08:55:19 -06008158 :ref:`ref-classes-create-spdx` class with no option.
Patrick Williams7784c422022-11-17 07:29:11 -06008159
8160 Note that this option doesn't increase the size of :term:`SPDX`
8161 files in ``tmp/deploy/images/MACHINE``.
8162
8163 :term:`SPDX_ARCHIVE_SOURCES`
8164 This option allows to add to :term:`SPDX` output compressed archives
8165 of the sources for packages installed on the target. It currently
8166 only works when :term:`SPDX_INCLUDE_SOURCES` is set.
8167
8168 This is one way of fulfilling "source code access" license
8169 requirements.
8170
8171 Such source archives are available in
8172 ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst``
8173 under the :term:`Build Directory`.
8174
8175 Enable this option as follows::
8176
8177 SPDX_INCLUDE_SOURCES = "1"
8178 SPDX_ARCHIVE_SOURCES = "1"
8179
8180 According to our tests on release 4.1 "langdale", building
8181 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
8182 these options multiplied the size of the ``tmp/deploy/spdx``
8183 directory by a factor of 11 (+1.4 GiB for this image),
Andrew Geissler517393d2023-01-13 08:55:19 -06008184 compared to just using the :ref:`ref-classes-create-spdx`
Patrick Williams7784c422022-11-17 07:29:11 -06008185 class with no option.
8186
8187 Note that using this option only marginally increases the size
8188 of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/``
8189 (+ 0.07\% with the tested image), compared to just enabling
8190 :term:`SPDX_INCLUDE_SOURCES`.
8191
Patrick Williams8e7b46e2023-05-01 14:19:06 -05008192 :term:`SPDX_CUSTOM_ANNOTATION_VARS`
8193 This option allows to associate `SPDX annotations
8194 <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe,
8195 using the values of variables in the recipe::
Patrick Williams44b3caf2024-04-12 16:51:14 -05008196
Patrick Williams8e7b46e2023-05-01 14:19:06 -05008197 ANNOTATION1 = "First annotation for recipe"
8198 ANNOTATION2 = "Second annotation for recipe"
8199 SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2"
8200
8201 This will add a new block to the recipe ``.sdpx.json`` output::
8202
8203 "annotations": [
8204 {
8205 "annotationDate": "2023-04-18T08:32:12Z",
8206 "annotationType": "OTHER",
8207 "annotator": "Tool: oe-spdx-creator - 1.0",
8208 "comment": "ANNOTATION1=First annotation for recipe"
8209 },
8210 {
8211 "annotationDate": "2023-04-18T08:32:12Z",
8212 "annotationType": "OTHER",
8213 "annotator": "Tool: oe-spdx-creator - 1.0",
8214 "comment": "ANNOTATION2=Second annotation for recipe"
8215 }
8216 ],
8217
Patrick Williams7784c422022-11-17 07:29:11 -06008218 :term:`SPDX_INCLUDE_SOURCES`
8219 This option allows to add a description of the source files used to build
8220 the host tools and the target packages, to the ``spdx.json`` files in
8221 ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`.
8222 As a consequence, the ``spdx.json`` files under the ``by-namespace`` and
8223 ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also
8224 modified to include references to such source file descriptions.
8225
8226 Enable this option as follows::
8227
8228 SPDX_INCLUDE_SOURCES = "1"
8229
8230 According to our tests on release 4.1 "langdale", building
8231 ``core-image-minimal`` for the ``qemux86-64`` machine, enabling
8232 this option multiplied the total size of the ``tmp/deploy/spdx``
8233 directory by a factor of 3 (+291 MiB for this image),
8234 and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in
8235 ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this
Andrew Geissler517393d2023-01-13 08:55:19 -06008236 image), compared to just using the :ref:`ref-classes-create-spdx` class
8237 with no option.
Patrick Williams7784c422022-11-17 07:29:11 -06008238
Patrick Williams03514f12024-04-05 07:04:11 -05008239 :term:`SPDX_NAMESPACE_PREFIX`
8240 This option could be used in order to change the prefix of ``spdxDocument``
8241 and the prefix of ``documentNamespace``. It is set by default to
8242 ``http://spdx.org/spdxdoc``.
8243
Patrick Williams7784c422022-11-17 07:29:11 -06008244 :term:`SPDX_PRETTY`
8245 This option makes the SPDX output more human-readable, using
8246 identation and newlines, instead of the default output in a
8247 single line::
8248
8249 SPDX_PRETTY = "1"
8250
8251 The generated SPDX files are approximately 20% bigger, but
8252 this option is recommended if you want to inspect the SPDX
8253 output files with a text editor.
8254
Andrew Geisslerf0343792020-11-18 10:42:21 -06008255 :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008256 Maps commonly used license names to their SPDX counterparts found in
Andrew Geissler09036742021-06-25 14:25:14 -05008257 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008258 mappings, see the ``meta/conf/licenses.conf`` file.
8259
8260 For additional information, see the :term:`LICENSE`
8261 variable.
8262
Andrew Geisslerf0343792020-11-18 10:42:21 -06008263 :term:`SPECIAL_PKGSUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008264 A list of prefixes for :term:`PN` used by the OpenEmbedded
8265 build system to create variants of recipes or packages. The list
8266 specifies the prefixes to strip off during certain circumstances such
8267 as the generation of the :term:`BPN` variable.
8268
Andrew Geisslerf0343792020-11-18 10:42:21 -06008269 :term:`SPL_BINARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008270 The file type for the Secondary Program Loader (SPL). Some devices
8271 use an SPL from which to boot (e.g. the BeagleBone development
8272 board). For such cases, you can declare the file type of the SPL
8273 binary in the ``u-boot.inc`` include file, which is used in the
8274 U-Boot recipe.
8275
8276 The SPL file type is set to "null" by default in the ``u-boot.inc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05008277 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008278
8279 # Some versions of u-boot build an SPL (Second Program Loader) image that
8280 # should be packaged along with the u-boot binary as well as placed in the
8281 # deploy directory. For those versions they can set the following variables
8282 # to allow packaging the SPL.
8283 SPL_BINARY ?= ""
8284 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
8285 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
8286 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
8287
Andrew Geissler09036742021-06-25 14:25:14 -05008288 The :term:`SPL_BINARY` variable helps form
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008289 various ``SPL_*`` variables used by the OpenEmbedded build system.
8290
8291 See the BeagleBone machine configuration example in the
Andrew Geissler517393d2023-01-13 08:55:19 -06008292 ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008293 section in the Yocto Project Board Support Package Developer's Guide
8294 for additional information.
8295
Patrick Williamsb542dec2023-06-09 01:26:37 -05008296 :term:`SPL_MKIMAGE_DTCOPTS`
8297 Options for the device tree compiler passed to ``mkimage -D`` feature
8298 while creating a FIT image with the :ref:`ref-classes-uboot-sign`
8299 class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the
8300 :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option
8301 to ``mkimage``.
8302
8303 The default value is set to "" by the :ref:`ref-classes-uboot-config`
8304 class.
8305
8306 :term:`SPL_SIGN_ENABLE`
8307 Enable signing of the U-Boot FIT image. The default value is "0".
8308 This variable is used by the :ref:`ref-classes-uboot-sign` class.
8309
8310 :term:`SPL_SIGN_KEYDIR`
8311 Location of the directory containing the RSA key and certificate used for
8312 signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign`
8313 class.
8314
8315 :term:`SPL_SIGN_KEYNAME`
8316 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
8317 for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR`
8318 directory. If we have for example a ``dev.key`` key and a ``dev.crt``
Patrick Williams44b3caf2024-04-12 16:51:14 -05008319 certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will
Patrick Williamsb542dec2023-06-09 01:26:37 -05008320 have to set :term:`SPL_SIGN_KEYNAME` to ``dev``.
8321
8322 :term:`SPLASH`
8323 This variable, used by the :ref:`ref-classes-image` class, allows
8324 to choose splashscreen applications. Set it to the names of packages
8325 for such applications to use. This variable is set by default to
8326 ``psplash``.
8327
8328 :term:`SPLASH_IMAGES`
8329 This variable, used by the ``psplash`` recipe, allows to customize
8330 the default splashscreen image.
8331
8332 Specified images in PNG format are converted to ``.h`` files by the recipe,
8333 and are included in the ``psplash`` binary, so you won't find them in
8334 the root filesystem.
8335
8336 To make such a change, it is recommended to customize the
8337 ``psplash`` recipe in a custom layer. Here is an example structure for
8338 an ``ACME`` board::
8339
8340 meta-acme/recipes-core/psplash
8341 ├── files
8342 │   └── logo-acme.png
8343 └── psplash_%.bbappend
8344
8345 And here are the contents of the ``psplash_%.bbappend`` file in
8346 this example::
8347
8348 SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default"
8349 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
8350
8351 You could even add specific configuration options for ``psplash``,
8352 for example::
8353
8354 EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen"
8355
Patrick Williams44b3caf2024-04-12 16:51:14 -05008356 For information on append files, see the
Patrick Williamsb542dec2023-06-09 01:26:37 -05008357 ":ref:`dev-manual/layers:appending other layers metadata with your layer`"
8358 section.
8359
Andrew Geissler517393d2023-01-13 08:55:19 -06008360 :term:`SRCREV_FORMAT`
8361 See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual.
8362
Andrew Geisslerf0343792020-11-18 10:42:21 -06008363 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008364
Andrew Geissler595f6302022-01-24 19:11:47 +00008365 See the BitBake manual for the initial description for this variable:
8366 :term:`bitbake:SRC_URI`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008367
Andrew Geissler595f6302022-01-24 19:11:47 +00008368 The following features are added by OpenEmbedded and the Yocto Project.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008369
Andrew Geissler595f6302022-01-24 19:11:47 +00008370 There are standard and recipe-specific options. Here are standard ones:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008371
Andrew Geissler615f2f12022-07-15 14:00:58 -05008372 - ``apply`` --- whether to apply the patch or not. The default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008373 action is to apply the patch.
8374
Andrew Geissler615f2f12022-07-15 14:00:58 -05008375 - ``striplevel`` --- which striplevel to use when applying the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008376 patch. The default level is 1.
8377
Andrew Geissler615f2f12022-07-15 14:00:58 -05008378 - ``patchdir`` --- specifies the directory in which the patch should
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008379 be applied. The default is ``${``\ :term:`S`\ ``}``.
8380
8381 Here are options specific to recipes building code from a revision
8382 control system:
8383
Andrew Geissler615f2f12022-07-15 14:00:58 -05008384 - ``mindate`` --- apply the patch only if
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008385 :term:`SRCDATE` is equal to or greater than
8386 ``mindate``.
8387
Andrew Geissler615f2f12022-07-15 14:00:58 -05008388 - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008389 than ``maxdate``.
8390
Andrew Geissler615f2f12022-07-15 14:00:58 -05008391 - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008392 greater than ``minrev``.
8393
Andrew Geissler615f2f12022-07-15 14:00:58 -05008394 - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008395 than ``maxrev``.
8396
Andrew Geissler615f2f12022-07-15 14:00:58 -05008397 - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008398 ``rev``.
8399
Andrew Geissler615f2f12022-07-15 14:00:58 -05008400 - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008401 ``rev``.
8402
Andrew Geissler595f6302022-01-24 19:11:47 +00008403 .. note::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008404
Andrew Geissler595f6302022-01-24 19:11:47 +00008405 If you want the build system to pick up files specified through
8406 a :term:`SRC_URI` statement from your append file, you need to be
8407 sure to extend the :term:`FILESPATH` variable by also using the
8408 :term:`FILESEXTRAPATHS` variable from within your append file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008409
Andrew Geisslerf0343792020-11-18 10:42:21 -06008410 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008411 By default, the OpenEmbedded build system automatically detects
Andrew Geissler5f350902021-07-23 13:09:54 -04008412 whether :term:`SRC_URI` contains files that are machine-specific. If so,
Andrew Geissler09036742021-06-25 14:25:14 -05008413 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008414 variable to "0" disables this behavior.
8415
Andrew Geisslerf0343792020-11-18 10:42:21 -06008416 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008417 The date of the source code used to build the package. This variable
8418 applies only if the source was fetched from a Source Code Manager
8419 (SCM).
8420
Andrew Geisslerf0343792020-11-18 10:42:21 -06008421 :term:`SRCPV`
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008422 The variable :term:`SRCPV` is deprecated. It was previously used to
8423 include source control information in :term:`PV` for :term:`bitbake` to
8424 work correctly but this is no longer a requirement. Source control
8425 information will be automatically included by :term:`bitbake` in the
8426 variable :term:`PKGV` during packaging if the ``+`` sign is present in
8427 :term:`PV`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008428
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008429 .. note::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008430
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008431 The :term:`SRCPV` variable used to be defined in the
8432 ``meta/conf/bitbake.conf`` configuration file in the :term:`Source
8433 Directory` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008434
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008435 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008436
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008437 The ``get_srcrev`` function can still be used to include source control
8438 information in variables manually.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008439
Andrew Geisslerf0343792020-11-18 10:42:21 -06008440 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008441 The revision of the source code used to build the package. This
8442 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
8443 that if you want to build a fixed revision and you want to avoid
8444 performing a query on the remote repository every time BitBake parses
Andrew Geissler09036742021-06-25 14:25:14 -05008445 your recipe, you should specify a :term:`SRCREV` that is a full revision
Patrick Williams520786c2023-06-25 16:20:36 -05008446 identifier (e.g. the full SHA hash in git) and not just a tag.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008447
8448 .. note::
8449
8450 For information on limitations when inheriting the latest revision
Andrew Geissler09036742021-06-25 14:25:14 -05008451 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008452 description and the
Andrew Geissler517393d2023-01-13 08:55:19 -06008453 ":ref:`dev-manual/packages:automatically incrementing a package version number`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008454 section, which is in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008455
Andrew Geissler09036742021-06-25 14:25:14 -05008456 :term:`SRCTREECOVEREDTASKS`
8457 A list of tasks that are typically not relevant (and therefore skipped)
Andrew Geissler517393d2023-01-13 08:55:19 -06008458 when building using the :ref:`ref-classes-externalsrc`
Andrew Geissler09036742021-06-25 14:25:14 -05008459 class. The default value as set in that class file is the set of tasks
8460 that are rarely needed when using external source::
8461
8462 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
8463
8464 The notable exception is when processing external kernel source as
Andrew Geissler517393d2023-01-13 08:55:19 -06008465 defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for
8466 aesthetics)::
Andrew Geissler09036742021-06-25 14:25:14 -05008467
8468 SRCTREECOVEREDTASKS += "\
8469 do_validate_branches \
8470 do_kernel_configcheck \
8471 do_kernel_checkout \
8472 do_fetch \
8473 do_unpack \
8474 do_patch \
8475 "
8476
8477 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD`
8478 variables for more information.
8479
Andrew Geisslerf0343792020-11-18 10:42:21 -06008480 :term:`SSTATE_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008481 The directory for the shared state cache.
8482
Andrew Geissler615f2f12022-07-15 14:00:58 -05008483 :term:`SSTATE_EXCLUDEDEPS_SYSROOT`
8484 This variable allows to specify indirect dependencies to exclude
8485 from sysroots, for example to avoid the situations when a dependency on
8486 any ``-native`` recipe will pull in all dependencies of that recipe
8487 in the recipe sysroot. This behaviour might not always be wanted,
8488 for example when that ``-native`` recipe depends on build tools
8489 that are not relevant for the current recipe.
8490
8491 This way, irrelevant dependencies are ignored, which could have
8492 prevented the reuse of prebuilt artifacts stored in the Shared
8493 State Cache.
8494
Andrew Geissler517393d2023-01-13 08:55:19 -06008495 :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular
Andrew Geissler615f2f12022-07-15 14:00:58 -05008496 expressions of recipe and dependency to ignore. An example
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06008497 is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`::
Andrew Geissler615f2f12022-07-15 14:00:58 -05008498
8499 # Nothing needs to depend on libc-initial
8500 # base-passwd/shadow-sysroot don't need their dependencies
8501 SSTATE_EXCLUDEDEPS_SYSROOT += "\
8502 .*->.*-initial.* \
8503 .*(base-passwd|shadow-sysroot)->.* \
8504 "
8505
8506 The ``->`` substring represents the dependency between
8507 the two regular expressions.
8508
Andrew Geisslerf0343792020-11-18 10:42:21 -06008509 :term:`SSTATE_MIRROR_ALLOW_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008510 If set to "1", allows fetches from mirrors that are specified in
8511 :term:`SSTATE_MIRRORS` to work even when
Andrew Geissler09036742021-06-25 14:25:14 -05008512 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to
8513 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if
8514 you have set :term:`SSTATE_MIRRORS` to point to an internal server for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008515 your shared state cache, but you want to disable any other fetching
8516 from the network.
8517
Andrew Geisslerf0343792020-11-18 10:42:21 -06008518 :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008519 Configures the OpenEmbedded build system to search other mirror
8520 locations for prebuilt cache data objects before building out the
8521 data. This variable works like fetcher :term:`MIRRORS`
8522 and :term:`PREMIRRORS` and points to the cache
8523 locations to check for the shared state (sstate) objects.
8524
8525 You can specify a filesystem directory or a remote URL such as HTTP
8526 or FTP. The locations you specify need to contain the shared state
8527 cache (sstate-cache) results from previous builds. The sstate-cache
8528 you point to can also be from builds on other machines.
8529
8530 When pointing to sstate build artifacts on another machine that uses
8531 a different GCC version for native builds, you must configure
Andrew Geissler09036742021-06-25 14:25:14 -05008532 :term:`SSTATE_MIRRORS` with a regular expression that maps local search
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008533 paths to server paths. The paths need to take into account
Andrew Geissler517393d2023-01-13 08:55:19 -06008534 :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class.
8535 For example, the following maps the local search path ``universal-4.9``
8536 to the server-provided path server_url_sstate_path::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008537
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00008538 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008539
8540 If a mirror uses the same structure as
8541 :term:`SSTATE_DIR`, you need to add "PATH" at the
8542 end as shown in the examples below. The build system substitutes the
Andrew Geissler517393d2023-01-13 08:55:19 -06008543 correct path within the directory structure::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008544
8545 SSTATE_MIRRORS ?= "\
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00008546 file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008547 file://.* file:///some-local-dir/sstate/PATH"
8548
Patrick Williams96e4b4e2025-02-03 15:49:15 -05008549 .. note::
8550
8551 If the mirror is protected behind a username and password, the
8552 :term:`build host` needs to be configured so the :term:`build system
8553 <OpenEmbedded Build System>` is able to download the sstate cache using
8554 authentication.
8555
8556 The recommended way to do that is by setting the following parameters
8557 in ``$HOME/.netrc`` (``$HOME`` being the :term:`build host` home
8558 directory)::
8559
8560 machine someserver.tld
8561 login <user>
8562 password <password>
8563
8564 This file requires permissions set to ``400`` or ``600`` to prevent
8565 other users from reading the file::
8566
8567 chmod 600 "$HOME/.netrc"
8568
8569 Another method to configure the username and password is from the
8570 URL in :term:`SSTATE_MIRRORS` directly, with the ``user`` and ``pswd``
8571 parameters::
8572
8573 SSTATE_MIRRORS ?= "\
8574 file://.* https://someserver.tld/share/sstate/PATH;user=<user>;pswd=<password>;downloadfilename=PATH \
8575 "
8576
Patrick Williamsac13d5f2023-11-24 18:59:46 -06008577 The Yocto Project actually shares the cache data objects built by its
8578 autobuilder::
8579
8580 SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH"
8581
8582 As such binary artifacts are built for the generic QEMU machines
8583 supported by the various Poky releases, they are less likely to be
8584 reusable in real projects building binaries optimized for a specific
8585 CPU family.
8586
Andrew Geisslerf0343792020-11-18 10:42:21 -06008587 :term:`SSTATE_SCAN_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008588 Controls the list of files the OpenEmbedded build system scans for
8589 hardcoded installation paths. The variable uses a space-separated
8590 list of filenames (not paths) with standard wildcard characters
8591 allowed.
8592
8593 During a build, the OpenEmbedded build system creates a shared state
8594 (sstate) object during the first stage of preparing the sysroots.
8595 That object is scanned for hardcoded paths for original installation
8596 locations. The list of files that are scanned for paths is controlled
Andrew Geissler09036742021-06-25 14:25:14 -05008597 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files
8598 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008599 than the variable being comprehensively set. The
Andrew Geissler517393d2023-01-13 08:55:19 -06008600 :ref:`ref-classes-sstate` class specifies the default list of files.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008601
Andrew Geissler517393d2023-01-13 08:55:19 -06008602 For details on the process, see the :ref:`ref-classes-staging` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008603
Andrew Geisslerf0343792020-11-18 10:42:21 -06008604 :term:`STAGING_BASE_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008605 Specifies the path to the ``/lib`` subdirectory of the sysroot
8606 directory for the build host.
8607
Andrew Geisslerf0343792020-11-18 10:42:21 -06008608 :term:`STAGING_BASELIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008609 Specifies the path to the ``/lib`` subdirectory of the sysroot
8610 directory for the target for which the current recipe is being built
8611 (:term:`STAGING_DIR_HOST`).
8612
Andrew Geisslerf0343792020-11-18 10:42:21 -06008613 :term:`STAGING_BINDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008614 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
8615 directory for the target for which the current recipe is being built
8616 (:term:`STAGING_DIR_HOST`).
8617
Andrew Geisslerf0343792020-11-18 10:42:21 -06008618 :term:`STAGING_BINDIR_CROSS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008619 Specifies the path to the directory containing binary configuration
8620 scripts. These scripts provide configuration information for other
8621 software that wants to make use of libraries or include files
8622 provided by the software associated with the script.
8623
8624 .. note::
8625
8626 This style of build configuration has been largely replaced by
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008627 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the
8628 library to which you are linking, it is recommended you use
8629 ``pkg-config`` instead of a provided configuration script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008630
Andrew Geisslerf0343792020-11-18 10:42:21 -06008631 :term:`STAGING_BINDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008632 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
8633 directory for the build host.
8634
Andrew Geisslerf0343792020-11-18 10:42:21 -06008635 :term:`STAGING_DATADIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008636 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
8637 directory for the target for which the current recipe is being built
8638 (:term:`STAGING_DIR_HOST`).
8639
Andrew Geisslerf0343792020-11-18 10:42:21 -06008640 :term:`STAGING_DATADIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008641 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
8642 directory for the build host.
8643
Andrew Geisslerf0343792020-11-18 10:42:21 -06008644 :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008645 Helps construct the ``recipe-sysroots`` directory, which is used
8646 during packaging.
8647
8648 For information on how staging for recipe-specific sysroots occurs,
8649 see the :ref:`ref-tasks-populate_sysroot`
Patrick Williams43a6b7c2025-02-13 15:13:32 -05008650 task, the ":ref:`dev-manual/devtool:sharing files between recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008651 section in the Yocto Project Development Tasks Manual, the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008652 ":ref:`overview-manual/concepts:configuration, compilation, and staging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008653 section in the Yocto Project Overview and Concepts Manual, and the
8654 :term:`SYSROOT_DIRS` variable.
8655
8656 .. note::
8657
Andrew Geissler09036742021-06-25 14:25:14 -05008658 Recipes should never write files directly under the :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008659 directory because the OpenEmbedded build system manages the
8660 directory automatically. Instead, files should be installed to
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008661 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008662 task and then the OpenEmbedded build system will stage a subset of
8663 those files into the sysroot.
8664
Andrew Geisslerf0343792020-11-18 10:42:21 -06008665 :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008666 Specifies the path to the sysroot directory for the system on which
8667 the component is built to run (the system that hosts the component).
8668 For most recipes, this sysroot is the one in which that recipe's
8669 :ref:`ref-tasks-populate_sysroot` task copies
8670 files. Exceptions include ``-native`` recipes, where the
Patrick Williams2194f502022-10-16 14:26:09 -05008671 :ref:`ref-tasks-populate_sysroot` task instead uses
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008672 :term:`STAGING_DIR_NATIVE`. Depending on
Andrew Geissler09036742021-06-25 14:25:14 -05008673 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008674 have the following values:
8675
8676 - For recipes building for the target machine, the value is
8677 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
8678
8679 - For native recipes building for the build host, the value is empty
8680 given the assumption that when building for the build host, the
8681 build host's own directories should be used.
8682
8683 .. note::
8684
8685 ``-native`` recipes are not installed into host paths like such
8686 as ``/usr``. Rather, these recipes are installed into
Andrew Geissler5f350902021-07-23 13:09:54 -04008687 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008688 standard build environment variables such as
8689 :term:`CPPFLAGS` and
8690 :term:`CFLAGS` are set up so that both host paths
Andrew Geissler09036742021-06-25 14:25:14 -05008691 and :term:`STAGING_DIR_NATIVE` are searched for libraries and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008692 headers using, for example, GCC's ``-isystem`` option.
8693
8694 Thus, the emphasis is that the ``STAGING_DIR*`` variables
8695 should be viewed as input variables by tasks such as
8696 :ref:`ref-tasks-configure`,
8697 :ref:`ref-tasks-compile`, and
8698 :ref:`ref-tasks-install`. Having the real system
Andrew Geissler09036742021-06-25 14:25:14 -05008699 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008700 for ``-native`` recipes, as they make use of host headers and
8701 libraries.
8702
Patrick Williamsac13d5f2023-11-24 18:59:46 -06008703 Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`.
8704
Andrew Geisslerf0343792020-11-18 10:42:21 -06008705 :term:`STAGING_DIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008706 Specifies the path to the sysroot directory used when building
8707 components that run on the build host itself.
8708
Patrick Williamsac13d5f2023-11-24 18:59:46 -06008709 The default value is ``"${RECIPE_SYSROOT_NATIVE}"``,
8710 check :term:`RECIPE_SYSROOT_NATIVE`.
8711
Andrew Geisslerf0343792020-11-18 10:42:21 -06008712 :term:`STAGING_DIR_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008713 Specifies the path to the sysroot used for the system for which the
8714 component generates code. For components that do not generate code,
Andrew Geissler09036742021-06-25 14:25:14 -05008715 which is the majority, :term:`STAGING_DIR_TARGET` is set to match
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008716 :term:`STAGING_DIR_HOST`.
8717
Andrew Geissler517393d2023-01-13 08:55:19 -06008718 Some recipes build binaries that can run on the target system but those
8719 binaries in turn generate code for another different system (e.g.
8720 :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU,
8721 the primary system is referred to as the "HOST" and the secondary, or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008722 different, system is referred to as the "TARGET". Thus, the binaries
8723 run on the "HOST" system and generate binaries for the "TARGET"
Andrew Geissler09036742021-06-25 14:25:14 -05008724 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used
8725 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008726 sysroot used for the "TARGET" system.
8727
Andrew Geisslerf0343792020-11-18 10:42:21 -06008728 :term:`STAGING_ETCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008729 Specifies the path to the ``/etc`` subdirectory of the sysroot
8730 directory for the build host.
8731
Andrew Geisslerf0343792020-11-18 10:42:21 -06008732 :term:`STAGING_EXECPREFIXDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008733 Specifies the path to the ``/usr`` subdirectory of the sysroot
8734 directory for the target for which the current recipe is being built
8735 (:term:`STAGING_DIR_HOST`).
8736
Andrew Geisslerf0343792020-11-18 10:42:21 -06008737 :term:`STAGING_INCDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008738 Specifies the path to the ``/usr/include`` subdirectory of the
8739 sysroot directory for the target for which the current recipe being
8740 built (:term:`STAGING_DIR_HOST`).
8741
Andrew Geisslerf0343792020-11-18 10:42:21 -06008742 :term:`STAGING_INCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008743 Specifies the path to the ``/usr/include`` subdirectory of the
8744 sysroot directory for the build host.
8745
Andrew Geisslerf0343792020-11-18 10:42:21 -06008746 :term:`STAGING_KERNEL_BUILDDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008747 Points to the directory containing the kernel build artifacts.
8748 Recipes building software that needs to access kernel build artifacts
8749 (e.g. ``systemtap-uprobes``) can look in the directory specified with
Andrew Geissler09036742021-06-25 14:25:14 -05008750 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008751 after the kernel has been built.
8752
Andrew Geisslerf0343792020-11-18 10:42:21 -06008753 :term:`STAGING_KERNEL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008754 The directory with kernel headers that are required to build
8755 out-of-tree modules.
8756
Andrew Geisslerf0343792020-11-18 10:42:21 -06008757 :term:`STAGING_LIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008758 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
8759 directory for the target for which the current recipe is being built
8760 (:term:`STAGING_DIR_HOST`).
8761
Andrew Geisslerf0343792020-11-18 10:42:21 -06008762 :term:`STAGING_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008763 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
8764 directory for the build host.
8765
Andrew Geisslerf0343792020-11-18 10:42:21 -06008766 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008767 Specifies the base path used to create recipe stamp files. The path
8768 to an actual stamp file is constructed by evaluating this string and
8769 then appending additional information. Currently, the default
Andrew Geissler09036742021-06-25 14:25:14 -05008770 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05008771 file is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008772
8773 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
8774
8775 For information on how BitBake uses stamp files to determine if a
8776 task should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008777 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008778 section in the Yocto Project Overview and Concepts Manual.
8779
8780 See :term:`STAMPS_DIR`,
8781 :term:`MULTIMACH_TARGET_SYS`,
8782 :term:`PN`, :term:`EXTENDPE`,
8783 :term:`PV`, and :term:`PR` for related variable
8784 information.
8785
Andrew Geissler517393d2023-01-13 08:55:19 -06008786 :term:`STAMPCLEAN`
8787 See :term:`bitbake:STAMPCLEAN` in the BitBake manual.
8788
Andrew Geisslerf0343792020-11-18 10:42:21 -06008789 :term:`STAMPS_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008790 Specifies the base directory in which the OpenEmbedded build system
8791 places stamps. The default directory is ``${TMPDIR}/stamps``.
8792
Andrew Geisslerf0343792020-11-18 10:42:21 -06008793 :term:`STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008794 The minimal command and arguments to run ``strip``, which is used to
8795 strip symbols.
8796
Andrew Geisslerf0343792020-11-18 10:42:21 -06008797 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008798 The short (72 characters or less) summary of the binary package for
8799 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05008800 :term:`SUMMARY` is used to define the
8801 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008802 not set in the recipe.
8803
Andrew Geisslerf0343792020-11-18 10:42:21 -06008804 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008805 The directory in which files checked out of a Subversion system are
8806 stored.
8807
Andrew Geisslerf0343792020-11-18 10:42:21 -06008808 :term:`SYSLINUX_DEFAULT_CONSOLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008809 Specifies the kernel boot default console. If you want to use a
8810 console other than the default, set this variable in your recipe as
Andrew Geisslerc926e172021-05-07 16:11:35 -05008811 follows where "X" is the console number you want to use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008812
8813 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
8814
Andrew Geissler517393d2023-01-13 08:55:19 -06008815 The :ref:`ref-classes-syslinux` class initially sets
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008816 this variable to null but then checks for a value later.
8817
Andrew Geisslerf0343792020-11-18 10:42:21 -06008818 :term:`SYSLINUX_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008819 Lists additional options to add to the syslinux file. You need to set
8820 this variable in your recipe. If you want to list multiple options,
8821 separate the options with a semicolon character (``;``).
8822
Andrew Geissler517393d2023-01-13 08:55:19 -06008823 The :ref:`ref-classes-syslinux` class uses this variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008824 to create a set of options.
8825
Andrew Geisslerf0343792020-11-18 10:42:21 -06008826 :term:`SYSLINUX_SERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008827 Specifies the alternate serial port or turns it off. To turn off
8828 serial, set this variable to an empty string in your recipe. The
8829 variable's default value is set in the
Andrew Geissler517393d2023-01-13 08:55:19 -06008830 :ref:`ref-classes-syslinux` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008831
8832 SYSLINUX_SERIAL ?= "0 115200"
8833
8834 The class checks for and uses the variable as needed.
8835
Andrew Geisslerf0343792020-11-18 10:42:21 -06008836 :term:`SYSLINUX_SERIAL_TTY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008837 Specifies the alternate console=tty... kernel boot argument. The
Andrew Geissler517393d2023-01-13 08:55:19 -06008838 variable's default value is set in the :ref:`ref-classes-syslinux`
8839 class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008840
8841 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
8842
8843 The class checks for and uses the variable as needed.
8844
Andrew Geisslerf0343792020-11-18 10:42:21 -06008845 :term:`SYSLINUX_SPLASH`
8846 An ``.LSS`` file used as the background for the VGA boot menu when
8847 you use the boot menu. You need to set this variable in your recipe.
8848
Andrew Geissler517393d2023-01-13 08:55:19 -06008849 The :ref:`ref-classes-syslinux` class checks for this
Andrew Geisslerf0343792020-11-18 10:42:21 -06008850 variable and if found, the OpenEmbedded build system installs the
8851 splash screen.
8852
8853 :term:`SYSROOT_DESTDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008854 Points to the temporary directory under the work directory (default
8855 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
8856 where the files populated into the sysroot are assembled during the
8857 :ref:`ref-tasks-populate_sysroot` task.
8858
Andrew Geisslerf0343792020-11-18 10:42:21 -06008859 :term:`SYSROOT_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008860 Directories that are staged into the sysroot by the
8861 :ref:`ref-tasks-populate_sysroot` task. By
Andrew Geisslerc926e172021-05-07 16:11:35 -05008862 default, the following directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008863
8864 SYSROOT_DIRS = " \
8865 ${includedir} \
8866 ${libdir} \
8867 ${base_libdir} \
8868 ${nonarch_base_libdir} \
8869 ${datadir} \
Andrew Geissler5199d832021-09-24 16:47:35 -05008870 /sysroot-only \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008871 "
8872
Patrick Williams84603582024-12-14 08:00:57 -05008873 Consider the following example in which you need to manipulate this variable.
8874 Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is
8875 installed into a custom folder other than "``${libdir}``"
8876 or "``${base_libdir}``", let's say "``/opt/lib``".
8877
8878 .. note::
8879
8880 This is not a recommended way to deal with shared libraries, but this
8881 is just to show the usefulness of setting :term:`SYSROOT_DIRS`.
8882
8883 When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in
8884 :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``A``
8885 into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``".
8886
8887 Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to
8888 ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So,
8889 the linking process will fail.
8890
8891 To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`::
8892
8893 SYSROOT_DIRS:append = " /opt/lib"
8894
8895 .. note::
8896 Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail
8897 because the linker does not know that location, since :term:`TARGET_LDFLAGS`
8898 doesn't contain it (if your recipe is for the target). Therefore, so you should add::
8899
8900 TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib"
8901
Andrew Geissler9aee5002022-03-30 16:27:02 +00008902 :term:`SYSROOT_DIRS_IGNORE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008903 Directories that are not staged into the sysroot by the
8904 :ref:`ref-tasks-populate_sysroot` task. You
8905 can use this variable to exclude certain subdirectories of
8906 directories listed in :term:`SYSROOT_DIRS` from
Andrew Geisslerc926e172021-05-07 16:11:35 -05008907 staging. By default, the following directories are not staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008908
Andrew Geissler9aee5002022-03-30 16:27:02 +00008909 SYSROOT_DIRS_IGNORE = " \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008910 ${mandir} \
8911 ${docdir} \
8912 ${infodir} \
Andrew Geissler5199d832021-09-24 16:47:35 -05008913 ${datadir}/X11/locale \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008914 ${datadir}/applications \
Andrew Geissler5199d832021-09-24 16:47:35 -05008915 ${datadir}/bash-completion \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008916 ${datadir}/fonts \
Andrew Geissler5199d832021-09-24 16:47:35 -05008917 ${datadir}/gtk-doc/html \
8918 ${datadir}/installed-tests \
8919 ${datadir}/locale \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008920 ${datadir}/pixmaps \
Andrew Geissler5199d832021-09-24 16:47:35 -05008921 ${datadir}/terminfo \
8922 ${libdir}/${BPN}/ptest \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008923 "
8924
Andrew Geisslerf0343792020-11-18 10:42:21 -06008925 :term:`SYSROOT_DIRS_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008926 Extra directories staged into the sysroot by the
8927 :ref:`ref-tasks-populate_sysroot` task for
8928 ``-native`` recipes, in addition to those specified in
8929 :term:`SYSROOT_DIRS`. By default, the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05008930 extra directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008931
8932 SYSROOT_DIRS_NATIVE = " \
8933 ${bindir} \
8934 ${sbindir} \
8935 ${base_bindir} \
8936 ${base_sbindir} \
8937 ${libexecdir} \
8938 ${sysconfdir} \
8939 ${localstatedir} \
8940 "
8941
8942 .. note::
8943
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008944 Programs built by ``-native`` recipes run directly from the sysroot
8945 (:term:`STAGING_DIR_NATIVE`), which is why additional directories
8946 containing program executables and supporting files need to be staged.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008947
Andrew Geisslerf0343792020-11-18 10:42:21 -06008948 :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008949 A list of functions to execute after files are staged into the
8950 sysroot. These functions are usually used to apply additional
8951 processing on the staged files, or to stage additional files.
8952
Andrew Geisslerf0343792020-11-18 10:42:21 -06008953 :term:`SYSTEMD_AUTO_ENABLE`
Andrew Geissler517393d2023-01-13 08:55:19 -06008954 When inheriting the :ref:`ref-classes-systemd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008955 this variable specifies whether the specified service in
8956 :term:`SYSTEMD_SERVICE` should start
8957 automatically or not. By default, the service is enabled to
8958 automatically start at boot time. The default setting is in the
Andrew Geissler517393d2023-01-13 08:55:19 -06008959 :ref:`ref-classes-systemd` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008960
8961 SYSTEMD_AUTO_ENABLE ??= "enable"
8962
8963 You can disable the service by setting the variable to "disable".
8964
Andrew Geisslerf0343792020-11-18 10:42:21 -06008965 :term:`SYSTEMD_BOOT_CFG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008966 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05008967 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008968 configuration file that should be used. By default, the
Andrew Geissler517393d2023-01-13 08:55:19 -06008969 :ref:`ref-classes-systemd-boot` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05008970 :term:`SYSTEMD_BOOT_CFG` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008971
Patrick Williamsdb4c27e2022-08-05 08:10:29 -05008972 SYSTEMD_BOOT_CFG ?= "${S}/loader.conf"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008973
8974 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008975 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008976
Andrew Geisslerf0343792020-11-18 10:42:21 -06008977 :term:`SYSTEMD_BOOT_ENTRIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008978 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05008979 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008980 list of entry files (``*.conf``) to install that contain one boot
Andrew Geissler517393d2023-01-13 08:55:19 -06008981 entry per file. By default, the :ref:`ref-classes-systemd-boot` class
8982 sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008983
8984 SYSTEMD_BOOT_ENTRIES ?= ""
8985
8986 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008987 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008988
Andrew Geisslerf0343792020-11-18 10:42:21 -06008989 :term:`SYSTEMD_BOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008990 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05008991 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008992 boot menu timeout in seconds. By default, the
Andrew Geissler517393d2023-01-13 08:55:19 -06008993 :ref:`ref-classes-systemd-boot` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05008994 :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008995
8996 SYSTEMD_BOOT_TIMEOUT ?= "10"
8997
8998 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008999 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009000
Andrew Geissler615f2f12022-07-15 14:00:58 -05009001 :term:`SYSTEMD_DEFAULT_TARGET`
9002
9003 This variable allows to set the default unit that systemd starts at bootup.
9004 Usually, this is either ``multi-user.target`` or ``graphical.target``.
9005 This works by creating a ``default.target`` symbolic link to the chosen systemd
9006 target file.
9007
9008 See `systemd's documentation
9009 <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__
9010 for details.
9011
Patrick Williams2390b1b2022-11-03 13:47:49 -05009012 For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb
9013 </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>`
Andrew Geissler615f2f12022-07-15 14:00:58 -05009014 recipe::
9015
9016 SYSTEMD_DEFAULT_TARGET = "graphical.target"
9017
Andrew Geisslerf0343792020-11-18 10:42:21 -06009018 :term:`SYSTEMD_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -06009019 When inheriting the :ref:`ref-classes-systemd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009020 this variable locates the systemd unit files when they are not found
Andrew Geissler09036742021-06-25 14:25:14 -05009021 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009022 variable is set such that the systemd unit files are assumed to
Andrew Geisslerc926e172021-05-07 16:11:35 -05009023 reside in the recipes main package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009024
9025 SYSTEMD_PACKAGES ?= "${PN}"
9026
9027 If these unit files are not in this recipe's main package, you need
Andrew Geissler09036742021-06-25 14:25:14 -05009028 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009029 the build system can find the systemd unit files.
9030
Andrew Geisslerf0343792020-11-18 10:42:21 -06009031 :term:`SYSTEMD_SERVICE`
Andrew Geissler517393d2023-01-13 08:55:19 -06009032 When inheriting the :ref:`ref-classes-systemd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009033 this variable specifies the systemd service name for a package.
9034
Andrew Geissler615f2f12022-07-15 14:00:58 -05009035 Multiple services can be specified, each one separated by a space.
9036
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009037 When you specify this file in your recipe, use a package name
9038 override to indicate the package to which the value applies. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05009039 an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009040
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009041 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009042
Andrew Geissler615f2f12022-07-15 14:00:58 -05009043 The package overrides that can be specified are directly related to the value of
Andrew Geissler517393d2023-01-13 08:55:19 -06009044 :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES`
Andrew Geissler615f2f12022-07-15 14:00:58 -05009045 will be silently ignored.
9046
Andrew Geisslerf0343792020-11-18 10:42:21 -06009047 :term:`SYSVINIT_ENABLED_GETTYS`
Patrick Williams8e7b46e2023-05-01 14:19:06 -05009048 When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009049 specifies a space-separated list of the virtual terminals that should
Patrick Williams8e7b46e2023-05-01 14:19:06 -05009050 run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming
9051 :term:`USE_VT` is not set to "0".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009052
Andrew Geissler09036742021-06-25 14:25:14 -05009053 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009054 run a getty on the first virtual terminal).
9055
Andrew Geisslerf0343792020-11-18 10:42:21 -06009056 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009057 This variable points to a directory were BitBake places temporary
9058 files, which consist mostly of task logs and scripts, when building a
Andrew Geisslerc926e172021-05-07 16:11:35 -05009059 particular recipe. The variable is typically set as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009060
9061 T = "${WORKDIR}/temp"
9062
9063 The :term:`WORKDIR` is the directory into which
9064 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
9065 file sets this variable.
9066
Andrew Geissler09036742021-06-25 14:25:14 -05009067 The :term:`T` variable is not to be confused with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009068 :term:`TMPDIR` variable, which points to the root of
9069 the directory tree where BitBake places the output of an entire
9070 build.
9071
Andrew Geisslerf0343792020-11-18 10:42:21 -06009072 :term:`TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009073 The target machine's architecture. The OpenEmbedded build system
9074 supports many architectures. Here is an example list of architectures
9075 supported. This list is by no means complete as the architecture is
9076 configurable:
9077
9078 - arm
9079 - i586
9080 - x86_64
9081 - powerpc
9082 - powerpc64
9083 - mips
9084 - mipsel
9085
9086 For additional information on machine architectures, see the
9087 :term:`TUNE_ARCH` variable.
9088
Andrew Geisslerf0343792020-11-18 10:42:21 -06009089 :term:`TARGET_AS_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009090 Specifies architecture-specific assembler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05009091 system. :term:`TARGET_AS_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009092 :term:`TUNE_ASARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05009093 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009094
9095 TARGET_AS_ARCH = "${TUNE_ASARGS}"
9096
Andrew Geisslerf0343792020-11-18 10:42:21 -06009097 :term:`TARGET_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009098 Specifies architecture-specific C compiler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05009099 system. :term:`TARGET_CC_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009100 :term:`TUNE_CCARGS` by default.
9101
9102 .. note::
9103
Andrew Geissler4c19ea12020-10-27 13:52:24 -05009104 It is a common workaround to append :term:`LDFLAGS` to
Andrew Geissler09036742021-06-25 14:25:14 -05009105 :term:`TARGET_CC_ARCH` in recipes that build software for the target that
9106 would not otherwise respect the exported :term:`LDFLAGS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009107
Andrew Geisslerf0343792020-11-18 10:42:21 -06009108 :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009109 This is a specific kernel compiler flag for a CPU or Application
9110 Binary Interface (ABI) tune. The flag is used rarely and only for
9111 cases where a userspace :term:`TUNE_CCARGS` is not
Andrew Geissler09036742021-06-25 14:25:14 -05009112 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009113 variable allows the kernel (and associated modules) to use a
9114 different configuration. See the
9115 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
9116 :term:`Source Directory` for an example.
9117
Andrew Geisslerf0343792020-11-18 10:42:21 -06009118 :term:`TARGET_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009119 Specifies the flags to pass to the C compiler when building for the
9120 target. When building in the target context,
9121 :term:`CFLAGS` is set to the value of this variable by
9122 default.
9123
Andrew Geissler09036742021-06-25 14:25:14 -05009124 Additionally, the SDK's environment setup script sets the :term:`CFLAGS`
9125 variable in the environment to the :term:`TARGET_CFLAGS` value so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009126 executables built using the SDK also have the flags applied.
9127
Andrew Geisslerf0343792020-11-18 10:42:21 -06009128 :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009129 Specifies the flags to pass to the C pre-processor (i.e. to both the
9130 C and the C++ compilers) when building for the target. When building
9131 in the target context, :term:`CPPFLAGS` is set to the
9132 value of this variable by default.
9133
9134 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05009135 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009136 value so that executables built using the SDK also have the flags
9137 applied.
9138
Andrew Geisslerf0343792020-11-18 10:42:21 -06009139 :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009140 Specifies the flags to pass to the C++ compiler when building for the
9141 target. When building in the target context,
9142 :term:`CXXFLAGS` is set to the value of this variable
9143 by default.
9144
9145 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05009146 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009147 value so that executables built using the SDK also have the flags
9148 applied.
9149
Patrick Williams2f814a62024-04-16 16:28:03 -05009150 :term:`TARGET_DBGSRC_DIR`
9151 Specifies the target path to debug source files. The default is
9152 ``/usr/src/debug/${PN}/${PV}``.
9153
Andrew Geisslerf0343792020-11-18 10:42:21 -06009154 :term:`TARGET_FPU`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009155 Specifies the method for handling FPU code. For FPU-less targets,
9156 which include most ARM CPUs, the variable must be set to "soft". If
9157 not, the kernel emulation gets used, which results in a performance
9158 penalty.
9159
Andrew Geisslerf0343792020-11-18 10:42:21 -06009160 :term:`TARGET_LD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009161 Specifies architecture-specific linker flags for the target system.
Andrew Geissler09036742021-06-25 14:25:14 -05009162 :term:`TARGET_LD_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009163 :term:`TUNE_LDARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05009164 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009165
9166 TARGET_LD_ARCH = "${TUNE_LDARGS}"
9167
Andrew Geisslerf0343792020-11-18 10:42:21 -06009168 :term:`TARGET_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009169 Specifies the flags to pass to the linker when building for the
9170 target. When building in the target context,
9171 :term:`LDFLAGS` is set to the value of this variable
9172 by default.
9173
9174 Additionally, the SDK's environment setup script sets the
9175 :term:`LDFLAGS` variable in the environment to the
Andrew Geissler09036742021-06-25 14:25:14 -05009176 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009177 have the flags applied.
9178
Andrew Geisslerf0343792020-11-18 10:42:21 -06009179 :term:`TARGET_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009180 Specifies the target's operating system. The variable can be set to
9181 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
William A. Kennington IIIac69b482021-06-02 12:28:27 -07009182 for musl libc. For ARM/EABI targets, the possible values are
9183 "linux-gnueabi" and "linux-musleabi".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009184
Andrew Geisslerf0343792020-11-18 10:42:21 -06009185 :term:`TARGET_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009186 Specifies the prefix used for the toolchain binary target tools.
9187
9188 Depending on the type of recipe and the build target,
Andrew Geissler5f350902021-07-23 13:09:54 -04009189 :term:`TARGET_PREFIX` is set as follows:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009190
9191 - For recipes building for the target machine, the value is
9192 "${:term:`TARGET_SYS`}-".
9193
9194 - For native recipes, the build system sets the variable to the
Andrew Geissler5f350902021-07-23 13:09:54 -04009195 value of :term:`BUILD_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009196
Andrew Geissler517393d2023-01-13 08:55:19 -06009197 - For native SDK recipes (:ref:`ref-classes-nativesdk`),
9198 the build system sets the variable to the value of :term:`SDK_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009199
Andrew Geisslerf0343792020-11-18 10:42:21 -06009200 :term:`TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009201 Specifies the system, including the architecture and the operating
9202 system, for which the build is occurring in the context of the
9203 current recipe.
9204
9205 The OpenEmbedded build system automatically sets this variable based
9206 on :term:`TARGET_ARCH`,
9207 :term:`TARGET_VENDOR`, and
9208 :term:`TARGET_OS` variables.
9209
9210 .. note::
9211
Andrew Geissler09036742021-06-25 14:25:14 -05009212 You do not need to set the :term:`TARGET_SYS` variable yourself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009213
9214 Consider these two examples:
9215
9216 - Given a native recipe on a 32-bit, x86 machine running Linux, the
9217 value is "i686-linux".
9218
9219 - Given a recipe being built for a little-endian, MIPS target
9220 running Linux, the value might be "mipsel-linux".
9221
Andrew Geisslerf0343792020-11-18 10:42:21 -06009222 :term:`TARGET_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009223 Specifies the name of the target vendor.
9224
Andrew Geisslerf0343792020-11-18 10:42:21 -06009225 :term:`TCLIBC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009226 Specifies the GNU standard C library (``libc``) variant to use during
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00009227 the build process.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009228
Andrew Geissler7e0e3c02022-02-25 20:34:39 +00009229 You can select "glibc", "musl", "newlib", or "baremetal".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009230
Andrew Geisslerf0343792020-11-18 10:42:21 -06009231 :term:`TCMODE`
Andrew Geissler09036742021-06-25 14:25:14 -05009232 Specifies the toolchain selector. :term:`TCMODE` controls the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009233 characteristics of the generated packages and images by telling the
9234 OpenEmbedded build system which toolchain profile to use. By default,
9235 the OpenEmbedded build system builds its own internal toolchain. The
9236 variable's default value is "default", which uses that internal
9237 toolchain.
9238
9239 .. note::
9240
Andrew Geissler09036742021-06-25 14:25:14 -05009241 If :term:`TCMODE` is set to a value other than "default", then it is your
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009242 responsibility to ensure that the toolchain is compatible with the
9243 default toolchain. Using older or newer versions of these
Andrew Geissler517393d2023-01-13 08:55:19 -06009244 components might cause build problems. See
Andrew Geissler6aa7eec2023-03-03 12:41:14 -06009245 :doc:`Release Information </migration-guides/index>` for your
Andrew Geissler517393d2023-01-13 08:55:19 -06009246 version of the Yocto Project, to find the specific components with
9247 which the toolchain must be compatible.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009248
Andrew Geissler09036742021-06-25 14:25:14 -05009249 The :term:`TCMODE` variable is similar to :term:`TCLIBC`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009250 which controls the variant of the GNU standard C library (``libc``)
9251 used during the build process: ``glibc`` or ``musl``.
9252
9253 With additional layers, it is possible to use a pre-compiled external
9254 toolchain. One example is the Sourcery G++ Toolchain. The support for
9255 this toolchain resides in the separate Mentor Graphics
9256 ``meta-sourcery`` layer at
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009257 https://github.com/MentorEmbedded/meta-sourcery/.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009258
9259 The layer's ``README`` file contains information on how to use the
Andrew Geissler517393d2023-01-13 08:55:19 -06009260 Sourcery G++ Toolchain as an external toolchain. You will have to
9261 add the layer to your ``bblayers.conf`` file and then set the
9262 :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to
9263 the location of the toolchain.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009264
9265 The fundamentals used for this example apply to any external
9266 toolchain. You can use ``meta-sourcery`` as a template for adding
9267 support for other external toolchains.
9268
Andrew Geissler517393d2023-01-13 08:55:19 -06009269 In addition to toolchain configuration, you will also need a
9270 corresponding toolchain recipe file. This recipe file needs to package
9271 up any pre-built objects in the toolchain such as ``libgcc``,
9272 ``libstdcc++``, any locales, and ``libc``.
9273
Andrew Geissler87f5cff2022-09-30 13:13:31 -05009274 :term:`TC_CXX_RUNTIME`
9275 Specifies the C/C++ STL and runtime variant to use during
9276 the build process. Default value is 'gnu'
9277
9278 You can select "gnu", "llvm", or "android".
9279
Andrew Geisslerd5838332022-05-27 11:33:10 -05009280 :term:`TEMPLATECONF`
9281 Specifies the directory used by the build system to find templates
9282 from which to build the ``bblayers.conf`` and ``local.conf`` files.
9283 Use this variable if you wish to customize such files, and the default
9284 BitBake targets shown when sourcing the ``oe-init-build-env`` script.
9285
9286 For details, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06009287 :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory`
Andrew Geisslerd5838332022-05-27 11:33:10 -05009288 section in the Yocto Project Development Tasks manual.
9289
9290 .. note::
9291
9292 You must set this variable in the external environment in order
9293 for it to work.
9294
Andrew Geisslerf0343792020-11-18 10:42:21 -06009295 :term:`TEST_EXPORT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009296 The location the OpenEmbedded build system uses to export tests when
9297 the :term:`TEST_EXPORT_ONLY` variable is set
9298 to "1".
9299
Andrew Geissler09036742021-06-25 14:25:14 -05009300 The :term:`TEST_EXPORT_DIR` variable defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009301 ``"${TMPDIR}/testimage/${PN}"``.
9302
Andrew Geisslerf0343792020-11-18 10:42:21 -06009303 :term:`TEST_EXPORT_ONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009304 Specifies to export the tests only. Set this variable to "1" if you
9305 do not want to run the tests but you want them to be exported in a
9306 manner that you to run them outside of the build system.
9307
Andrew Geisslerf0343792020-11-18 10:42:21 -06009308 :term:`TEST_LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009309 Holds the SSH log and the boot log for QEMU machines. The
Andrew Geissler09036742021-06-25 14:25:14 -05009310 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009311
9312 .. note::
9313
Andrew Geissler4c19ea12020-10-27 13:52:24 -05009314 Actual test results reside in the task log (``log.do_testimage``),
9315 which is in the ``${WORKDIR}/temp/`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009316
Andrew Geisslerf0343792020-11-18 10:42:21 -06009317 :term:`TEST_POWERCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009318 For automated hardware testing, specifies the command to use to
9319 control the power of the target machine under test. Typically, this
9320 command would point to a script that performs the appropriate action
9321 (e.g. interacting with a web-enabled power strip). The specified
9322 command should expect to receive as the last argument "off", "on" or
9323 "cycle" specifying to power off, on, or cycle (power off and then
9324 power on) the device, respectively.
9325
Andrew Geisslerf0343792020-11-18 10:42:21 -06009326 :term:`TEST_POWERCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009327 For automated hardware testing, specifies additional arguments to
9328 pass through to the command specified in
9329 :term:`TEST_POWERCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05009330 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009331 wish, for example, to separate the machine-specific and
9332 non-machine-specific parts of the arguments.
9333
Andrew Geisslerf0343792020-11-18 10:42:21 -06009334 :term:`TEST_QEMUBOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009335 The time in seconds allowed for an image to boot before automated
9336 runtime tests begin to run against an image. The default timeout
9337 period to allow the boot process to reach the login prompt is 500
9338 seconds. You can specify a different value in the ``local.conf``
9339 file.
9340
9341 For more information on testing images, see the
Patrick Williams96e4b4e2025-02-03 15:49:15 -05009342 ":ref:`test-manual/runtime-testing:performing automated runtime testing`"
9343 section in the Yocto Project Test Environment Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009344
Andrew Geisslerf0343792020-11-18 10:42:21 -06009345 :term:`TEST_SERIALCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009346 For automated hardware testing, specifies the command to use to
9347 connect to the serial console of the target machine under test. This
9348 command simply needs to connect to the serial console and forward
9349 that connection to standard input and output as any normal terminal
9350 program does.
9351
9352 For example, to use the Picocom terminal program on serial device
Andrew Geisslerc926e172021-05-07 16:11:35 -05009353 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009354
9355 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
9356
Andrew Geisslerf0343792020-11-18 10:42:21 -06009357 :term:`TEST_SERIALCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009358 For automated hardware testing, specifies additional arguments to
9359 pass through to the command specified in
9360 :term:`TEST_SERIALCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05009361 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009362 wish, for example, to separate the machine-specific and
9363 non-machine-specific parts of the command.
9364
Andrew Geisslerf0343792020-11-18 10:42:21 -06009365 :term:`TEST_SERVER_IP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009366 The IP address of the build machine (host machine). This IP address
9367 is usually automatically detected. However, if detection fails, this
9368 variable needs to be set to the IP address of the build machine (i.e.
9369 where the build is taking place).
9370
9371 .. note::
9372
Andrew Geissler09036742021-06-25 14:25:14 -05009373 The :term:`TEST_SERVER_IP` variable is only used for a small number of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05009374 tests such as the "dnf" test suite, which needs to download packages
9375 from ``WORKDIR/oe-rootfs-repo``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009376
Andrew Geisslerf0343792020-11-18 10:42:21 -06009377 :term:`TEST_SUITES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009378 An ordered list of tests (modules) to run against an image when
9379 performing automated runtime testing.
9380
9381 The OpenEmbedded build system provides a core set of tests that can
9382 be used against images.
9383
9384 .. note::
9385
9386 Currently, there is only support for running these tests under
9387 QEMU.
9388
9389 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
Andrew Geissler09036742021-06-25 14:25:14 -05009390 your own tests to the list of tests by appending :term:`TEST_SUITES` as
Andrew Geisslerc926e172021-05-07 16:11:35 -05009391 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009392
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009393 TEST_SUITES:append = " mytest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009394
9395 Alternatively, you can
9396 provide the "auto" option to have all applicable tests run against
Andrew Geissler517393d2023-01-13 08:55:19 -06009397 the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009398
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009399 TEST_SUITES:append = " auto"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009400
9401 Using this option causes the
9402 build system to automatically run tests that are applicable to the
9403 image. Tests that are not applicable are skipped.
9404
9405 The order in which tests are run is important. Tests that depend on
9406 another test must appear later in the list than the test on which
9407 they depend. For example, if you append the list of tests with two
9408 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
Andrew Geisslerc926e172021-05-07 16:11:35 -05009409 ``test_A``, then you must order the tests as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009410
9411 TEST_SUITES = "test_A test_B"
9412
9413 For more information on testing images, see the
Patrick Williams96e4b4e2025-02-03 15:49:15 -05009414 ":ref:`test-manual/runtime-testing:performing automated runtime testing`"
9415 section in the Yocto Project Test Environment Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009416
Andrew Geisslerf0343792020-11-18 10:42:21 -06009417 :term:`TEST_TARGET`
9418 Specifies the target controller to use when running tests against a
Andrew Geisslerc926e172021-05-07 16:11:35 -05009419 test image. The default controller to use is "qemu"::
Andrew Geisslerf0343792020-11-18 10:42:21 -06009420
9421 TEST_TARGET = "qemu"
9422
9423 A target controller is a class that defines how an image gets
9424 deployed on a target and how a target is started. A layer can extend
9425 the controllers by adding a module in the layer's
9426 ``/lib/oeqa/controllers`` directory and by inheriting the
9427 ``BaseTarget`` class, which is an abstract class that cannot be used
Andrew Geissler09036742021-06-25 14:25:14 -05009428 as a value of :term:`TEST_TARGET`.
Andrew Geisslerf0343792020-11-18 10:42:21 -06009429
Andrew Geissler5f350902021-07-23 13:09:54 -04009430 You can provide the following arguments with :term:`TEST_TARGET`:
Andrew Geisslerf0343792020-11-18 10:42:21 -06009431
9432 - *"qemu":* Boots a QEMU image and runs the tests. See the
Patrick Williams96e4b4e2025-02-03 15:49:15 -05009433 ":ref:`test-manual/runtime-testing:enabling runtime tests on qemu`" section
9434 in the Yocto Project Test Environment Manual for more
Andrew Geisslerf0343792020-11-18 10:42:21 -06009435 information.
9436
9437 - *"simpleremote":* Runs the tests on target hardware that is
9438 already up and running. The hardware can be on the network or it
9439 can be a device running an image on QEMU. You must also set
9440 :term:`TEST_TARGET_IP` when you use
9441 "simpleremote".
9442
9443 .. note::
9444
9445 This argument is defined in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05009446 ``meta/lib/oeqa/controllers/simpleremote.py``.
Andrew Geisslerf0343792020-11-18 10:42:21 -06009447
9448 For information on running tests on hardware, see the
Patrick Williams96e4b4e2025-02-03 15:49:15 -05009449 ":ref:`test-manual/runtime-testing:enabling runtime tests on hardware`"
9450 section in the Yocto Project Test Environment Manual.
Andrew Geisslerf0343792020-11-18 10:42:21 -06009451
9452 :term:`TEST_TARGET_IP`
Andrew Geissler09036742021-06-25 14:25:14 -05009453 The IP address of your hardware under test. The :term:`TEST_TARGET_IP`
Andrew Geisslerf0343792020-11-18 10:42:21 -06009454 variable has no effect when :term:`TEST_TARGET` is
9455 set to "qemu".
9456
9457 When you specify the IP address, you can also include a port. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05009458 an example::
Andrew Geisslerf0343792020-11-18 10:42:21 -06009459
9460 TEST_TARGET_IP = "192.168.1.4:2201"
9461
9462 Specifying a port is
9463 useful when SSH is started on a non-standard port or in cases when
9464 your hardware under test is behind a firewall or network that is not
9465 directly accessible from your host and you need to do port address
9466 translation.
9467
9468 :term:`TESTIMAGE_AUTO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009469 Automatically runs the series of automated tests for images when an
Andrew Geissler09036742021-06-25 14:25:14 -05009470 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009471 any image that successfully builds to automatically boot under QEMU.
9472 Using the variable also adds in dependencies so that any SDK for
9473 which testing is requested is automatically built first.
9474
9475 These tests are written in Python making use of the ``unittest``
9476 module, and the majority of them run commands on the target system
9477 over ``ssh``. You can set this variable to "1" in your ``local.conf``
9478 file in the :term:`Build Directory` to have the
9479 OpenEmbedded build system automatically run these tests after an
9480 image successfully builds:
9481
9482 TESTIMAGE_AUTO = "1"
9483
9484 For more information
9485 on enabling, running, and writing these tests, see the
Patrick Williams96e4b4e2025-02-03 15:49:15 -05009486 ":ref:`test-manual/runtime-testing:performing automated runtime testing`"
9487 section in the Yocto Project Test Environment Manual and the
Patrick Williams975a06f2022-10-21 14:42:47 -05009488 ":ref:`ref-classes-testimage`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009489
Patrick Williams84603582024-12-14 08:00:57 -05009490 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS`
9491 When using the :ref:`ref-classes-testimage` class, the variable
9492 :term:`TESTIMAGE_FAILED_QA_ARTIFACTS` lists space-separated paths on the
9493 target to retrieve onto the host.
9494
Andrew Geisslerf0343792020-11-18 10:42:21 -06009495 :term:`THISDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009496 The directory in which the file BitBake is currently parsing is
9497 located. Do not manually set this variable.
9498
Andrew Geisslerf0343792020-11-18 10:42:21 -06009499 :term:`TIME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009500 The time the build was started. Times appear using the hour, minute,
9501 and second (HMS) format (e.g. "140159" for one minute and fifty-nine
9502 seconds past 1400 hours).
9503
Andrew Geisslerf0343792020-11-18 10:42:21 -06009504 :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009505 This variable is the base directory the OpenEmbedded build system
9506 uses for all build output and intermediate files (other than the
Andrew Geissler09036742021-06-25 14:25:14 -05009507 shared state cache). By default, the :term:`TMPDIR` variable points to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009508 ``tmp`` within the :term:`Build Directory`.
9509
9510 If you want to establish this directory in a location other than the
9511 default, you can uncomment and edit the following statement in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05009512 ``conf/local.conf`` file in the :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009513
9514 #TMPDIR = "${TOPDIR}/tmp"
9515
Andrew Geissler09036742021-06-25 14:25:14 -05009516 An example use for this scenario is to set :term:`TMPDIR` to a local disk,
Patrick Williams2390b1b2022-11-03 13:47:49 -05009517 which does not use NFS, while having the :term:`Build Directory` use NFS.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009518
Andrew Geissler09036742021-06-25 14:25:14 -05009519 The filesystem used by :term:`TMPDIR` must have standard filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009520 semantics (i.e. mixed-case files are unique, POSIX file locking, and
9521 persistent inodes). Due to various issues with NFS and bugs in some
9522 implementations, NFS does not meet this minimum requirement.
Andrew Geissler09036742021-06-25 14:25:14 -05009523 Consequently, :term:`TMPDIR` cannot be on NFS.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009524
Andrew Geisslerf0343792020-11-18 10:42:21 -06009525 :term:`TOOLCHAIN_HOST_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009526 This variable lists packages the OpenEmbedded build system uses when
9527 building an SDK, which contains a cross-development environment. The
9528 packages specified by this variable are part of the toolchain set
9529 that runs on the :term:`SDKMACHINE`, and each
9530 package should usually have the prefix ``nativesdk-``. For example,
Andrew Geisslerc926e172021-05-07 16:11:35 -05009531 consider the following command when building an SDK::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009532
9533 $ bitbake -c populate_sdk imagename
9534
9535 In this case, a default list of packages is
9536 set in this variable, but you can add additional packages to the
9537 list. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009538 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009539 in the Yocto Project Application Development and the Extensible
9540 Software Development Kit (eSDK) manual for more information.
9541
9542 For background information on cross-development toolchains in the
9543 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009544 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009545 section in the Yocto Project Overview and Concepts Manual. For
9546 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009547 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009548
Andrew Geisslereff27472021-10-29 15:35:00 -05009549 Note that this variable applies to building an SDK, not an eSDK,
Andrew Geissler517393d2023-01-13 08:55:19 -06009550 in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be
Andrew Geisslereff27472021-10-29 15:35:00 -05009551 used instead.
9552
9553 :term:`TOOLCHAIN_HOST_TASK_ESDK`
9554 This variable allows to extend what is installed in the host
9555 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
9556 applying to SDKs.
9557
Patrick Williamsac13d5f2023-11-24 18:59:46 -06009558 :term:`TOOLCHAIN_OPTIONS`
9559 This variable holds extra options passed to the compiler and the linker
9560 for non ``-native`` recipes as they have to point to their custom
9561 ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`::
9562
9563 TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}"
9564
9565 Native recipes don't need this variable to be set, as they are
9566 built for the host machine with the native compiler.
9567
Andrew Geisslerf0343792020-11-18 10:42:21 -06009568 :term:`TOOLCHAIN_OUTPUTNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009569 This variable defines the name used for the toolchain output. The
9570 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
Andrew Geissler09036742021-06-25 14:25:14 -05009571 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009572
9573 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
9574
9575 See
9576 the :term:`SDK_NAME` and
9577 :term:`SDK_VERSION` variables for additional
9578 information.
9579
Andrew Geisslerf0343792020-11-18 10:42:21 -06009580 :term:`TOOLCHAIN_TARGET_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009581 This variable lists packages the OpenEmbedded build system uses when
9582 it creates the target part of an SDK (i.e. the part built for the
9583 target hardware), which includes libraries and headers. Use this
9584 variable to add individual packages to the part of the SDK that runs
9585 on the target. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009586 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009587 in the Yocto Project Application Development and the Extensible
9588 Software Development Kit (eSDK) manual for more information.
9589
9590 For background information on cross-development toolchains in the
9591 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009592 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009593 section in the Yocto Project Overview and Concepts Manual. For
9594 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06009595 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009596
Andrew Geissler517393d2023-01-13 08:55:19 -06009597 :term:`TOPDIR`
9598 See :term:`bitbake:TOPDIR` in the BitBake manual.
9599
Andrew Geisslerf0343792020-11-18 10:42:21 -06009600 :term:`TRANSLATED_TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009601 A sanitized version of :term:`TARGET_ARCH`. This
9602 variable is used where the architecture is needed in a value where
9603 underscores are not allowed, for example within package filenames. In
9604 this case, dash characters replace any underscore characters used in
Andrew Geissler09036742021-06-25 14:25:14 -05009605 :term:`TARGET_ARCH`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009606
9607 Do not edit this variable.
9608
Andrew Geisslerf0343792020-11-18 10:42:21 -06009609 :term:`TUNE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009610 The GNU canonical architecture for a specific architecture (i.e.
9611 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
9612 this value to setup configuration.
9613
Andrew Geissler09036742021-06-25 14:25:14 -05009614 :term:`TUNE_ARCH` definitions are specific to a given architecture. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009615 definitions can be a single static definition, or can be dynamically
9616 adjusted. You can see details for a given CPU family by looking at
9617 the architecture's ``README`` file. For example, the
9618 ``meta/conf/machine/include/mips/README`` file in the
9619 :term:`Source Directory` provides information for
Andrew Geissler09036742021-06-25 14:25:14 -05009620 :term:`TUNE_ARCH` specific to the ``mips`` architecture.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009621
Andrew Geissler09036742021-06-25 14:25:14 -05009622 :term:`TUNE_ARCH` is tied closely to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009623 :term:`TARGET_ARCH`, which defines the target
9624 machine's architecture. The BitBake configuration file
Andrew Geissler09036742021-06-25 14:25:14 -05009625 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009626
9627 TARGET_ARCH = "${TUNE_ARCH}"
9628
9629 The following list, which is by no means complete since architectures
9630 are configurable, shows supported machine architectures:
9631
9632 - arm
9633 - i586
9634 - x86_64
9635 - powerpc
9636 - powerpc64
9637 - mips
9638 - mipsel
9639
Andrew Geisslerf0343792020-11-18 10:42:21 -06009640 :term:`TUNE_ASARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009641 Specifies architecture-specific assembler flags for the target
9642 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05009643 :term:`TUNE_ASARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009644 typically under ``meta/conf/machine/include/`` and are influenced
9645 through :term:`TUNE_FEATURES`. For example, the
9646 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05009647 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009648
9649 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
9650
9651 .. note::
9652
9653 Board Support Packages (BSPs) select the tune. The selected tune,
9654 in turn, affects the tune variables themselves (i.e. the tune can
9655 supply its own set of flags).
9656
Andrew Geisslerf0343792020-11-18 10:42:21 -06009657 :term:`TUNE_CCARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009658 Specifies architecture-specific C compiler flags for the target
9659 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05009660 :term:`TUNE_CCARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009661 typically under ``meta/conf/machine/include/`` and are influenced
9662 through :term:`TUNE_FEATURES`.
9663
9664 .. note::
9665
9666 Board Support Packages (BSPs) select the tune. The selected tune,
9667 in turn, affects the tune variables themselves (i.e. the tune can
9668 supply its own set of flags).
9669
Andrew Geisslerf0343792020-11-18 10:42:21 -06009670 :term:`TUNE_FEATURES`
9671 Features used to "tune" a compiler for optimal use given a specific
9672 processor. The features are defined within the tune files and allow
9673 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
9674 the features.
9675
9676 The OpenEmbedded build system verifies the features to be sure they
9677 are not conflicting and that they are supported.
9678
9679 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
Andrew Geissler09036742021-06-25 14:25:14 -05009680 :term:`TUNE_FEATURES` as follows::
Andrew Geisslerf0343792020-11-18 10:42:21 -06009681
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009682 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"
Andrew Geisslerf0343792020-11-18 10:42:21 -06009683
9684 See the :term:`DEFAULTTUNE` variable for more information.
9685
9686 :term:`TUNE_LDARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009687 Specifies architecture-specific linker flags for the target system.
9688 The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05009689 :term:`TUNE_LDARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009690 typically under ``meta/conf/machine/include/`` and are influenced
9691 through :term:`TUNE_FEATURES`. For example, the
9692 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05009693 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009694
9695 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
9696
9697 .. note::
9698
9699 Board Support Packages (BSPs) select the tune. The selected tune,
9700 in turn, affects the tune variables themselves (i.e. the tune can
9701 supply its own set of flags).
9702
Andrew Geisslerf0343792020-11-18 10:42:21 -06009703 :term:`TUNE_PKGARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009704 The package architecture understood by the packaging system to define
9705 the architecture, ABI, and tuning of output packages. The specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05009706 tune is defined using the "_tune" override as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009707
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009708 TUNE_PKGARCH:tune-tune = "tune"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009709
9710 These tune-specific package architectures are defined in the machine
9711 include files. Here is an example of the "core2-32" tuning as used in
Andrew Geisslerd159c7f2021-09-02 21:05:58 -05009712 the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009713
Patrick Williams0ca19cc2021-08-16 14:03:13 -05009714 TUNE_PKGARCH:tune-core2-32 = "core2-32"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009715
Andrew Geisslerf0343792020-11-18 10:42:21 -06009716 :term:`TUNECONFLICTS[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009717 Specifies CPU or Application Binary Interface (ABI) tuning features
9718 that conflict with feature.
9719
9720 Known tuning conflicts are specified in the machine include files in
9721 the :term:`Source Directory`. Here is an example from
9722 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
9723 that lists the "o32" and "n64" features as conflicting with the "n32"
Andrew Geisslerc926e172021-05-07 16:11:35 -05009724 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009725
9726 TUNECONFLICTS[n32] = "o32 n64"
9727
Andrew Geisslerf0343792020-11-18 10:42:21 -06009728 :term:`TUNEVALID[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009729 Specifies a valid CPU or Application Binary Interface (ABI) tuning
9730 feature. The specified feature is stored as a flag. Valid features
9731 are specified in the machine include files (e.g.
9732 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
Andrew Geisslerc926e172021-05-07 16:11:35 -05009733 from that file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009734
9735 TUNEVALID[bigendian] = "Enable big-endian mode."
9736
9737 See the machine include files in the :term:`Source Directory`
9738 for these features.
9739
Patrick Williams705982a2024-01-12 09:51:57 -06009740 :term:`UBOOT_BINARY`
9741 Specifies the name of the binary build by U-Boot.
9742
Andrew Geisslerf0343792020-11-18 10:42:21 -06009743 :term:`UBOOT_CONFIG`
Patrick Williams705982a2024-01-12 09:51:57 -06009744 Configures one or more U-Boot configurations to build. Each
9745 configuration can define the :term:`UBOOT_MACHINE` and optionally the
9746 :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009747
Patrick Williams39653562024-03-01 08:54:02 -06009748 Here is an example from the ``meta-freescale`` layer. ::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009749
Patrick Williams705982a2024-01-12 09:51:57 -06009750 UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor"
9751 UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig"
9752 UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin"
9753 UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin"
9754 UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig"
9755 UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig"
9756 UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig"
9757 UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009758
Patrick Williams705982a2024-01-12 09:51:57 -06009759 In this example, all possible seven configurations are selected. Each
9760 configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and
9761 the "sd..." configurations define an individual name for
9762 :term:`UBOOT_BINARY`. No configuration defines a second parameter for
9763 :term:`IMAGE_FSTYPES` to use for the U-Boot image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009764
Andrew Geissler09036742021-06-25 14:25:14 -05009765 For more information on how the :term:`UBOOT_CONFIG` is handled, see the
Andrew Geissler517393d2023-01-13 08:55:19 -06009766 :ref:`ref-classes-uboot-config` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009767
Andrew Geisslerf0343792020-11-18 10:42:21 -06009768 :term:`UBOOT_DTB_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009769 Specifies the load address for the dtb image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05009770 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in
Andrew Geissler517393d2023-01-13 08:55:19 -06009771 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
9772 used in creating the dtb sections of Image Tree Source for the FIT image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009773
Andrew Geisslerf0343792020-11-18 10:42:21 -06009774 :term:`UBOOT_DTBO_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009775 Specifies the load address for the dtbo image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05009776 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in
Andrew Geissler517393d2023-01-13 08:55:19 -06009777 :ref:`ref-classes-kernel-fitimage` class to specify the load address to be
9778 used in creating the dtbo sections of Image Tree Source for the FIT image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009779
Andrew Geisslerf0343792020-11-18 10:42:21 -06009780 :term:`UBOOT_ENTRYPOINT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009781 Specifies the entry point for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05009782 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009783 command-line parameter to the ``uboot-mkimage`` utility.
9784
Patrick Williamsb542dec2023-06-09 01:26:37 -05009785 To pass a 64 bit address for FIT image creation, you will need to set:
9786 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9787 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
Andrew Geissler3eeda902023-05-19 10:14:02 -05009788
Patrick Williamsb542dec2023-06-09 01:26:37 -05009789 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9790 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9791 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9792 classes.
9793
9794 :term:`UBOOT_FIT_ADDRESS_CELLS`
9795 Specifies the value of the ``#address-cells`` value for the
Patrick Williams44b3caf2024-04-12 16:51:14 -05009796 description of the U-Boot FIT image.
Patrick Williamsb542dec2023-06-09 01:26:37 -05009797
9798 The default value is set to "1" by the :ref:`ref-classes-uboot-sign`
Patrick Williams44b3caf2024-04-12 16:51:14 -05009799 class, which corresponds to 32 bit addresses.
Patrick Williamsb542dec2023-06-09 01:26:37 -05009800
9801 For platforms that need to set 64 bit addresses in
9802 :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to
9803 set this value to "2", as two 32 bit values (cells) will be needed
9804 to represent such addresses.
9805
9806 Here is an example setting "0x400000000" as a load address::
Patrick Williams44b3caf2024-04-12 16:51:14 -05009807
Patrick Williamsb542dec2023-06-09 01:26:37 -05009808 UBOOT_FIT_ADDRESS_CELLS = "2"
9809 UBOOT_LOADADDRESS= "0x04 0x00000000"
9810
9811 See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__.
9812
9813 :term:`UBOOT_FIT_DESC`
9814 Specifies the description string encoded into a U-Boot fitImage. The default
9815 value is set by the :ref:`ref-classes-uboot-sign` class as follows::
9816
9817 UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
9818
9819 :term:`UBOOT_FIT_GENERATE_KEYS`
9820 Decides whether to generate the keys for signing the U-Boot fitImage if
9821 they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`.
9822 The default value is "0".
9823
9824 Enable this as follows::
9825
9826 UBOOT_FIT_GENERATE_KEYS = "1"
9827
9828 This variable is used in the :ref:`ref-classes-uboot-sign` class.
9829
9830 :term:`UBOOT_FIT_HASH_ALG`
9831 Specifies the hash algorithm used in creating the U-Boot FIT Image.
9832 It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign`
9833 class.
9834
9835 :term:`UBOOT_FIT_KEY_GENRSA_ARGS`
9836 Arguments to ``openssl genrsa`` for generating a RSA private key for
9837 signing the U-Boot FIT image. The default value of this variable
9838 is set to "-F4" by the :ref:`ref-classes-uboot-sign` class.
9839
9840 :term:`UBOOT_FIT_KEY_REQ_ARGS`
9841 Arguments to ``openssl req`` for generating a certificate for signing
9842 the U-Boot FIT image. The default value is "-batch -new" by the
9843 :ref:`ref-classes-uboot-sign` class, "batch" for
9844 non interactive mode and "new" for generating new keys.
9845
9846 :term:`UBOOT_FIT_KEY_SIGN_PKCS`
9847 Format for the public key certificate used for signing the U-Boot FIT
9848 image. The default value is set to "x509" by the
9849 :ref:`ref-classes-uboot-sign` class.
9850
9851 :term:`UBOOT_FIT_SIGN_ALG`
9852 Specifies the signature algorithm used in creating the U-Boot FIT Image.
9853 This variable is set by default to "rsa2048" by the
9854 :ref:`ref-classes-uboot-sign` class.
9855
9856 :term:`UBOOT_FIT_SIGN_NUMBITS`
9857 Size of the private key used in signing the U-Boot FIT image, in number
9858 of bits. The default value for this variable is set to "2048"
9859 by the :ref:`ref-classes-uboot-sign` class.
9860
9861 :term:`UBOOT_FITIMAGE_ENABLE`
9862 This variable allows to generate a FIT image for U-Boot, which is one
9863 of the ways to implement a verified boot process.
9864
9865 Its default value is "0", so set it to "1" to enable this functionality::
9866
9867 UBOOT_FITIMAGE_ENABLE = "1"
9868
9869 See the :ref:`ref-classes-uboot-sign` class for details.
Patrick Williams44b3caf2024-04-12 16:51:14 -05009870
Andrew Geisslerf0343792020-11-18 10:42:21 -06009871 :term:`UBOOT_LOADADDRESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009872 Specifies the load address for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05009873 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009874 command-line parameter to the ``uboot-mkimage`` utility.
9875
Patrick Williamsb542dec2023-06-09 01:26:37 -05009876 To pass a 64 bit address, you will also need to set:
9877
9878 - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation.
9879 - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation.
9880
9881 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9882 :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`,
9883 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9884 classes.
Andrew Geissler3eeda902023-05-19 10:14:02 -05009885
Andrew Geisslerf0343792020-11-18 10:42:21 -06009886 :term:`UBOOT_LOCALVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009887 Appends a string to the name of the local version of the U-Boot
9888 image. For example, assuming the version of the U-Boot image built
9889 was "2013.10", the full version string reported by U-Boot would be
Andrew Geisslerc926e172021-05-07 16:11:35 -05009890 "2013.10-yocto" given the following statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009891
9892 UBOOT_LOCALVERSION = "-yocto"
9893
Andrew Geisslerf0343792020-11-18 10:42:21 -06009894 :term:`UBOOT_MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009895 Specifies the value passed on the ``make`` command line when building
9896 a U-Boot image. The value indicates the target platform
9897 configuration. You typically set this variable from the machine
9898 configuration file (i.e. ``conf/machine/machine_name.conf``).
9899
9900 Please see the "Selection of Processor Architecture and Board Type"
9901 section in the U-Boot README for valid values for this variable.
9902
Andrew Geisslerf0343792020-11-18 10:42:21 -06009903 :term:`UBOOT_MAKE_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009904 Specifies the target called in the ``Makefile``. The default target
9905 is "all".
9906
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009907 :term:`UBOOT_MKIMAGE`
9908 Specifies the name of the mkimage command as used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06009909 :ref:`ref-classes-kernel-fitimage` class to assemble
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009910 the FIT image. This can be used to substitute an alternative command, wrapper
9911 script or function if desired. The default is "uboot-mkimage".
9912
Andrew Geisslerf0343792020-11-18 10:42:21 -06009913 :term:`UBOOT_MKIMAGE_DTCOPTS`
Patrick Williamsb542dec2023-06-09 01:26:37 -05009914 Options for the device tree compiler passed to ``mkimage -D`` feature
9915 while creating a FIT image with the :ref:`ref-classes-kernel-fitimage`
9916 class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the
9917 :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option
9918 to ``mkimage``.
9919
9920 This variable is also used by the :ref:`ref-classes-uboot-sign` class.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009921
Patrick Williams975a06f2022-10-21 14:42:47 -05009922 :term:`UBOOT_MKIMAGE_KERNEL_TYPE`
9923 Specifies the type argument for the kernel as passed to ``uboot-mkimage``.
9924 The default value is "kernel".
9925
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009926 :term:`UBOOT_MKIMAGE_SIGN`
9927 Specifies the name of the mkimage command as used by the
Andrew Geissler517393d2023-01-13 08:55:19 -06009928 :ref:`ref-classes-kernel-fitimage` class to sign
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009929 the FIT image after it has been assembled (if enabled). This can be used
9930 to substitute an alternative command, wrapper script or function if
9931 desired. The default is "${:term:`UBOOT_MKIMAGE`}".
9932
9933 :term:`UBOOT_MKIMAGE_SIGN_ARGS`
9934 Optionally specifies additional arguments for the
Andrew Geissler517393d2023-01-13 08:55:19 -06009935 :ref:`ref-classes-kernel-fitimage` class to pass to the
Andrew Geisslerd1e89492021-02-12 15:35:20 -06009936 mkimage command when signing the FIT image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009937
Andrew Geisslerf0343792020-11-18 10:42:21 -06009938 :term:`UBOOT_RD_ENTRYPOINT`
Andrew Geissler517393d2023-01-13 08:55:19 -06009939 Specifies the entrypoint for the RAM disk image. During FIT image
9940 creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in
9941 :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be
9942 used in creating the Image Tree Source for the FIT image.
Andrew Geissler4873add2020-11-02 18:44:49 -06009943
Andrew Geisslerf0343792020-11-18 10:42:21 -06009944 :term:`UBOOT_RD_LOADADDRESS`
Andrew Geissler517393d2023-01-13 08:55:19 -06009945 Specifies the load address for the RAM disk image. During FIT image
9946 creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in
9947 :ref:`ref-classes-kernel-fitimage` class to specify the load address to
9948 be used in creating the Image Tree Source for the FIT image.
Andrew Geisslerf0343792020-11-18 10:42:21 -06009949
9950 :term:`UBOOT_SIGN_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009951 Enable signing of FIT image. The default value is "0".
9952
Patrick Williamsb542dec2023-06-09 01:26:37 -05009953 This variable is used by the :ref:`ref-classes-kernel-fitimage`,
9954 :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign`
9955 classes.
9956
Andrew Geisslerf0343792020-11-18 10:42:21 -06009957 :term:`UBOOT_SIGN_KEYDIR`
Patrick Williamsb542dec2023-06-09 01:26:37 -05009958 Location of the directory containing the RSA key and certificate used for
9959 signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and
9960 :ref:`ref-classes-uboot-sign` classes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009961
Andrew Geisslerf0343792020-11-18 10:42:21 -06009962 :term:`UBOOT_SIGN_KEYNAME`
Patrick Williamsb542dec2023-06-09 01:26:37 -05009963 The name of keys used by the :ref:`ref-classes-kernel-fitimage` class
9964 for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR`
9965 directory. If we have for example a ``dev.key`` key and a ``dev.crt``
9966 certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will
9967 have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009968
Andrew Geisslerf0343792020-11-18 10:42:21 -06009969 :term:`UBOOT_SUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009970 Points to the generated U-Boot extension. For example, ``u-boot.sb``
9971 has a ``.sb`` extension.
9972
9973 The default U-Boot extension is ``.bin``
9974
Andrew Geisslerf0343792020-11-18 10:42:21 -06009975 :term:`UBOOT_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05009976 Specifies the target used for building U-Boot. The target is passed
9977 directly as part of the "make" command (e.g. SPL and AIS). If you do
9978 not specifically set this variable, the OpenEmbedded build process
9979 passes and uses "all" for the target during the U-Boot building
9980 process.
9981
Patrick Williams84603582024-12-14 08:00:57 -05009982 :term:`UKIFY_CMD`
9983 When inheriting the :ref:`ref-classes-uki` class,
9984 `ukify <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__ command to build
9985 `Unified Kernel Image (UKI) <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
9986 Defaults to ``ukify build``.
9987
9988 :term:`UKI_CMDLINE`
9989 When inheriting the :ref:`ref-classes-uki` class, the kernel command line
9990 to use when booting the `Unified Kernel Image (UKI)
9991 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
9992 Defaults to ``rootwait root=LABEL=root console=${KERNEL_CONSOLE}``.
9993
9994 :term:`UKI_CONFIG_FILE`
9995 When inheriting the :ref:`ref-classes-uki` class, an optional config
9996 file for the `ukify
9997 <https://www.freedesktop.org/software/systemd/man/latest/ukify.html>`__
9998 command.
9999
10000 :term:`UKI_FILENAME`
10001 When inheriting the :ref:`ref-classes-uki` class, the output file name
10002 for the generated `Unified Kernel Image (UKI)
10003 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
10004 Defaults to ``uki.efi``.
10005
10006 :term:`UKI_KERNEL_FILENAME`
10007 When inheriting the :ref:`ref-classes-uki` class, the kernel image file
10008 name to use as input. Defaults to :term:`KERNEL_IMAGETYPE`.
10009
10010 :term:`UKI_SB_CERT`
10011 When inheriting the :ref:`ref-classes-uki` class, optional UEFI
10012 secureboot certificate matching the private key in :term:`UKI_SB_KEY`.
10013
10014 :term:`UKI_SB_KEY`
10015 When inheriting the :ref:`ref-classes-uki` class, optional UEFI
10016 secureboot private key to sign the `Unified Kernel Image (UKI)
10017 <https://uapi-group.org/specifications/specs/unified_kernel_image/>`__.
10018
Andrew Geissler9aee5002022-03-30 16:27:02 +000010019 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010020 Specifies a list of options that, if reported by the configure script
10021 as being invalid, should not generate a warning during the
10022 :ref:`ref-tasks-configure` task. Normally, invalid
10023 configure options are simply not passed to the configure script (e.g.
10024 should be removed from :term:`EXTRA_OECONF` or
10025 :term:`PACKAGECONFIG_CONFARGS`).
William A. Kennington IIIac69b482021-06-02 12:28:27 -070010026 However, there are common options that are passed to all
10027 configure scripts at a class level, but might not be valid for some
10028 configure scripts. Therefore warnings about these options are useless.
Andrew Geissler9aee5002022-03-30 16:27:02 +000010029 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010030
10031 The configure arguments check that uses
Andrew Geissler9aee5002022-03-30 16:27:02 +000010032 :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the
Andrew Geissler517393d2023-01-13 08:55:19 -060010033 :ref:`ref-classes-insane` class and is only enabled if the
10034 recipe inherits the :ref:`ref-classes-autotools` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010035
Andrew Geissleredff4922024-06-19 14:12:16 -040010036 :term:`UNPACKDIR`
10037 This variable, used by the :ref:`ref-classes-base` class,
10038 specifies where fetches sources should be unpacked by the
10039 :ref:`ref-tasks-unpack` task.
10040
Andrew Geisslerf0343792020-11-18 10:42:21 -060010041 :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010042 For recipes inheriting the
Andrew Geissler517393d2023-01-13 08:55:19 -060010043 :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010044 specifies the package that contains the initscript that is enabled.
10045
10046 The default value is "${PN}". Given that almost all recipes that
10047 install initscripts package them in the main package for the recipe,
10048 you rarely need to set this variable in individual recipes.
10049
Andrew Geissler5199d832021-09-24 16:47:35 -050010050 :term:`UPSTREAM_CHECK_COMMITS`
10051 You can perform a per-recipe check for what the latest upstream
10052 source code version is by calling ``devtool latest-version recipe``. If
10053 the recipe source code is provided from Git repositories, but
10054 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS`
10055 to ``1`` in the recipe, and the OpenEmbedded build system
10056 will compare the latest commit with the one currently specified
Andrew Geissler517393d2023-01-13 08:55:19 -060010057 by the recipe (:term:`SRCREV`)::
Andrew Geissler5199d832021-09-24 16:47:35 -050010058
10059 UPSTREAM_CHECK_COMMITS = "1"
10060
Andrew Geisslerf0343792020-11-18 10:42:21 -060010061 :term:`UPSTREAM_CHECK_GITTAGREGEX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010062 You can perform a per-recipe check for what the latest upstream
Andrew Geissler5199d832021-09-24 16:47:35 -050010063 source code version is by calling ``devtool latest-version recipe``. If
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010064 the recipe source code is provided from Git repositories, the
10065 OpenEmbedded build system determines the latest upstream version by
10066 picking the latest tag from the list of all repository tags.
10067
Andrew Geissler09036742021-06-25 14:25:14 -050010068 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010069 regular expression to filter only the relevant tags should the
Andrew Geissler517393d2023-01-13 08:55:19 -060010070 default filter not work correctly::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010071
10072 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
10073
Andrew Geisslerf0343792020-11-18 10:42:21 -060010074 :term:`UPSTREAM_CHECK_REGEX`
Andrew Geissler09036742021-06-25 14:25:14 -050010075 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010076 regular expression instead of the default one when the package
10077 checking system is parsing the page found using
Andrew Geissler517393d2023-01-13 08:55:19 -060010078 :term:`UPSTREAM_CHECK_URI`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010079
10080 UPSTREAM_CHECK_REGEX = "package_regex"
10081
Andrew Geisslerf0343792020-11-18 10:42:21 -060010082 :term:`UPSTREAM_CHECK_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010083 You can perform a per-recipe check for what the latest upstream
Andrew Geissler5199d832021-09-24 16:47:35 -050010084 source code version is by calling ``devtool latest-version recipe``. If
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010085 the source code is provided from tarballs, the latest version is
10086 determined by fetching the directory listing where the tarball is and
10087 attempting to find a later tarball. When this approach does not work,
Andrew Geissler09036742021-06-25 14:25:14 -050010088 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
Andrew Geissler517393d2023-01-13 08:55:19 -060010089 contains the link to the latest tarball::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010090
10091 UPSTREAM_CHECK_URI = "recipe_url"
10092
Andrew Geissler5199d832021-09-24 16:47:35 -050010093 :term:`UPSTREAM_VERSION_UNKNOWN`
10094 You can perform a per-recipe check for what the latest upstream
10095 source code version is by calling ``devtool latest-version recipe``.
10096 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`,
10097 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
10098 the recipe allows to determine what the latest upstream version is,
10099 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe
Andrew Geissler517393d2023-01-13 08:55:19 -060010100 to acknowledge that the check cannot be performed::
Andrew Geissler5199d832021-09-24 16:47:35 -050010101
10102 UPSTREAM_VERSION_UNKNOWN = "1"
10103
Andrew Geisslerf0343792020-11-18 10:42:21 -060010104 :term:`USE_DEVFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010105 Determines if ``devtmpfs`` is used for ``/dev`` population. The
Andrew Geissler09036742021-06-25 14:25:14 -050010106 default value used for :term:`USE_DEVFS` is "1" when no value is
10107 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010108 statically populated ``/dev`` directory.
10109
Andrew Geissler517393d2023-01-13 08:55:19 -060010110 See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010111 the Yocto Project Development Tasks Manual for information on how to
10112 use this variable.
10113
Andrew Geisslerf0343792020-11-18 10:42:21 -060010114 :term:`USE_VT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010115 When using
Andrew Geissler517393d2023-01-13 08:55:19 -060010116 :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`,
Patrick Williams8e7b46e2023-05-01 14:19:06 -050010117 determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>`
10118 on any virtual terminals in order to enable logging in through those
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010119 terminals.
10120
Andrew Geissler09036742021-06-25 14:25:14 -050010121 The default value used for :term:`USE_VT` is "1" when no default value is
10122 specifically set. Typically, you would set :term:`USE_VT` to "0" in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010123 machine configuration file for machines that do not have a graphical
10124 display attached and therefore do not need virtual terminal
10125 functionality.
10126
Andrew Geisslerf0343792020-11-18 10:42:21 -060010127 :term:`USER_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010128 A list of classes to globally inherit. These classes are used by the
Andrew Geissler9aee5002022-03-30 16:27:02 +000010129 OpenEmbedded build system to enable extra features.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010130
Patrick Williams975a06f2022-10-21 14:42:47 -050010131 Classes inherited using :term:`USER_CLASSES` must be located in the
10132 ``classes-global/`` or ``classes/`` subdirectories.
10133
Andrew Geisslerc926e172021-05-07 16:11:35 -050010134 The default list is set in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010135
Andrew Geissler9aee5002022-03-30 16:27:02 +000010136 USER_CLASSES ?= "buildstats"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010137
10138 For more information, see
Andrew Geissler87f5cff2022-09-30 13:13:31 -050010139 ``meta-poky/conf/templates/default/local.conf.sample`` in the
10140 :term:`Source Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010141
Andrew Geissleredff4922024-06-19 14:12:16 -040010142 :term:`USERADD_DEPENDS`
10143 Specifies a list of recipes that create users / groups (via
10144 :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe
10145 depends upon. This ensures that those users / groups are available
10146 when building a recipe.
10147
Andrew Geisslerf0343792020-11-18 10:42:21 -060010148 :term:`USERADD_ERROR_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010149 If set to ``error``, forces the OpenEmbedded build system to produce
10150 an error if the user identification (``uid``) and group
10151 identification (``gid``) values are not defined in any of the files
10152 listed in :term:`USERADD_UID_TABLES` and
10153 :term:`USERADD_GID_TABLES`. If set to
10154 ``warn``, a warning will be issued instead.
10155
10156 The default behavior for the build system is to dynamically apply
10157 ``uid`` and ``gid`` values. Consequently, the
Andrew Geissler09036742021-06-25 14:25:14 -050010158 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010159 on using statically assigned ``gid`` and ``uid`` values, you should
Andrew Geissler09036742021-06-25 14:25:14 -050010160 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -050010161 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010162
10163 USERADD_ERROR_DYNAMIC = "error"
10164
10165 Overriding the
10166 default behavior implies you are going to also take steps to set
10167 static ``uid`` and ``gid`` values through use of the
10168 :term:`USERADDEXTENSION`,
10169 :term:`USERADD_UID_TABLES`, and
10170 :term:`USERADD_GID_TABLES` variables.
10171
10172 .. note::
10173
10174 There is a difference in behavior between setting
Andrew Geissler09036742021-06-25 14:25:14 -050010175 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``.
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010176 When it is set to ``warn``, the build system will report a warning for
10177 every undefined ``uid`` and ``gid`` in any recipe. But when it is set
10178 to ``error``, it will only report errors for recipes that are actually
10179 built.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010180 This saves you from having to add static IDs for recipes that you
10181 know will never be built.
10182
Andrew Geisslerf0343792020-11-18 10:42:21 -060010183 :term:`USERADD_GID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010184 Specifies a password file to use for obtaining static group
10185 identification (``gid``) values when the OpenEmbedded build system
10186 adds a group to the system during package installation.
10187
10188 When applying static group identification (``gid``) values, the
10189 OpenEmbedded build system looks in :term:`BBPATH` for a
10190 ``files/group`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -050010191 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010192
10193
10194 USERADD_GID_TABLES = "files/group"
10195
10196 .. note::
10197
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010198 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
10199 causes the build system to use static ``gid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010200
Andrew Geisslerf0343792020-11-18 10:42:21 -060010201 :term:`USERADD_PACKAGES`
Andrew Geissler517393d2023-01-13 08:55:19 -060010202 When inheriting the :ref:`ref-classes-useradd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010203 this variable specifies the individual packages within the recipe
10204 that require users and/or groups to be added.
10205
10206 You must set this variable if the recipe inherits the class. For
10207 example, the following enables adding a user for the main package in
Andrew Geisslerc926e172021-05-07 16:11:35 -050010208 a recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010209
10210 USERADD_PACKAGES = "${PN}"
10211
10212 .. note::
10213
Andrew Geissler09036742021-06-25 14:25:14 -050010214 It follows that if you are going to use the :term:`USERADD_PACKAGES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010215 variable, you need to set one or more of the :term:`USERADD_PARAM`,
10216 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010217
Andrew Geisslerf0343792020-11-18 10:42:21 -060010218 :term:`USERADD_PARAM`
Andrew Geissler517393d2023-01-13 08:55:19 -060010219 When inheriting the :ref:`ref-classes-useradd` class,
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010220 this variable specifies for a package what parameters should pass to
10221 the ``useradd`` command if you add a user to the system when the
10222 package is installed.
10223
Andrew Geisslerc926e172021-05-07 16:11:35 -050010224 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010225
Patrick Williams0ca19cc2021-08-16 14:03:13 -050010226 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010227 --no-create-home --shell /bin/false \
10228 --user-group messagebus"
10229
10230 For information on the
10231 standard Linux shell command ``useradd``, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -060010232 https://linux.die.net/man/8/useradd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010233
Andrew Geisslerf0343792020-11-18 10:42:21 -060010234 :term:`USERADD_UID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010235 Specifies a password file to use for obtaining static user
10236 identification (``uid``) values when the OpenEmbedded build system
10237 adds a user to the system during package installation.
10238
10239 When applying static user identification (``uid``) values, the
10240 OpenEmbedded build system looks in :term:`BBPATH` for a
10241 ``files/passwd`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -050010242 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010243
10244 USERADD_UID_TABLES = "files/passwd"
10245
10246 .. note::
10247
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010248 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
10249 causes the build system to use static ``uid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010250
Andrew Geisslerf0343792020-11-18 10:42:21 -060010251 :term:`USERADDEXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010252 When set to "useradd-staticids", causes the OpenEmbedded build system
10253 to base all user and group additions on a static ``passwd`` and
10254 ``group`` files found in :term:`BBPATH`.
10255
10256 To use static user identification (``uid``) and group identification
10257 (``gid``) values, set the variable as follows in your ``local.conf``
10258 file: USERADDEXTENSION = "useradd-staticids"
10259
10260 .. note::
10261
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010262 Setting this variable to use static ``uid`` and ``gid``
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010263 values causes the OpenEmbedded build system to employ the
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010264 :ref:`ref-classes-useradd` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010265
10266 If you use static ``uid`` and ``gid`` information, you must also
10267 specify the ``files/passwd`` and ``files/group`` files by setting the
10268 :term:`USERADD_UID_TABLES` and
10269 :term:`USERADD_GID_TABLES` variables.
10270 Additionally, you should also set the
10271 :term:`USERADD_ERROR_DYNAMIC` variable.
10272
Patrick Williamsb58112e2024-03-07 11:16:36 -060010273 :term:`VIRTUAL-RUNTIME`
10274 :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual
10275 packages for runtime usage, typically for use in :term:`RDEPENDS`
10276 or in image definitions.
10277
10278 An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible
10279 to either use BusyBox based utilities::
10280
10281 VIRTUAL-RUNTIME_base-utils = "busybox"
10282
10283 or their full featured implementations from GNU Coreutils
10284 and other projects::
10285
10286 VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils"
10287
10288 Here are two examples using this virtual runtime package. The
10289 first one is in :yocto_git:`initramfs-framework_1.0.bb
10290 </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`::
10291
10292 RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}"
10293
10294 The second example is in the :yocto_git:`core-image-initramfs-boot
10295 </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>`
10296 image definition::
10297
10298 PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd"
10299
Andrew Geisslerf0343792020-11-18 10:42:21 -060010300 :term:`WARN_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010301 Specifies the quality assurance checks whose failures are reported as
10302 warnings by the OpenEmbedded build system. You set this variable in
10303 your distribution configuration file. For a list of the checks you
10304 can control with this variable, see the
Andrew Geissler595f6302022-01-24 19:11:47 +000010305 ":ref:`ref-classes-insane`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010306
Patrick Williams975a06f2022-10-21 14:42:47 -050010307 :term:`WATCHDOG_TIMEOUT`
10308 Specifies the timeout in seconds used by the ``watchdog`` recipe and
10309 also by ``systemd`` during reboot. The default is 60 seconds.
10310
Patrick Williams96e4b4e2025-02-03 15:49:15 -050010311 :term:`WIC_SECTOR_SIZE`
10312 The variable :term:`WIC_SECTOR_SIZE` controls the sector size of Wic
10313 images. In the background, this controls the value of the
10314 ``PARTED_SECTOR_SIZE`` environment variable passed to the ``parted``
10315 command-line utility, used to generated the images. The default value is
10316 ``512``.
10317
10318 For more information on how to create Wic images, see the
10319 ":ref:`dev-manual/wic:creating partitioned images using wic`" section in
10320 the Yocto Project Development Tasks Manual.
10321
Patrick Williams975a06f2022-10-21 14:42:47 -050010322 :term:`WIRELESS_DAEMON`
10323 For ``connman`` and ``packagegroup-base``, specifies the wireless
10324 daemon to use. The default is "wpa-supplicant" (note that the value
10325 uses a dash and not an underscore).
10326
Andrew Geisslerf0343792020-11-18 10:42:21 -060010327 :term:`WKS_FILE`
10328 Specifies the location of the Wic kickstart file that is used by the
10329 OpenEmbedded build system to create a partitioned image
Andrew Geisslereff27472021-10-29 15:35:00 -050010330 (``image.wic``). For information on how to create a partitioned
Andrew Geisslerf0343792020-11-18 10:42:21 -060010331 image, see the
Andrew Geissler517393d2023-01-13 08:55:19 -060010332 ":ref:`dev-manual/wic:creating partitioned images using wic`"
Andrew Geisslerf0343792020-11-18 10:42:21 -060010333 section in the Yocto Project Development Tasks Manual. For details on
Andrew Geissler09209ee2020-12-13 08:44:15 -060010334 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter.
Andrew Geisslerf0343792020-11-18 10:42:21 -060010335
10336 :term:`WKS_FILE_DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010337 When placed in the recipe that builds your image, this variable lists
Andrew Geissler09036742021-06-25 14:25:14 -050010338 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010339 applicable when Wic images are active (i.e. when
10340 :term:`IMAGE_FSTYPES` contains entries related
10341 to Wic). If your recipe does not create Wic images, the variable has
10342 no effect.
10343
Andrew Geissler09036742021-06-25 14:25:14 -050010344 The :term:`WKS_FILE_DEPENDS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010345 :term:`DEPENDS` variable. When you use the variable in
10346 your recipe that builds the Wic image, dependencies you list in the
Andrew Geissler09036742021-06-25 14:25:14 -050010347 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010348
Andrew Geissler09036742021-06-25 14:25:14 -050010349 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010350 specify a list of additional dependencies (e.g. native tools,
10351 bootloaders, and so forth), that are required to build Wic images.
Patrick Williams39653562024-03-01 08:54:02 -060010352 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010353
10354 WKS_FILE_DEPENDS = "some-native-tool"
10355
10356 In the
10357 previous example, some-native-tool would be replaced with an actual
10358 native tool on which the build would depend.
10359
Andrew Geisslerd5838332022-05-27 11:33:10 -050010360 :term:`WKS_FILES`
10361 Specifies a list of candidate Wic kickstart files to be used by the
10362 OpenEmbedded build system to create a partitioned image. Only the
10363 first one that is found, from left to right, will be used.
10364
10365 This is only useful when there are multiple ``.wks`` files that can be
10366 used to produce an image. A typical case is when multiple layers are
10367 used for different hardware platforms, each supplying a different
10368 ``.wks`` file. In this case, you specify all possible ones through
10369 :term:`WKS_FILES`.
10370
10371 If only one ``.wks`` file is used, set :term:`WKS_FILE` instead.
10372
Andrew Geisslerf0343792020-11-18 10:42:21 -060010373 :term:`WORKDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010374 The pathname of the work directory in which the OpenEmbedded build
10375 system builds a recipe. This directory is located within the
10376 :term:`TMPDIR` directory structure and is specific to
10377 the recipe being built and the system for which it is being built.
10378
Andrew Geissler09036742021-06-25 14:25:14 -050010379 The :term:`WORKDIR` directory is defined as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010380
10381 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
10382
10383 The actual directory depends on several things:
10384
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010385 - :term:`TMPDIR`: The top-level build output directory
10386 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier
10387 - :term:`PN`: The recipe name
Andrew Geissler615f2f12022-07-15 14:00:58 -050010388 - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which
Andrew Geissler517393d2023-01-13 08:55:19 -060010389 is usually the case for most recipes, then :term:`EXTENDPE` is blank.
Andrew Geissler4c19ea12020-10-27 13:52:24 -050010390 - :term:`PV`: The recipe version
10391 - :term:`PR`: The recipe revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010392
10393 As an example, assume a Source Directory top-level folder name
Patrick Williams2390b1b2022-11-03 13:47:49 -050010394 ``poky``, a default :term:`Build Directory` at ``poky/build``, and a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010395 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
10396 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
10397 directory the build system uses to build the package would be as
Andrew Geisslerc926e172021-05-07 16:11:35 -050010398 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010399
10400 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
10401
Andrew Geisslerf0343792020-11-18 10:42:21 -060010402 :term:`XSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010403 Specifies the packages that should be installed to provide an X
10404 server and drivers for the current machine, assuming your image
10405 directly includes ``packagegroup-core-x11-xserver`` or, perhaps
10406 indirectly, includes "x11-base" in
10407 :term:`IMAGE_FEATURES`.
10408
Andrew Geissler09036742021-06-25 14:25:14 -050010409 The default value of :term:`XSERVER`, if not specified in the machine
Andrew Geisslerc9f78652020-09-18 14:11:35 -050010410 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
Patrick Williams03907ee2022-05-01 06:28:52 -050010411
10412 :term:`XZ_THREADS`
10413 Specifies the number of parallel threads that should be used when
10414 using xz compression.
10415
10416 By default this scales with core count, but is never set less than 2
10417 to ensure that multi-threaded mode is always used so that the output
10418 file contents are deterministic. Builds will work with a value of 1
10419 but the output will differ compared to the output from the compression
10420 generated when more than one thread is used.
10421
10422 On systems where many tasks run in parallel, setting a limit to this
10423 can be helpful in controlling system resource usage.
10424
Andrew Geissler517393d2023-01-13 08:55:19 -060010425 :term:`XZ_MEMLIMIT`
Patrick Williams03907ee2022-05-01 06:28:52 -050010426 Specifies the maximum memory the xz compression should use as a percentage
10427 of system memory. If unconstrained the xz compressor can use large amounts of
10428 memory and become problematic with parallelism elsewhere in the build.
10429 "50%" has been found to be a good value.
10430
Patrick Williams84603582024-12-14 08:00:57 -050010431 :term:`ZSTD_COMPRESSION_LEVEL`
10432 Specifies the compression level to be used with ZStandard compression
10433 (from ``1`` to ``19``, set to ``3`` by default, following upstream choice).
10434 Higher levels produce smaller files, but take longer to complete.
10435
Patrick Williams03907ee2022-05-01 06:28:52 -050010436 :term:`ZSTD_THREADS`
10437 Specifies the number of parallel threads that should be used when
10438 using ZStandard compression.
10439
10440 By default this scales with core count, but is never set less than 2
10441 to ensure that multi-threaded mode is always used so that the output
10442 file contents are deterministic. Builds will work with a value of 1
10443 but the output will differ compared to the output from the compression
10444 generated when more than one thread is used.
10445
10446 On systems where many tasks run in parallel, setting a limit to this
10447 can be helpful in controlling system resource usage.