blob: d5ac1926b6eeaf488b05b18a314e3624fe6bf3a1 [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>`
11:term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FEATURE_PACKAGES>`
12:term:`G <GCCPIE>` :term:`H <HOMEPAGE>` :term:`I <ICECC_DISABLED>`
13:term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>`
14:term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P`
15:term:`R <RANLIB>` :term:`S` :term:`T`
16:term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>`
17:term:`W <WARN_QA>` :term:`X <XSERVER>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050018
19.. glossary::
20
Andrew Geisslerf0343792020-11-18 10:42:21 -060021 :term:`ABIEXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050022 Extension to the Application Binary Interface (ABI) field of the GNU
23 canonical architecture name (e.g. "eabi").
24
25 ABI extensions are set in the machine include files. For example, the
26 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
Andrew Geisslerc926e172021-05-07 16:11:35 -050027 following extension::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050028
29 ABIEXTENSION = "eabi"
30
Andrew Geisslerf0343792020-11-18 10:42:21 -060031 :term:`ALLOW_EMPTY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050032 Specifies whether to produce an output package even if it is empty.
33 By default, BitBake does not produce empty packages. This default
34 behavior can cause issues when there is an
35 :term:`RDEPENDS` or some other hard runtime
36 requirement on the existence of the package.
37
38 Like all package-controlling variables, you must always use them in
Andrew Geisslerc926e172021-05-07 16:11:35 -050039 conjunction with a package name override, as in::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050040
Patrick Williams0ca19cc2021-08-16 14:03:13 -050041 ALLOW_EMPTY:${PN} = "1"
42 ALLOW_EMPTY:${PN}-dev = "1"
43 ALLOW_EMPTY:${PN}-staticdev = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050044
Andrew Geisslerf0343792020-11-18 10:42:21 -060045 :term:`ALTERNATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050046 Lists commands in a package that need an alternative binary naming
47 scheme. Sometimes the same command is provided in multiple packages.
48 When this occurs, the OpenEmbedded build system needs to use the
49 alternatives system to create a different binary naming scheme so the
50 commands can co-exist.
51
William A. Kennington IIIac69b482021-06-02 12:28:27 -070052 To use the variable, list out the package's commands that are also
53 provided by another package. For example, if the ``busybox`` package
54 has four such commands, you identify them as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050055
Patrick Williams0ca19cc2021-08-16 14:03:13 -050056 ALTERNATIVE:busybox = "sh sed test bracket"
Andrew Geisslerc9f78652020-09-18 14:11:35 -050057
58 For more information on the alternatives system, see the
59 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
60 section.
61
Andrew Geisslerf0343792020-11-18 10:42:21 -060062 :term:`ALTERNATIVE_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050063 Used by the alternatives system to map duplicated commands to actual
64 locations. For example, if the ``bracket`` command provided by the
65 ``busybox`` package is duplicated through another package, you must
Andrew Geissler09036742021-06-25 14:25:14 -050066 use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual
Andrew Geisslerc926e172021-05-07 16:11:35 -050067 location::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050068
69 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
70
71 In this example, the binary for the ``bracket`` command (i.e. ``[``)
72 from the ``busybox`` package resides in ``/usr/bin/``.
73
74 .. note::
75
Andrew Geissler09036742021-06-25 14:25:14 -050076 If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -050077
78 For more information on the alternatives system, see the
79 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
80 section.
81
Andrew Geisslerf0343792020-11-18 10:42:21 -060082 :term:`ALTERNATIVE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050083 Used by the alternatives system to create default priorities for
84 duplicated commands. You can use the variable to create a single
85 default regardless of the command name or package, a default for
86 specific duplicated commands regardless of the package, or a default
87 for specific commands tied to particular packages. Here are the
Andrew Geisslerc926e172021-05-07 16:11:35 -050088 available syntax forms::
Andrew Geisslerc9f78652020-09-18 14:11:35 -050089
90 ALTERNATIVE_PRIORITY = "priority"
91 ALTERNATIVE_PRIORITY[name] = "priority"
92 ALTERNATIVE_PRIORITY_pkg[name] = "priority"
93
94 For more information on the alternatives system, see the
95 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
96 section.
97
Andrew Geisslerf0343792020-11-18 10:42:21 -060098 :term:`ALTERNATIVE_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -050099 Used by the alternatives system to create default link locations for
100 duplicated commands. You can use the variable to create a single
101 default location for all duplicated commands regardless of the
102 command name or package, a default for specific duplicated commands
103 regardless of the package, or a default for specific commands tied to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500104 particular packages. Here are the available syntax forms::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500105
106 ALTERNATIVE_TARGET = "target"
107 ALTERNATIVE_TARGET[name] = "target"
108 ALTERNATIVE_TARGET_pkg[name] = "target"
109
110 .. note::
111
Andrew Geissler09036742021-06-25 14:25:14 -0500112 If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500113 from the :term:`ALTERNATIVE_LINK_NAME` variable.
114
Andrew Geissler09036742021-06-25 14:25:14 -0500115 If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the
116 same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500117 appended to it.
118
119 Finally, if the file referenced has not been renamed, the
120 alternatives system will rename it to avoid the need to rename
121 alternative files in the :ref:`ref-tasks-install`
122 task while retaining support for the command if necessary.
123
124 For more information on the alternatives system, see the
125 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
126 section.
127
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600128 :term:`ANY_OF_DISTRO_FEATURES`
129 When inheriting the
130 :ref:`features_check <ref-classes-features_check>`
131 class, this variable identifies a list of distribution features where
132 at least one must be enabled in the current configuration in order
133 for the OpenEmbedded build system to build the recipe. In other words,
Andrew Geissler09036742021-06-25 14:25:14 -0500134 if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES`
135 appear in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -0600136 the recipe will be skipped, and if the build system attempts to build
137 the recipe then an error will be triggered.
138
139
Andrew Geisslerf0343792020-11-18 10:42:21 -0600140 :term:`APPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500141 An override list of append strings for each target specified with
142 :term:`LABELS`.
143
144 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
145 information on how this variable is used.
146
Andrew Geisslerf0343792020-11-18 10:42:21 -0600147 :term:`AR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500148 The minimal command and arguments used to run ``ar``.
149
Andrew Geisslerf0343792020-11-18 10:42:21 -0600150 :term:`ARCHIVER_MODE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500151 When used with the :ref:`archiver <ref-classes-archiver>` class,
152 determines the type of information used to create a released archive.
153 You can use this variable to create archives of patched source,
154 original source, configured source, and so forth by employing the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500155 following variable flags (varflags)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500156
157 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
158 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
159 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
160 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
161 ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
162 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
163 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
164 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
165
166 For information on how the variable works, see the
167 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
168
Andrew Geisslerf0343792020-11-18 10:42:21 -0600169 :term:`AS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500170 Minimal command and arguments needed to run the assembler.
171
Andrew Geisslerf0343792020-11-18 10:42:21 -0600172 :term:`ASSUME_PROVIDED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500173 Lists recipe names (:term:`PN` values) BitBake does not
174 attempt to build. Instead, BitBake assumes these recipes have already
175 been built.
176
Andrew Geissler09036742021-06-25 14:25:14 -0500177 In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500178 tools that should not be built. An example is ``git-native``, which
179 when specified, allows for the Git binary from the host to be used
180 rather than building ``git-native``.
181
Andrew Geisslerf0343792020-11-18 10:42:21 -0600182 :term:`ASSUME_SHLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500183 Provides additional ``shlibs`` provider mapping information, which
184 adds to or overwrites the information provided automatically by the
185 system. Separate multiple entries using spaces.
186
187 As an example, use the following form to add an ``shlib`` provider of
Andrew Geisslerc926e172021-05-07 16:11:35 -0500188 shlibname in packagename with the optional version::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500189
190 shlibname:packagename[_version]
191
192 Here is an example that adds a shared library named ``libEGL.so.1``
Andrew Geisslerc926e172021-05-07 16:11:35 -0500193 as being provided by the ``libegl-implementation`` package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500194
195 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
196
Andrew Geisslerf0343792020-11-18 10:42:21 -0600197 :term:`AUTHOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500198 The email address used to contact the original author or authors in
199 order to send patches and forward bugs.
200
Andrew Geisslerf0343792020-11-18 10:42:21 -0600201 :term:`AUTO_LIBNAME_PKGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500202 When the :ref:`debian <ref-classes-debian>` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -0500203 which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500204 packages should be checked for libraries and renamed according to
205 Debian library package naming.
206
207 The default value is "${PACKAGES}", which causes the debian class to
208 act on all packages that are explicitly generated by the recipe.
209
Andrew Geisslerf0343792020-11-18 10:42:21 -0600210 :term:`AUTO_SYSLINUXMENU`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500211 Enables creating an automatic menu for the syslinux bootloader. You
212 must set this variable in your recipe. The
213 :ref:`syslinux <ref-classes-syslinux>` class checks this variable.
214
Andrew Geisslerf0343792020-11-18 10:42:21 -0600215 :term:`AUTOREV`
Andrew Geissler09036742021-06-25 14:25:14 -0500216 When :term:`SRCREV` is set to the value of this variable, it specifies to
Andrew Geisslerc926e172021-05-07 16:11:35 -0500217 use the latest source revision in the repository. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500218
219 SRCREV = "${AUTOREV}"
220
221 If you use the previous statement to retrieve the latest version of
222 software, you need to be sure :term:`PV` contains
223 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you
224 have a kernel recipe that inherits the
225 :ref:`kernel <ref-classes-kernel>` class and you use the previous
226 statement. In this example, ``${SRCPV}`` does not automatically get
Andrew Geissler09036742021-06-25 14:25:14 -0500227 into :term:`PV`. Consequently, you need to change :term:`PV` in your recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500228 so that it does contain ``${SRCPV}``.
229
230 For more information see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600231 ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500232 section in the Yocto Project Development Tasks Manual.
233
Andrew Geisslerf0343792020-11-18 10:42:21 -0600234 :term:`AVAILABLE_LICENSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500235 List of licenses found in the directories specified by
236 :term:`COMMON_LICENSE_DIR` and
237 :term:`LICENSE_PATH`.
238
239 .. note::
240
Andrew Geissler09036742021-06-25 14:25:14 -0500241 It is assumed that all changes to :term:`COMMON_LICENSE_DIR` and
242 :term:`LICENSE_PATH` have been done before :term:`AVAILABLE_LICENSES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500243 is defined (in :ref:`ref-classes-license`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500244
Andrew Geisslerf0343792020-11-18 10:42:21 -0600245 :term:`AVAILTUNES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500246 The list of defined CPU and Application Binary Interface (ABI)
247 tunings (i.e. "tunes") available for use by the OpenEmbedded build
248 system.
249
250 The list simply presents the tunes that are available. Not all tunes
251 may be compatible with a particular machine configuration, or with
252 each other in a
Andrew Geissler09209ee2020-12-13 08:44:15 -0600253 :ref:`Multilib <dev-manual/common-tasks:combining multiple versions of library files into one image>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500254 configuration.
255
256 To add a tune to the list, be sure to append it with spaces using the
257 "+=" BitBake operator. Do not simply replace the list by using the
258 "=" operator. See the
Patrick Williams213cb262021-08-07 19:21:33 -0500259 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500260 User Manual for more information.
261
Andrew Geissler95ac1b82021-03-31 14:34:31 -0500262 :term:`AZ_SAS`
263 Azure Storage Shared Access Signature, when using the
264 :ref:`Azure Storage fetcher (az://) <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`
265 This variable can be defined to be used by the fetcher to authenticate
266 and gain access to non-public artifacts.
267 ::
268
269 AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>""
270
271 For more information see Microsoft's Azure Storage documentation at
272 https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview
273
Andrew Geisslerf0343792020-11-18 10:42:21 -0600274 :term:`B`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500275 The directory within the :term:`Build Directory` in
276 which the OpenEmbedded build system places generated objects during a
277 recipe's build process. By default, this directory is the same as the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500278 :term:`S` directory, which is defined as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500279
280 S = "${WORKDIR}/${BP}"
281
Andrew Geissler09036742021-06-25 14:25:14 -0500282 You can separate the (:term:`S`) directory and the directory pointed to
Andrew Geissler5f350902021-07-23 13:09:54 -0400283 by the :term:`B` variable. Most Autotools-based recipes support
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500284 separating these directories. The build system defaults to using
285 separate directories for ``gcc`` and some kernel recipes.
286
Andrew Geisslerf0343792020-11-18 10:42:21 -0600287 :term:`BAD_RECOMMENDATIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500288 Lists "recommended-only" packages to not install. Recommended-only
289 packages are packages installed only through the
290 :term:`RRECOMMENDS` variable. You can prevent any
291 of these "recommended" packages from being installed by listing them
Andrew Geissler09036742021-06-25 14:25:14 -0500292 with the :term:`BAD_RECOMMENDATIONS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500293
294 BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
295
296 You can set this variable globally in your ``local.conf`` file or you
297 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -0500298 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500299
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500300 BAD_RECOMMENDATIONS:pn-target_image = "package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500301
302 It is important to realize that if you choose to not install packages
303 using this variable and some other packages are dependent on them
304 (i.e. listed in a recipe's :term:`RDEPENDS`
305 variable), the OpenEmbedded build system ignores your request and
306 will install the packages to avoid dependency errors.
307
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700308 This variable is supported only when using the IPK and RPM
309 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500310
311 See the :term:`NO_RECOMMENDATIONS` and the
312 :term:`PACKAGE_EXCLUDE` variables for related
313 information.
314
Andrew Geisslerf0343792020-11-18 10:42:21 -0600315 :term:`BASE_LIB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500316 The library directory name for the CPU or Application Binary
Andrew Geissler09036742021-06-25 14:25:14 -0500317 Interface (ABI) tune. The :term:`BASE_LIB` applies only in the Multilib
Andrew Geissler09209ee2020-12-13 08:44:15 -0600318 context. See the ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500319 section in the Yocto Project Development Tasks Manual for information
320 on Multilib.
321
Andrew Geissler09036742021-06-25 14:25:14 -0500322 The :term:`BASE_LIB` variable is defined in the machine include files in
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500323 the :term:`Source Directory`. If Multilib is not
324 being used, the value defaults to "lib".
325
Andrew Geisslerf0343792020-11-18 10:42:21 -0600326 :term:`BASE_WORKDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500327 Points to the base of the work directory for all recipes. The default
328 value is "${TMPDIR}/work".
329
Andrew Geisslerf0343792020-11-18 10:42:21 -0600330 :term:`BB_ALLOWED_NETWORKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500331 Specifies a space-delimited list of hosts that the fetcher is allowed
332 to use to obtain the required source code. Following are
333 considerations surrounding this variable:
334
Andrew Geissler09036742021-06-25 14:25:14 -0500335 - This host list is only used if :term:`BB_NO_NETWORK` is either not set
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500336 or set to "0".
337
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700338 - There is limited support for wildcard matching against the beginning of
339 host names. For example, the following setting matches
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500340 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
341 ::
342
343 BB_ALLOWED_NETWORKS = "*.gnu.org"
344
345 .. note::
346
347 The use of the "``*``" character only works at the beginning of
348 a host name and it must be isolated from the remainder of the
349 host name. You cannot use the wildcard character in any other
350 location of the name or combined with the front part of the
351 name.
352
353 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
354 is not.
355
356 - Mirrors not in the host list are skipped and logged in debug.
357
358 - Attempts to access networks not in the host list cause a failure.
359
Andrew Geissler09036742021-06-25 14:25:14 -0500360 Using :term:`BB_ALLOWED_NETWORKS` in conjunction with
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500361 :term:`PREMIRRORS` is very useful. Adding the host
Andrew Geissler09036742021-06-25 14:25:14 -0500362 you want to use to :term:`PREMIRRORS` results in the source code being
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500363 fetched from an allowed location and avoids raising an error when a
364 host that is not allowed is in a :term:`SRC_URI`
365 statement. This is because the fetcher does not attempt to use the
Andrew Geissler09036742021-06-25 14:25:14 -0500366 host listed in :term:`SRC_URI` after a successful fetch from the
367 :term:`PREMIRRORS` occurs.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500368
Andrew Geisslerf0343792020-11-18 10:42:21 -0600369 :term:`BB_DANGLINGAPPENDS_WARNONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500370 Defines how BitBake handles situations where an append file
371 (``.bbappend``) has no corresponding recipe file (``.bb``). This
372 condition often occurs when layers get out of sync (e.g. ``oe-core``
373 bumps a recipe version and the old recipe no longer exists and the
374 other layer has not been updated to the new version of the recipe
375 yet).
376
377 The default fatal behavior is safest because it is the sane reaction
378 given something is out of sync. It is important to realize when your
379 changes are no longer being applied.
380
381 You can change the default behavior by setting this variable to "1",
382 "yes", or "true" in your ``local.conf`` file, which is located in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500383 :term:`Build Directory`: Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500384
385 BB_DANGLINGAPPENDS_WARNONLY = "1"
386
Andrew Geisslerf0343792020-11-18 10:42:21 -0600387 :term:`BB_DISKMON_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500388 Monitors disk space and available inodes during the build and allows
389 you to control the build based on these parameters.
390
391 Disk space monitoring is disabled by default. To enable monitoring,
Andrew Geissler09036742021-06-25 14:25:14 -0500392 add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500393 found in the :term:`Build Directory`. Use the
394 following form:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500395
396 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500397
398 BB_DISKMON_DIRS = "action,dir,threshold [...]"
399
400 where:
401
402 action is:
403 ABORT: Immediately abort the build when
404 a threshold is broken.
405 STOPTASKS: Stop the build after the currently
406 executing tasks have finished when
407 a threshold is broken.
408 WARN: Issue a warning but continue the
409 build when a threshold is broken.
410 Subsequent warnings are issued as
411 defined by the BB_DISKMON_WARNINTERVAL
412 variable, which must be defined in
413 the conf/local.conf file.
414
415 dir is:
416 Any directory you choose. You can specify one or
417 more directories to monitor by separating the
418 groupings with a space. If two directories are
419 on the same device, only the first directory
420 is monitored.
421
422 threshold is:
423 Either the minimum available disk space,
424 the minimum number of free inodes, or
425 both. You must specify at least one. To
426 omit one or the other, simply omit the value.
427 Specify the threshold using G, M, K for Gbytes,
428 Mbytes, and Kbytes, respectively. If you do
429 not specify G, M, or K, Kbytes is assumed by
430 default. Do not use GB, MB, or KB.
431
Andrew Geisslerc926e172021-05-07 16:11:35 -0500432 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500433
434 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
435 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
436 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
437
438 The first example works only if you also provide the
439 :term:`BB_DISKMON_WARNINTERVAL`
440 variable in the ``conf/local.conf``. This example causes the build
441 system to immediately abort when either the disk space in
442 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
443 below 100 Kbytes. Because two directories are provided with the
444 variable, the build system also issue a warning when the disk space
445 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
446 of free inodes drops below 100 Kbytes. Subsequent warnings are issued
Andrew Geissler09036742021-06-25 14:25:14 -0500447 during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500448 variable.
449
450 The second example stops the build after all currently executing
451 tasks complete when the minimum disk space in the ``${TMPDIR}``
452 directory drops below 1 Gbyte. No disk monitoring occurs for the free
453 inodes in this case.
454
455 The final example immediately aborts the build when the number of
456 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
457 disk space monitoring for the directory itself occurs in this case.
458
Andrew Geisslerf0343792020-11-18 10:42:21 -0600459 :term:`BB_DISKMON_WARNINTERVAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500460 Defines the disk space and free inode warning intervals. To set these
461 intervals, define the variable in your ``conf/local.conf`` file in
462 the :term:`Build Directory`.
463
Andrew Geissler09036742021-06-25 14:25:14 -0500464 If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500465 must also use the :term:`BB_DISKMON_DIRS`
466 variable and define its action as "WARN". During the build,
467 subsequent warnings are issued each time disk space or number of free
468 inodes further reduces by the respective interval.
469
Andrew Geissler09036742021-06-25 14:25:14 -0500470 If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you
471 do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk
Andrew Geisslerc926e172021-05-07 16:11:35 -0500472 monitoring interval defaults to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500473
474 BB_DISKMON_WARNINTERVAL = "50M,5K"
475
476 When specifying the variable in your configuration file, use the
477 following form:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500478
479 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500480
481 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"
482
483 where:
484
485 disk_space_interval is:
486 An interval of memory expressed in either
487 G, M, or K for Gbytes, Mbytes, or Kbytes,
488 respectively. You cannot use GB, MB, or KB.
489
490 disk_inode_interval is:
491 An interval of free inodes expressed in either
492 G, M, or K for Gbytes, Mbytes, or Kbytes,
493 respectively. You cannot use GB, MB, or KB.
494
Andrew Geisslerc926e172021-05-07 16:11:35 -0500495 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500496
497 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
498 BB_DISKMON_WARNINTERVAL = "50M,5K"
499
500 These variables cause the
501 OpenEmbedded build system to issue subsequent warnings each time the
502 available disk space further reduces by 50 Mbytes or the number of
503 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
504 directory. Subsequent warnings based on the interval occur each time
505 a respective interval is reached beyond the initial warning (i.e. 1
506 Gbytes and 100 Kbytes).
507
Andrew Geisslerf0343792020-11-18 10:42:21 -0600508 :term:`BB_GENERATE_MIRROR_TARBALLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500509 Causes tarballs of the source control repositories (e.g. Git
510 repositories), including metadata, to be placed in the
511 :term:`DL_DIR` directory.
512
513 For performance reasons, creating and placing tarballs of these
514 repositories is not the default action by the OpenEmbedded build
515 system.
516 ::
517
518 BB_GENERATE_MIRROR_TARBALLS = "1"
519
520 Set this variable in your
521 ``local.conf`` file in the :term:`Build Directory`.
522
523 Once you have the tarballs containing your source files, you can
Andrew Geissler09036742021-06-25 14:25:14 -0500524 clean up your :term:`DL_DIR` directory by deleting any Git or other
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500525 source control work directories.
526
Andrew Geisslerf0343792020-11-18 10:42:21 -0600527 :term:`BB_NUMBER_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500528 The maximum number of tasks BitBake should run in parallel at any one
529 time. The OpenEmbedded build system automatically configures this
530 variable to be equal to the number of cores on the build system. For
531 example, a system with a dual core processor that also uses
Andrew Geissler09036742021-06-25 14:25:14 -0500532 hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500533 to "4".
534
535 For single socket systems (i.e. one CPU), you should not have to
536 override this variable to gain optimal parallelism during builds.
537 However, if you have very large systems that employ multiple physical
Andrew Geissler09036742021-06-25 14:25:14 -0500538 CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500539 is not set higher than "20".
540
541 For more information on speeding up builds, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600542 ":ref:`dev-manual/common-tasks:speeding up a build`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500543 section in the Yocto Project Development Tasks Manual.
544
Andrew Geisslerf0343792020-11-18 10:42:21 -0600545 :term:`BB_SERVER_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500546 Specifies the time (in seconds) after which to unload the BitBake
Andrew Geissler09036742021-06-25 14:25:14 -0500547 server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500548 long the BitBake server stays resident between invocations.
549
550 For example, the following statement in your ``local.conf`` file
Andrew Geisslerc926e172021-05-07 16:11:35 -0500551 instructs the server to be unloaded after 20 seconds of inactivity::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500552
553 BB_SERVER_TIMEOUT = "20"
554
555 If you want the server to never be unloaded,
Andrew Geissler5f350902021-07-23 13:09:54 -0400556 set :term:`BB_SERVER_TIMEOUT` to "-1".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500557
Andrew Geisslerf0343792020-11-18 10:42:21 -0600558 :term:`BBCLASSEXTEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500559 Allows you to extend a recipe so that it builds variants of the
William A. Kennington IIIac69b482021-06-02 12:28:27 -0700560 software. There are common variants for recipes as "natives" like
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500561 ``quilt-native``, which is a copy of Quilt built to run on the build
562 system; "crosses" such as ``gcc-cross``, which is a compiler built to
563 run on the build machine but produces binaries that run on the target
564 :term:`MACHINE`; "nativesdk", which targets the SDK
Andrew Geissler09036742021-06-25 14:25:14 -0500565 machine instead of :term:`MACHINE`; and "mulitlibs" in the form
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500566 "``multilib:``\ multilib_name".
567
568 To build a different variant of the recipe with a minimal amount of
Andrew Geisslerc926e172021-05-07 16:11:35 -0500569 code, it usually is as simple as adding the following to your recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500570
571 BBCLASSEXTEND =+ "native nativesdk"
572 BBCLASSEXTEND =+ "multilib:multilib_name"
573
574 .. note::
575
Andrew Geissler09036742021-06-25 14:25:14 -0500576 Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500577 variants by rewriting variable values and applying overrides such
Patrick Williams0ca19cc2021-08-16 14:03:13 -0500578 as ``:class-native``. For example, to generate a native version of
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500579 a recipe, a :term:`DEPENDS` on "foo" is rewritten
Andrew Geissler5f350902021-07-23 13:09:54 -0400580 to a :term:`DEPENDS` on "foo-native".
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500581
Andrew Geissler09036742021-06-25 14:25:14 -0500582 Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500583 Parsing once adds some limitations. For example, it is not
584 possible to include a different file depending on the variant,
585 since ``include`` statements are processed when the recipe is
586 parsed.
587
Andrew Geisslerf0343792020-11-18 10:42:21 -0600588 :term:`BBFILE_COLLECTIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500589 Lists the names of configured layers. These names are used to find
590 the other ``BBFILE_*`` variables. Typically, each layer will append
591 its name to this variable in its ``conf/layer.conf`` file.
592
Andrew Geisslerf0343792020-11-18 10:42:21 -0600593 :term:`BBFILE_PATTERN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500594 Variable that expands to match files from
595 :term:`BBFILES` in a particular layer. This variable
596 is used in the ``conf/layer.conf`` file and must be suffixed with the
597 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
598
Andrew Geisslerf0343792020-11-18 10:42:21 -0600599 :term:`BBFILE_PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500600 Assigns the priority for recipe files in each layer.
601
602 This variable is useful in situations where the same recipe appears
603 in more than one layer. Setting this variable allows you to
604 prioritize a layer against other layers that contain the same recipe
605 - effectively letting you control the precedence for the multiple
606 layers. The precedence established through this variable stands
607 regardless of a recipe's version (:term:`PV` variable). For
Andrew Geissler09036742021-06-25 14:25:14 -0500608 example, a layer that has a recipe with a higher :term:`PV` value but for
609 which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500610 has a lower precedence.
611
Andrew Geissler09036742021-06-25 14:25:14 -0500612 A larger value for the :term:`BBFILE_PRIORITY` variable results in a
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500613 higher precedence. For example, the value 6 has a higher precedence
Andrew Geissler09036742021-06-25 14:25:14 -0500614 than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable
615 is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500616 for more information. The default priority, if unspecified for a
617 layer with no dependencies, is the lowest defined priority + 1 (or 1
618 if no priorities are defined).
619
620 .. tip::
621
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500622 You can use the command ``bitbake-layers show-layers``
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500623 to list all configured layers along with their priorities.
624
Andrew Geisslerf0343792020-11-18 10:42:21 -0600625 :term:`BBFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500626 A space-separated list of recipe files BitBake uses to build
627 software.
628
629 When specifying recipe files, you can pattern match using Python's
630 `glob <https://docs.python.org/3/library/glob.html>`_ syntax.
631 For details on the syntax, see the documentation by following the
632 previous link.
633
Andrew Geisslerf0343792020-11-18 10:42:21 -0600634 :term:`BBFILES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500635 Activates content when identified layers are present. You identify
636 the layers by the collections that the layers define.
637
Andrew Geissler09036742021-06-25 14:25:14 -0500638 Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500639 whose corresponding ``.bb`` file is in a layer that attempts to
640 modify other layers through ``.bbappend`` but does not want to
641 introduce a hard dependency on those other layers.
642
Andrew Geissler09036742021-06-25 14:25:14 -0500643 Use the following form for :term:`BBFILES_DYNAMIC`:
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500644 collection_name:filename_pattern The following example identifies two
Andrew Geisslerc926e172021-05-07 16:11:35 -0500645 collection names and two filename patterns::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500646
647 BBFILES_DYNAMIC += " \
648 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
649 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
650 "
651
652 This next example shows an error message that occurs because invalid
653 entries are found, which cause parsing to abort:
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500654
655 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500656
657 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
658 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
659 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
660
Andrew Geisslerf0343792020-11-18 10:42:21 -0600661 :term:`BBINCLUDELOGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500662 Variable that controls how BitBake displays logs on build failure.
663
Andrew Geisslerf0343792020-11-18 10:42:21 -0600664 :term:`BBINCLUDELOGS_LINES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500665 If :term:`BBINCLUDELOGS` is set, specifies the
666 maximum number of lines from the task log file to print when
Andrew Geissler09036742021-06-25 14:25:14 -0500667 reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500668 the entire log is printed.
669
Andrew Geisslerf0343792020-11-18 10:42:21 -0600670 :term:`BBLAYERS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500671 Lists the layers to enable during the build. This variable is defined
672 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
Andrew Geisslerc926e172021-05-07 16:11:35 -0500673 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500674
675 BBLAYERS = " \
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500676 /home/scottrif/poky/meta \
677 /home/scottrif/poky/meta-poky \
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500678 /home/scottrif/poky/meta-yocto-bsp \
679 /home/scottrif/poky/meta-mykernel \
680 "
681
682 This example enables four layers, one of which is a custom,
683 user-defined layer named ``meta-mykernel``.
684
Andrew Geisslerf0343792020-11-18 10:42:21 -0600685 :term:`BBMASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500686 Prevents BitBake from processing recipes and recipe append files.
687
Andrew Geissler09036742021-06-25 14:25:14 -0500688 You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500689 ``.bbappend`` files. BitBake ignores any recipe or recipe append
690 files that match any of the expressions. It is as if BitBake does not
691 see them at all. Consequently, matching files are not parsed or
692 otherwise used by BitBake.
693
694 The values you provide are passed to Python's regular expression
695 compiler. Consequently, the syntax follows Python's Regular
696 Expression (re) syntax. The expressions are compared against the full
697 paths to the files. For complete syntax information, see Python's
Andrew Geisslerc3d88e42020-10-02 09:45:00 -0500698 documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500699
700 The following example uses a complete regular expression to tell
701 BitBake to ignore all recipe and recipe append files in the
Andrew Geisslerc926e172021-05-07 16:11:35 -0500702 ``meta-ti/recipes-misc/`` directory::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500703
704 BBMASK = "meta-ti/recipes-misc/"
705
706 If you want to mask out multiple directories or recipes, you can
707 specify multiple regular expression fragments. This next example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500708 masks out multiple directories and individual recipes::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500709
710 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
711 BBMASK += "/meta-oe/recipes-support/"
712 BBMASK += "/meta-foo/.*/openldap"
713 BBMASK += "opencv.*\.bbappend"
714 BBMASK += "lzma"
715
716 .. note::
717
718 When specifying a directory name, use the trailing slash character
719 to ensure you match just that directory name.
720
Andrew Geisslerf0343792020-11-18 10:42:21 -0600721 :term:`BBMULTICONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500722 Specifies each additional separate configuration when you are
723 building targets with multiple configurations. Use this variable in
724 your ``conf/local.conf`` configuration file. Specify a
725 multiconfigname for each configuration file you are using. For
Andrew Geisslerc926e172021-05-07 16:11:35 -0500726 example, the following line specifies three configuration files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500727
728 BBMULTICONFIG = "configA configB configC"
729
730 Each configuration file you
731 use must reside in the :term:`Build Directory`
732 ``conf/multiconfig`` directory (e.g.
733 build_directory\ ``/conf/multiconfig/configA.conf``).
734
Andrew Geissler09036742021-06-25 14:25:14 -0500735 For information on how to use :term:`BBMULTICONFIG` in an environment
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500736 that supports building targets with multiple configurations, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600737 ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500738 section in the Yocto Project Development Tasks Manual.
739
Andrew Geisslerf0343792020-11-18 10:42:21 -0600740 :term:`BBPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500741 Used by BitBake to locate ``.bbclass`` and configuration files. This
742 variable is analogous to the ``PATH`` variable.
743
744 .. note::
745
746 If you run BitBake from a directory outside of the
Andrew Geissler09036742021-06-25 14:25:14 -0500747 :term:`Build Directory`, you must be sure to set :term:`BBPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500748 to point to the Build Directory. Set the variable as you would any
Andrew Geisslerc926e172021-05-07 16:11:35 -0500749 environment variable and then run BitBake::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500750
751 $ BBPATH = "build_directory"
752 $ export BBPATH
753 $ bitbake target
754
755
Andrew Geisslerf0343792020-11-18 10:42:21 -0600756 :term:`BBSERVER`
Andrew Geissler09036742021-06-25 14:25:14 -0500757 If defined in the BitBake environment, :term:`BBSERVER` points to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500758 BitBake remote server.
759
760 Use the following format to export the variable to the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -0500761 environment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500762
763 export BBSERVER=localhost:$port
764
Patrick Williams213cb262021-08-07 19:21:33 -0500765 By default, :term:`BBSERVER` also appears in :term:`BB_HASHBASE_WHITELIST`.
Andrew Geissler09036742021-06-25 14:25:14 -0500766 Consequently, :term:`BBSERVER` is excluded from checksum and dependency
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500767 data.
768
Andrew Geisslerf0343792020-11-18 10:42:21 -0600769 :term:`BINCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500770 When inheriting the
771 :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class,
772 this variable specifies binary configuration scripts to disable in
773 favor of using ``pkg-config`` to query the information. The
774 ``binconfig-disabled`` class will modify the specified scripts to
775 return an error so that calls to them can be easily found and
776 replaced.
777
778 To add multiple scripts, separate them by spaces. Here is an example
Andrew Geisslerc926e172021-05-07 16:11:35 -0500779 from the ``libpng`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500780
781 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
782
Andrew Geisslerf0343792020-11-18 10:42:21 -0600783 :term:`BINCONFIG_GLOB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500784 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
785 this variable specifies a wildcard for configuration scripts that
786 need editing. The scripts are edited to correct any paths that have
787 been set up during compilation so that they are correct for use when
788 installed into the sysroot and called by the build processes of other
789 recipes.
790
791 .. note::
792
Andrew Geissler09036742021-06-25 14:25:14 -0500793 The :term:`BINCONFIG_GLOB` variable uses
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500794 `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__,
795 which is recognition and expansion of wildcards during pattern
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500796 matching. Shell globbing is very similar to
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500797 `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__
798 and `glob <https://docs.python.org/3/library/glob.html>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500799
800 For more information on how this variable works, see
801 ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`.
802 You can also find general
803 information on the class in the
804 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
805
Andrew Geisslerf0343792020-11-18 10:42:21 -0600806 :term:`BP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500807 The base recipe name and version but without any special recipe name
Andrew Geissler09036742021-06-25 14:25:14 -0500808 suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is
Andrew Geisslerc926e172021-05-07 16:11:35 -0500809 comprised of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500810
811 ${BPN}-${PV}
812
Andrew Geisslerf0343792020-11-18 10:42:21 -0600813 :term:`BPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500814 This variable is a version of the :term:`PN` variable with
815 common prefixes and suffixes removed, such as ``nativesdk-``,
816 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``.
817 The exact lists of prefixes and suffixes removed are specified by the
818 :term:`MLPREFIX` and
819 :term:`SPECIAL_PKGSUFFIX` variables,
820 respectively.
821
Andrew Geisslerf0343792020-11-18 10:42:21 -0600822 :term:`BUGTRACKER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500823 Specifies a URL for an upstream bug tracking website for a recipe.
824 The OpenEmbedded build system does not use this variable. Rather, the
825 variable is a useful pointer in case a bug in the software being
826 built needs to be manually reported.
827
Andrew Geisslerf0343792020-11-18 10:42:21 -0600828 :term:`BUILD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500829 Specifies the architecture of the build host (e.g. ``i686``). The
Andrew Geissler09036742021-06-25 14:25:14 -0500830 OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500831 machine name reported by the ``uname`` command.
832
Andrew Geisslerf0343792020-11-18 10:42:21 -0600833 :term:`BUILD_AS_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500834 Specifies the architecture-specific assembler flags for the build
Andrew Geissler09036742021-06-25 14:25:14 -0500835 host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500836
Andrew Geisslerf0343792020-11-18 10:42:21 -0600837 :term:`BUILD_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500838 Specifies the architecture-specific C compiler flags for the build
Andrew Geissler09036742021-06-25 14:25:14 -0500839 host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500840
Andrew Geisslerf0343792020-11-18 10:42:21 -0600841 :term:`BUILD_CCLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500842 Specifies the linker command to be used for the build host when the C
Andrew Geissler09036742021-06-25 14:25:14 -0500843 compiler is being used as the linker. By default, :term:`BUILD_CCLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500844 points to GCC and passes as arguments the value of
845 :term:`BUILD_CC_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -0500846 :term:`BUILD_CC_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500847
Andrew Geisslerf0343792020-11-18 10:42:21 -0600848 :term:`BUILD_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500849 Specifies the flags to pass to the C compiler when building for the
850 build host. When building in the ``-native`` context,
851 :term:`CFLAGS` is set to the value of this variable by
852 default.
853
Andrew Geisslerf0343792020-11-18 10:42:21 -0600854 :term:`BUILD_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500855 Specifies the flags to pass to the C preprocessor (i.e. to both the C
856 and the C++ compilers) when building for the build host. When
857 building in the ``-native`` context, :term:`CPPFLAGS`
858 is set to the value of this variable by default.
859
Andrew Geisslerf0343792020-11-18 10:42:21 -0600860 :term:`BUILD_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500861 Specifies the flags to pass to the C++ compiler when building for the
862 build host. When building in the ``-native`` context,
863 :term:`CXXFLAGS` is set to the value of this variable
864 by default.
865
Andrew Geisslerf0343792020-11-18 10:42:21 -0600866 :term:`BUILD_FC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500867 Specifies the Fortran compiler command for the build host. By
Andrew Geissler09036742021-06-25 14:25:14 -0500868 default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500869 value of :term:`BUILD_CC_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -0500870 :term:`BUILD_CC_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500871
Andrew Geisslerf0343792020-11-18 10:42:21 -0600872 :term:`BUILD_LD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500873 Specifies the linker command for the build host. By default,
Andrew Geissler09036742021-06-25 14:25:14 -0500874 :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500875 the value of :term:`BUILD_LD_ARCH`, assuming
Andrew Geissler09036742021-06-25 14:25:14 -0500876 :term:`BUILD_LD_ARCH` is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500877
Andrew Geisslerf0343792020-11-18 10:42:21 -0600878 :term:`BUILD_LD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500879 Specifies architecture-specific linker flags for the build host. By
Andrew Geissler09036742021-06-25 14:25:14 -0500880 default, the value of :term:`BUILD_LD_ARCH` is empty.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500881
Andrew Geisslerf0343792020-11-18 10:42:21 -0600882 :term:`BUILD_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500883 Specifies the flags to pass to the linker when building for the build
884 host. When building in the ``-native`` context,
885 :term:`LDFLAGS` is set to the value of this variable
886 by default.
887
Andrew Geisslerf0343792020-11-18 10:42:21 -0600888 :term:`BUILD_OPTIMIZATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500889 Specifies the optimization flags passed to the C compiler when
890 building for the build host or the SDK. The flags are passed through
891 the :term:`BUILD_CFLAGS` and
892 :term:`BUILDSDK_CFLAGS` default values.
893
Andrew Geissler5f350902021-07-23 13:09:54 -0400894 The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500895 -pipe".
896
Andrew Geisslerf0343792020-11-18 10:42:21 -0600897 :term:`BUILD_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500898 Specifies the operating system in use on the build host (e.g.
899 "linux"). The OpenEmbedded build system sets the value of
Andrew Geissler5f350902021-07-23 13:09:54 -0400900 :term:`BUILD_OS` from the OS reported by the ``uname`` command - the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500901 first word, converted to lower-case characters.
902
Andrew Geisslerf0343792020-11-18 10:42:21 -0600903 :term:`BUILD_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500904 The toolchain binary prefix used for native recipes. The OpenEmbedded
Andrew Geissler09036742021-06-25 14:25:14 -0500905 build system uses the :term:`BUILD_PREFIX` value to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500906 :term:`TARGET_PREFIX` when building for
907 ``native`` recipes.
908
Andrew Geisslerf0343792020-11-18 10:42:21 -0600909 :term:`BUILD_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500910 Specifies the command to be used to strip debugging symbols from
Andrew Geissler09036742021-06-25 14:25:14 -0500911 binaries produced for the build host. By default, :term:`BUILD_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500912 points to
913 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
914
Andrew Geisslerf0343792020-11-18 10:42:21 -0600915 :term:`BUILD_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500916 Specifies the system, including the architecture and the operating
917 system, to use when building for the build host (i.e. when building
918 ``native`` recipes).
919
920 The OpenEmbedded build system automatically sets this variable based
921 on :term:`BUILD_ARCH`,
922 :term:`BUILD_VENDOR`, and
923 :term:`BUILD_OS`. You do not need to set the
Andrew Geissler09036742021-06-25 14:25:14 -0500924 :term:`BUILD_SYS` variable yourself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500925
Andrew Geisslerf0343792020-11-18 10:42:21 -0600926 :term:`BUILD_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500927 Specifies the vendor name to use when building for the build host.
928 The default value is an empty string ("").
929
Andrew Geisslerf0343792020-11-18 10:42:21 -0600930 :term:`BUILDDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500931 Points to the location of the :term:`Build Directory`.
932 You can define this directory indirectly through the
Andrew Geissler4c19ea12020-10-27 13:52:24 -0500933 :ref:`structure-core-script` script by passing in a Build
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500934 Directory path when you run the script. If you run the script and do
Andrew Geissler09036742021-06-25 14:25:14 -0500935 not provide a Build Directory path, the :term:`BUILDDIR` defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500936 ``build`` in the current directory.
937
Andrew Geisslerf0343792020-11-18 10:42:21 -0600938 :term:`BUILDHISTORY_COMMIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500939 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
940 class, this variable specifies whether or not to commit the build
941 history output in a local Git repository. If set to "1", this local
942 repository will be maintained automatically by the ``buildhistory``
943 class and a commit will be created on every build for changes to each
944 top-level subdirectory of the build history output (images, packages,
945 and sdk). If you want to track changes to build history over time,
946 you should set this value to "1".
947
948 By default, the ``buildhistory`` class does not commit the build
Andrew Geisslerc926e172021-05-07 16:11:35 -0500949 history output in a local Git repository::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500950
951 BUILDHISTORY_COMMIT ?= "0"
952
Andrew Geisslerf0343792020-11-18 10:42:21 -0600953 :term:`BUILDHISTORY_COMMIT_AUTHOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500954 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
955 class, this variable specifies the author to use for each Git commit.
Andrew Geissler09036742021-06-25 14:25:14 -0500956 In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500957 :term:`BUILDHISTORY_COMMIT` variable must
958 be set to "1".
959
960 Git requires that the value you provide for the
Andrew Geissler09036742021-06-25 14:25:14 -0500961 :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500962 email@host". Providing an email address or host that is not valid
963 does not produce an error.
964
Andrew Geisslerc926e172021-05-07 16:11:35 -0500965 By default, the ``buildhistory`` class sets the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500966
967 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
968
Andrew Geisslerf0343792020-11-18 10:42:21 -0600969 :term:`BUILDHISTORY_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500970 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
971 class, this variable specifies the directory in which build history
972 information is kept. For more information on how the variable works,
973 see the ``buildhistory.class``.
974
Andrew Geisslerc926e172021-05-07 16:11:35 -0500975 By default, the ``buildhistory`` class sets the directory as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500976
977 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
978
Andrew Geisslerf0343792020-11-18 10:42:21 -0600979 :term:`BUILDHISTORY_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500980 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
981 class, this variable specifies the build history features to be
982 enabled. For more information on how build history works, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -0600983 ":ref:`dev-manual/common-tasks:maintaining build output quality`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500984 section in the Yocto Project Development Tasks Manual.
985
986 You can specify these features in the form of a space-separated list:
987
988 - *image:* Analysis of the contents of images, which includes the
989 list of installed packages among other things.
990
991 - *package:* Analysis of the contents of individual packages.
992
993 - *sdk:* Analysis of the contents of the software development kit
994 (SDK).
995
996 - *task:* Save output file signatures for
Andrew Geissler09209ee2020-12-13 08:44:15 -0600997 :ref:`shared state <overview-manual/concepts:shared state cache>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500998 (sstate) tasks.
999 This saves one file per task and lists the SHA-256 checksums for
1000 each file staged (i.e. the output of the task).
1001
1002 By default, the ``buildhistory`` class enables the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001003 features::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001004
1005 BUILDHISTORY_FEATURES ?= "image package sdk"
1006
Andrew Geisslerf0343792020-11-18 10:42:21 -06001007 :term:`BUILDHISTORY_IMAGE_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001008 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
1009 class, this variable specifies a list of paths to files copied from
1010 the image contents into the build history directory under an
1011 "image-files" directory in the directory for the image, so that you
1012 can track the contents of each file. The default is to copy
1013 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for
1014 changes in user and group entries. You can modify the list to include
1015 any file. Specifying an invalid path does not produce an error.
1016 Consequently, you can include files that might not always be present.
1017
1018 By default, the ``buildhistory`` class provides paths to the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001019 following files::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001020
1021 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1022
Andrew Geissler5f350902021-07-23 13:09:54 -04001023 :term:`BUILDHISTORY_PATH_PREFIX_STRIP`
1024 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
1025 class, this variable specifies a common path prefix that should be
1026 stripped off the beginning of paths in the task signature list when the
1027 ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be
1028 useful when build history is populated from multiple sources that may not
1029 all use the same top level directory.
1030
1031 By default, the ``buildhistory`` class sets the variable as follows::
1032
1033 BUILDHISTORY_PATH_PREFIX_STRIP ?= ""
1034
1035 In this case, no prefixes will be stripped.
1036
Andrew Geisslerf0343792020-11-18 10:42:21 -06001037 :term:`BUILDHISTORY_PUSH_REPO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001038 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
1039 class, this variable optionally specifies a remote repository to
1040 which build history pushes Git changes. In order for
Andrew Geissler09036742021-06-25 14:25:14 -05001041 :term:`BUILDHISTORY_PUSH_REPO` to work,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001042 :term:`BUILDHISTORY_COMMIT` must be set to
1043 "1".
1044
1045 The repository should correspond to a remote address that specifies a
1046 repository as understood by Git, or alternatively to a remote name
1047 that you have set up manually using ``git remote`` within the local
1048 repository.
1049
Andrew Geisslerc926e172021-05-07 16:11:35 -05001050 By default, the ``buildhistory`` class sets the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001051
1052 BUILDHISTORY_PUSH_REPO ?= ""
1053
Andrew Geisslerf0343792020-11-18 10:42:21 -06001054 :term:`BUILDSDK_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001055 Specifies the flags to pass to the C compiler when building for the
1056 SDK. When building in the ``nativesdk-`` context,
1057 :term:`CFLAGS` is set to the value of this variable by
1058 default.
1059
Andrew Geisslerf0343792020-11-18 10:42:21 -06001060 :term:`BUILDSDK_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001061 Specifies the flags to pass to the C pre-processor (i.e. to both the
1062 C and the C++ compilers) when building for the SDK. When building in
1063 the ``nativesdk-`` context, :term:`CPPFLAGS` is set
1064 to the value of this variable by default.
1065
Andrew Geisslerf0343792020-11-18 10:42:21 -06001066 :term:`BUILDSDK_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001067 Specifies the flags to pass to the C++ compiler when building for the
1068 SDK. When building in the ``nativesdk-`` context,
1069 :term:`CXXFLAGS` is set to the value of this variable
1070 by default.
1071
Andrew Geisslerf0343792020-11-18 10:42:21 -06001072 :term:`BUILDSDK_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001073 Specifies the flags to pass to the linker when building for the SDK.
1074 When building in the ``nativesdk-`` context,
1075 :term:`LDFLAGS` is set to the value of this variable
1076 by default.
1077
Andrew Geisslerf0343792020-11-18 10:42:21 -06001078 :term:`BUILDSTATS_BASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001079 Points to the location of the directory that holds build statistics
1080 when you use and enable the
1081 :ref:`buildstats <ref-classes-buildstats>` class. The
Andrew Geissler09036742021-06-25 14:25:14 -05001082 :term:`BUILDSTATS_BASE` directory defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001083 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
1084
Andrew Geisslerf0343792020-11-18 10:42:21 -06001085 :term:`BUSYBOX_SPLIT_SUID`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001086 For the BusyBox recipe, specifies whether to split the output
1087 executable file into two parts: one for features that require
1088 ``setuid root``, and one for the remaining features (i.e. those that
1089 do not require ``setuid root``).
1090
Andrew Geissler09036742021-06-25 14:25:14 -05001091 The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001092 splitting the output executable file. Set the variable to "0" to get
1093 a single output executable file.
1094
Andrew Geisslerf0343792020-11-18 10:42:21 -06001095 :term:`CACHE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001096 Specifies the directory BitBake uses to store a cache of the
1097 :term:`Metadata` so it does not need to be parsed every time
1098 BitBake is started.
1099
Andrew Geisslerf0343792020-11-18 10:42:21 -06001100 :term:`CC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001101 The minimal command and arguments used to run the C compiler.
1102
Andrew Geisslerf0343792020-11-18 10:42:21 -06001103 :term:`CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001104 Specifies the flags to pass to the C compiler. This variable is
1105 exported to an environment variable and thus made visible to the
1106 software being built during the compilation step.
1107
Andrew Geissler09036742021-06-25 14:25:14 -05001108 Default initialization for :term:`CFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001109 being built:
1110
1111 - :term:`TARGET_CFLAGS` when building for the
1112 target
1113
1114 - :term:`BUILD_CFLAGS` when building for the
1115 build host (i.e. ``-native``)
1116
1117 - :term:`BUILDSDK_CFLAGS` when building for
1118 an SDK (i.e. ``nativesdk-``)
1119
Andrew Geisslerf0343792020-11-18 10:42:21 -06001120 :term:`CLASSOVERRIDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001121 An internal variable specifying the special class override that
1122 should currently apply (e.g. "class-target", "class-native", and so
1123 forth). The classes that use this variable (e.g.
1124 :ref:`native <ref-classes-native>`,
1125 :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the
1126 variable to appropriate values.
1127
1128 .. note::
1129
Andrew Geissler5f350902021-07-23 13:09:54 -04001130 :term:`CLASSOVERRIDE` gets its default "class-target" value from the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001131 ``bitbake.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001132
1133 As an example, the following override allows you to install extra
Andrew Geisslerc926e172021-05-07 16:11:35 -05001134 files, but only when building for the target::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001135
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001136 do_install:append:class-target() {
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001137 install my-extra-file ${D}${sysconfdir}
1138 }
1139
1140 Here is an example where ``FOO`` is set to
1141 "native" when building for the build host, and to "other" when not
Andrew Geisslerc926e172021-05-07 16:11:35 -05001142 building for the build host::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001143
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001144 FOO:class-native = "native"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001145 FOO = "other"
1146
Andrew Geissler09036742021-06-25 14:25:14 -05001147 The underlying mechanism behind :term:`CLASSOVERRIDE` is simply
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001148 that it is included in the default value of
1149 :term:`OVERRIDES`.
1150
Andrew Geisslerf0343792020-11-18 10:42:21 -06001151 :term:`CLEANBROKEN`
Andrew Geissler09036742021-06-25 14:25:14 -05001152 If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001153 ``make clean`` command does not work for the software being built.
1154 Consequently, the OpenEmbedded build system will not try to run
1155 ``make clean`` during the :ref:`ref-tasks-configure`
1156 task, which is the default behavior.
1157
Andrew Geisslerf0343792020-11-18 10:42:21 -06001158 :term:`COMBINED_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001159 Provides a list of hardware features that are enabled in both
1160 :term:`MACHINE_FEATURES` and
1161 :term:`DISTRO_FEATURES`. This select list of
1162 features contains features that make sense to be controlled both at
1163 the machine and distribution configuration level. For example, the
1164 "bluetooth" feature requires hardware support but should also be
1165 optional at the distribution level, in case the hardware supports
1166 Bluetooth but you do not ever intend to use it.
1167
Andrew Geisslerf0343792020-11-18 10:42:21 -06001168 :term:`COMMON_LICENSE_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001169 Points to ``meta/files/common-licenses`` in the
1170 :term:`Source Directory`, which is where generic license
1171 files reside.
1172
Andrew Geisslerf0343792020-11-18 10:42:21 -06001173 :term:`COMPATIBLE_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001174 A regular expression that resolves to one or more hosts (when the
1175 recipe is native) or one or more targets (when the recipe is
1176 non-native) with which a recipe is compatible. The regular expression
1177 is matched against :term:`HOST_SYS`. You can use the
1178 variable to stop recipes from being built for classes of systems with
1179 which the recipes are not compatible. Stopping these builds is
1180 particularly useful with kernels. The variable also helps to increase
1181 parsing speed since the build system skips parsing recipes not
1182 compatible with the current system.
1183
Andrew Geisslerf0343792020-11-18 10:42:21 -06001184 :term:`COMPATIBLE_MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001185 A regular expression that resolves to one or more target machines
1186 with which a recipe is compatible. The regular expression is matched
1187 against :term:`MACHINEOVERRIDES`. You can use
1188 the variable to stop recipes from being built for machines with which
1189 the recipes are not compatible. Stopping these builds is particularly
1190 useful with kernels. The variable also helps to increase parsing
1191 speed since the build system skips parsing recipes not compatible
1192 with the current machine.
1193
Andrew Geisslerf0343792020-11-18 10:42:21 -06001194 :term:`COMPLEMENTARY_GLOB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001195 Defines wildcards to match when installing a list of complementary
1196 packages for all the packages explicitly (or implicitly) installed in
1197 an image.
1198
1199 .. note::
1200
Andrew Geissler09036742021-06-25 14:25:14 -05001201 The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001202 (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__),
1203 which is similar to the Unix style pathname pattern expansion
1204 (`glob <https://docs.python.org/3/library/glob.html>`__).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001205
1206 The resulting list of complementary packages is associated with an
1207 item that can be added to
1208 :term:`IMAGE_FEATURES`. An example usage of
Andrew Geissler09036742021-06-25 14:25:14 -05001209 this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001210 will install -dev packages (containing headers and other development
1211 files) for every package in the image.
1212
1213 To add a new feature item pointing to a wildcard, use a variable flag
1214 to specify the feature item name and use the value to specify the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001215 wildcard. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001216
1217 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1218
Andrew Geisslerf0343792020-11-18 10:42:21 -06001219 :term:`COMPONENTS_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001220 Stores sysroot components for each recipe. The OpenEmbedded build
Andrew Geissler5f350902021-07-23 13:09:54 -04001221 system uses :term:`COMPONENTS_DIR` when constructing recipe-specific
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001222 sysroots for other recipes.
1223
1224 The default is
1225 "``${``\ :term:`STAGING_DIR`\ ``}-components``."
1226 (i.e.
1227 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
1228
Andrew Geisslerf0343792020-11-18 10:42:21 -06001229 :term:`CONF_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001230 Tracks the version of the local configuration file (i.e.
Andrew Geissler09036742021-06-25 14:25:14 -05001231 ``local.conf``). The value for :term:`CONF_VERSION` increments each time
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001232 ``build/conf/`` compatibility changes.
1233
Andrew Geisslerf0343792020-11-18 10:42:21 -06001234 :term:`CONFFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001235 Identifies editable or configurable files that are part of a package.
1236 If the Package Management System (PMS) is being used to update
1237 packages on the target system, it is possible that configuration
1238 files you have changed after the original installation and that you
1239 now want to remain unchanged are overwritten. In other words,
1240 editable files might exist in the package that you do not want reset
Andrew Geissler09036742021-06-25 14:25:14 -05001241 as part of the package update process. You can use the :term:`CONFFILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001242 variable to list the files in the package that you wish to prevent
1243 the PMS from overwriting during this update process.
1244
Andrew Geissler09036742021-06-25 14:25:14 -05001245 To use the :term:`CONFFILES` variable, provide a package name override
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001246 that identifies the resulting package. Then, provide a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001247 space-separated list of files. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001248
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001249 CONFFILES:${PN} += "${sysconfdir}/file1 \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001250 ${sysconfdir}/file2 ${sysconfdir}/file3"
1251
Andrew Geissler09036742021-06-25 14:25:14 -05001252 There is a relationship between the :term:`CONFFILES` and :term:`FILES`
1253 variables. The files listed within :term:`CONFFILES` must be a subset of
1254 the files listed within :term:`FILES`. Because the configuration files
1255 you provide with :term:`CONFFILES` are simply being identified so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001256 the PMS will not overwrite them, it makes sense that the files must
Andrew Geissler09036742021-06-25 14:25:14 -05001257 already be included as part of the package through the :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001258 variable.
1259
1260 .. note::
1261
Andrew Geissler09036742021-06-25 14:25:14 -05001262 When specifying paths as part of the :term:`CONFFILES` variable, it is
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001263 good practice to use appropriate path variables.
1264 For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}``
1265 rather than ``/usr/bin``. You can find a list of these variables at
1266 the top of the ``meta/conf/bitbake.conf`` file in the
1267 :term:`Source Directory`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001268
Andrew Geisslerf0343792020-11-18 10:42:21 -06001269 :term:`CONFIG_INITRAMFS_SOURCE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001270 Identifies the initial RAM filesystem (initramfs) source files. The
1271 OpenEmbedded build system receives and uses this kernel Kconfig
1272 variable as an environment variable. By default, the variable is set
1273 to null ("").
1274
Andrew Geissler09036742021-06-25 14:25:14 -05001275 The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001276 with a ``.cpio`` suffix or a space-separated list of directories and
1277 files for building the initramfs image. A cpio archive should contain
1278 a filesystem archive to be used as an initramfs image. Directories
1279 should contain a filesystem layout to be included in the initramfs
1280 image. Files should contain entries according to the format described
1281 by the ``usr/gen_init_cpio`` program in the kernel tree.
1282
1283 If you specify multiple directories and files, the initramfs image
1284 will be the aggregate of all of them.
1285
1286 For information on creating an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001287 ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001288 in the Yocto Project Development Tasks Manual.
1289
Andrew Geisslerf0343792020-11-18 10:42:21 -06001290 :term:`CONFIG_SITE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001291 A list of files that contains ``autoconf`` test results relevant to
1292 the current build. This variable is used by the Autotools utilities
1293 when running ``configure``.
1294
Andrew Geisslerf0343792020-11-18 10:42:21 -06001295 :term:`CONFIGURE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001296 The minimal arguments for GNU configure.
1297
Andrew Geisslerf0343792020-11-18 10:42:21 -06001298 :term:`CONFLICT_DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001299 When inheriting the
Andrew Geissler6ce62a22020-11-30 19:58:47 -06001300 :ref:`features_check <ref-classes-features_check>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001301 class, this variable identifies distribution features that would be
1302 in conflict should the recipe be built. In other words, if the
Andrew Geissler09036742021-06-25 14:25:14 -05001303 :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also
1304 appears in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -06001305 the recipe will be skipped, and if the build system attempts to build
1306 the recipe then an error will be triggered.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001307
Andrew Geisslerf0343792020-11-18 10:42:21 -06001308 :term:`COPYLEFT_LICENSE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001309 A space-separated list of licenses to exclude from the source
1310 archived by the :ref:`archiver <ref-classes-archiver>` class. In
1311 other words, if a license in a recipe's
1312 :term:`LICENSE` value is in the value of
Andrew Geissler09036742021-06-25 14:25:14 -05001313 :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001314 class.
1315
1316 .. note::
1317
Andrew Geissler09036742021-06-25 14:25:14 -05001318 The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001319 :term:`COPYLEFT_LICENSE_INCLUDE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001320
1321 The default value, which is "CLOSED Proprietary", for
Andrew Geissler09036742021-06-25 14:25:14 -05001322 :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001323 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1324 is inherited by the ``archiver`` class.
1325
Andrew Geisslerf0343792020-11-18 10:42:21 -06001326 :term:`COPYLEFT_LICENSE_INCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001327 A space-separated list of licenses to include in the source archived
1328 by the :ref:`archiver <ref-classes-archiver>` class. In other
1329 words, if a license in a recipe's :term:`LICENSE`
Andrew Geissler09036742021-06-25 14:25:14 -05001330 value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001331 source is archived by the class.
1332
1333 The default value is set by the
1334 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1335 is inherited by the ``archiver`` class. The default value includes
1336 "GPL*", "LGPL*", and "AGPL*".
1337
Andrew Geisslerf0343792020-11-18 10:42:21 -06001338 :term:`COPYLEFT_PN_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001339 A list of recipes to exclude in the source archived by the
1340 :ref:`archiver <ref-classes-archiver>` class. The
Andrew Geissler09036742021-06-25 14:25:14 -05001341 :term:`COPYLEFT_PN_EXCLUDE` variable overrides the license inclusion and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001342 exclusion caused through the
1343 :term:`COPYLEFT_LICENSE_INCLUDE` and
1344 :term:`COPYLEFT_LICENSE_EXCLUDE`
1345 variables, respectively.
1346
1347 The default value, which is "" indicating to not explicitly exclude
Andrew Geissler09036742021-06-25 14:25:14 -05001348 any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001349 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1350 is inherited by the ``archiver`` class.
1351
Andrew Geisslerf0343792020-11-18 10:42:21 -06001352 :term:`COPYLEFT_PN_INCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001353 A list of recipes to include in the source archived by the
1354 :ref:`archiver <ref-classes-archiver>` class. The
Andrew Geissler09036742021-06-25 14:25:14 -05001355 :term:`COPYLEFT_PN_INCLUDE` variable overrides the license inclusion and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001356 exclusion caused through the
1357 :term:`COPYLEFT_LICENSE_INCLUDE` and
1358 :term:`COPYLEFT_LICENSE_EXCLUDE`
1359 variables, respectively.
1360
1361 The default value, which is "" indicating to not explicitly include
Andrew Geissler09036742021-06-25 14:25:14 -05001362 any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001363 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1364 is inherited by the ``archiver`` class.
1365
Andrew Geisslerf0343792020-11-18 10:42:21 -06001366 :term:`COPYLEFT_RECIPE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001367 A space-separated list of recipe types to include in the source
1368 archived by the :ref:`archiver <ref-classes-archiver>` class.
1369 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``,
1370 ``crosssdk``, and ``cross-canadian``.
1371
Andrew Geissler09036742021-06-25 14:25:14 -05001372 The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001373 is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>`
1374 class, which is inherited by the ``archiver`` class.
1375
Andrew Geisslerf0343792020-11-18 10:42:21 -06001376 :term:`COPY_LIC_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001377 If set to "1" along with the
1378 :term:`COPY_LIC_MANIFEST` variable, the
1379 OpenEmbedded build system copies into the image the license files,
1380 which are located in ``/usr/share/common-licenses``, for each
1381 package. The license files are placed in directories within the image
1382 itself during build time.
1383
1384 .. note::
1385
Andrew Geissler09036742021-06-25 14:25:14 -05001386 The :term:`COPY_LIC_DIRS` does not offer a path for adding licenses for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001387 newly installed packages to an image, which might be most suitable for
1388 read-only filesystems that cannot be upgraded. See the
1389 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001390 You can also reference the ":ref:`dev-manual/common-tasks:providing license text`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001391 section in the Yocto Project Development Tasks Manual for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001392 information on providing license text.
1393
Andrew Geisslerf0343792020-11-18 10:42:21 -06001394 :term:`COPY_LIC_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001395 If set to "1", the OpenEmbedded build system copies the license
1396 manifest for the image to
1397 ``/usr/share/common-licenses/license.manifest`` within the image
1398 itself during build time.
1399
1400 .. note::
1401
Andrew Geissler09036742021-06-25 14:25:14 -05001402 The :term:`COPY_LIC_MANIFEST` does not offer a path for adding licenses for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001403 newly installed packages to an image, which might be most suitable for
1404 read-only filesystems that cannot be upgraded. See the
1405 :term:`LICENSE_CREATE_PACKAGE` variable for additional information.
Andrew Geissler09209ee2020-12-13 08:44:15 -06001406 You can also reference the ":ref:`dev-manual/common-tasks:providing license text`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001407 section in the Yocto Project Development Tasks Manual for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001408 information on providing license text.
1409
Andrew Geisslerf0343792020-11-18 10:42:21 -06001410 :term:`CORE_IMAGE_EXTRA_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001411 Specifies the list of packages to be added to the image. You should
1412 only set this variable in the ``local.conf`` configuration file found
1413 in the :term:`Build Directory`.
1414
1415 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
1416 supported.
1417
Andrew Geisslerf0343792020-11-18 10:42:21 -06001418 :term:`COREBASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001419 Specifies the parent directory of the OpenEmbedded-Core Metadata
1420 layer (i.e. ``meta``).
1421
Andrew Geissler09036742021-06-25 14:25:14 -05001422 It is an important distinction that :term:`COREBASE` points to the parent
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001423 of this layer and not the layer itself. Consider an example where you
1424 have cloned the Poky Git repository and retained the ``poky`` name
Andrew Geissler09036742021-06-25 14:25:14 -05001425 for your local copy of the repository. In this case, :term:`COREBASE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001426 points to the ``poky`` folder because it is the parent directory of
1427 the ``poky/meta`` layer.
1428
Andrew Geisslerf0343792020-11-18 10:42:21 -06001429 :term:`COREBASE_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001430 Lists files from the :term:`COREBASE` directory that
1431 should be copied other than the layers listed in the
Andrew Geissler09036742021-06-25 14:25:14 -05001432 ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001433 to copy metadata from the OpenEmbedded build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001434 into the extensible SDK.
1435
Andrew Geissler09036742021-06-25 14:25:14 -05001436 Explicitly listing files in :term:`COREBASE` is needed because it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001437 typically contains build directories and other files that should not
1438 normally be copied into the extensible SDK. Consequently, the value
Andrew Geissler09036742021-06-25 14:25:14 -05001439 of :term:`COREBASE_FILES` is used in order to only copy the files that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001440 are actually needed.
1441
Andrew Geisslerf0343792020-11-18 10:42:21 -06001442 :term:`CPP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001443 The minimal command and arguments used to run the C preprocessor.
1444
Andrew Geisslerf0343792020-11-18 10:42:21 -06001445 :term:`CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001446 Specifies the flags to pass to the C pre-processor (i.e. to both the
1447 C and the C++ compilers). This variable is exported to an environment
1448 variable and thus made visible to the software being built during the
1449 compilation step.
1450
Andrew Geissler09036742021-06-25 14:25:14 -05001451 Default initialization for :term:`CPPFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001452 being built:
1453
1454 - :term:`TARGET_CPPFLAGS` when building for
1455 the target
1456
1457 - :term:`BUILD_CPPFLAGS` when building for the
1458 build host (i.e. ``-native``)
1459
1460 - :term:`BUILDSDK_CPPFLAGS` when building
1461 for an SDK (i.e. ``nativesdk-``)
1462
Andrew Geisslerf0343792020-11-18 10:42:21 -06001463 :term:`CROSS_COMPILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001464 The toolchain binary prefix for the target tools. The
Andrew Geissler09036742021-06-25 14:25:14 -05001465 :term:`CROSS_COMPILE` variable is the same as the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001466 :term:`TARGET_PREFIX` variable.
1467
1468 .. note::
1469
Andrew Geissler09036742021-06-25 14:25:14 -05001470 The OpenEmbedded build system sets the :term:`CROSS_COMPILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001471 variable only in certain contexts (e.g. when building for kernel
1472 and kernel module recipes).
1473
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001474 :term:`CVE_CHECK_PN_WHITELIST`
1475 The list of package names (:term:`PN`) for which
1476 CVEs (Common Vulnerabilities and Exposures) are ignored.
1477
1478 :term:`CVE_CHECK_WHITELIST`
1479 The list of CVE IDs which are ignored. Here is
1480 an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`::
1481
1482 # This is windows only issue.
1483 CVE_CHECK_WHITELIST += "CVE-2020-15523"
1484
Patrick Williams213cb262021-08-07 19:21:33 -05001485 :term:`CVE_PRODUCT`
1486 In a recipe, defines the name used to match the recipe name
1487 against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__.
1488
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001489 The default is ${:term:`BPN`}. If it does not match the name in the NIST CVE
Patrick Williams213cb262021-08-07 19:21:33 -05001490 database or matches with multiple entries in the database, the default
1491 value needs to be changed.
1492
1493 Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`::
1494
1495 CVE_PRODUCT = "oracle_berkeley_db berkeley_db"
1496
Andrew Geisslerf0343792020-11-18 10:42:21 -06001497 :term:`CVSDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001498 The directory in which files checked out under the CVS system are
1499 stored.
1500
Andrew Geisslerf0343792020-11-18 10:42:21 -06001501 :term:`CXX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001502 The minimal command and arguments used to run the C++ compiler.
1503
Andrew Geisslerf0343792020-11-18 10:42:21 -06001504 :term:`CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001505 Specifies the flags to pass to the C++ compiler. This variable is
1506 exported to an environment variable and thus made visible to the
1507 software being built during the compilation step.
1508
Andrew Geissler09036742021-06-25 14:25:14 -05001509 Default initialization for :term:`CXXFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001510 being built:
1511
1512 - :term:`TARGET_CXXFLAGS` when building for
1513 the target
1514
1515 - :term:`BUILD_CXXFLAGS` when building for the
1516 build host (i.e. ``-native``)
1517
1518 - :term:`BUILDSDK_CXXFLAGS` when building
1519 for an SDK (i.e. ``nativesdk-``)
1520
Andrew Geisslerf0343792020-11-18 10:42:21 -06001521 :term:`D`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001522 The destination directory. The location in the :term:`Build Directory`
1523 where components are installed by the
1524 :ref:`ref-tasks-install` task. This location defaults
Andrew Geisslerc926e172021-05-07 16:11:35 -05001525 to::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001526
1527 ${WORKDIR}/image
1528
1529 .. note::
1530
1531 Tasks that read from or write to this directory should run under
Andrew Geissler09209ee2020-12-13 08:44:15 -06001532 :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001533
Andrew Geisslerf0343792020-11-18 10:42:21 -06001534 :term:`DATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001535 The date the build was started. Dates appear using the year, month,
1536 and day (YMD) format (e.g. "20150209" for February 9th, 2015).
1537
Andrew Geisslerf0343792020-11-18 10:42:21 -06001538 :term:`DATETIME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001539 The date and time on which the current build started. The format is
1540 suitable for timestamps.
1541
Andrew Geisslerf0343792020-11-18 10:42:21 -06001542 :term:`DEBIAN_NOAUTONAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001543 When the :ref:`debian <ref-classes-debian>` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -05001544 which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001545 particular package should not be renamed according to Debian library
1546 package naming. You must use the package name as an override when you
Andrew Geisslerc926e172021-05-07 16:11:35 -05001547 set this variable. Here is an example from the ``fontconfig`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001548
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001549 DEBIAN_NOAUTONAME:fontconfig-utils = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001550
Andrew Geisslerf0343792020-11-18 10:42:21 -06001551 :term:`DEBIANNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001552 When the :ref:`debian <ref-classes-debian>` class is inherited,
Andrew Geissler09036742021-06-25 14:25:14 -05001553 which is the default behavior, :term:`DEBIANNAME` allows you to override
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001554 the library name for an individual package. Overriding the library
1555 name in these cases is rare. You must use the package name as an
1556 override when you set this variable. Here is an example from the
Andrew Geisslerc926e172021-05-07 16:11:35 -05001557 ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001558
Patrick Williams0ca19cc2021-08-16 14:03:13 -05001559 DEBIANNAME:${PN} = "dbus-1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001560
Andrew Geisslerf0343792020-11-18 10:42:21 -06001561 :term:`DEBUG_BUILD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001562 Specifies to build packages with debugging information. This
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001563 influences the value of the :term:`SELECTED_OPTIMIZATION` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001564
Andrew Geisslerf0343792020-11-18 10:42:21 -06001565 :term:`DEBUG_OPTIMIZATION`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001566 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001567 compiling a system for debugging. This variable defaults to "-O
1568 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1569
Andrew Geisslerf0343792020-11-18 10:42:21 -06001570 :term:`DEFAULT_PREFERENCE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001571 Specifies a weak bias for recipe selection priority.
1572
1573 The most common usage of this is variable is to set it to "-1" within
1574 a recipe for a development version of a piece of software. Using the
1575 variable in this way causes the stable version of the recipe to build
William A. Kennington IIIac69b482021-06-02 12:28:27 -07001576 by default in the absence of :term:`PREFERRED_VERSION` being used to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001577 build the development version.
1578
1579 .. note::
1580
Andrew Geissler09036742021-06-25 14:25:14 -05001581 The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001582 by :term:`BBFILE_PRIORITY` if that variable is different between two
1583 layers that contain different versions of the same recipe.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001584
Andrew Geisslerf0343792020-11-18 10:42:21 -06001585 :term:`DEFAULTTUNE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001586 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1587 the "tune") used by the OpenEmbedded build system. The
Andrew Geissler09036742021-06-25 14:25:14 -05001588 :term:`DEFAULTTUNE` helps define
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001589 :term:`TUNE_FEATURES`.
1590
1591 The default tune is either implicitly or explicitly set by the
1592 machine (:term:`MACHINE`). However, you can override
1593 the setting using available tunes as defined with
1594 :term:`AVAILTUNES`.
1595
Andrew Geisslerf0343792020-11-18 10:42:21 -06001596 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001597 Lists a recipe's build-time dependencies. These are dependencies on
1598 other recipes whose contents (e.g. headers and shared libraries) are
1599 needed by the recipe at build time.
1600
1601 As an example, consider a recipe ``foo`` that contains the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001602 assignment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001603
1604 DEPENDS = "bar"
1605
1606 The practical effect of the previous
1607 assignment is that all files installed by bar will be available in
1608 the appropriate staging sysroot, given by the
1609 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the
1610 :ref:`ref-tasks-configure` task for ``foo`` runs.
1611 This mechanism is implemented by having ``do_configure`` depend on
1612 the :ref:`ref-tasks-populate_sysroot` task of
Andrew Geissler09036742021-06-25 14:25:14 -05001613 each recipe listed in :term:`DEPENDS`, through a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001614 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1615 declaration in the :ref:`base <ref-classes-base>` class.
1616
1617 .. note::
1618
Andrew Geissler09036742021-06-25 14:25:14 -05001619 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001620 explicitly. The standard classes and build-related variables are
1621 configured to automatically use the appropriate staging sysroots.
1622
Andrew Geissler09036742021-06-25 14:25:14 -05001623 As another example, :term:`DEPENDS` can also be used to add utilities
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001624 that run on the build machine during the build. For example, a recipe
1625 that makes use of a code generator built by the recipe ``codegen``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001626 might have the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001627
1628 DEPENDS = "codegen-native"
1629
1630 For more
1631 information, see the :ref:`native <ref-classes-native>` class and
1632 the :term:`EXTRANATIVEPATH` variable.
1633
1634 .. note::
1635
Andrew Geissler09036742021-06-25 14:25:14 -05001636 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001637 it is a list of :term:`PROVIDES` names, which
1638 usually match recipe names. Putting a package name such as
Andrew Geissler09036742021-06-25 14:25:14 -05001639 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001640 instead, as this will put files from all the packages that make
1641 up ``foo``, which includes those from ``foo-dev``, into the
1642 sysroot.
1643
Andrew Geissler09036742021-06-25 14:25:14 -05001644 - One recipe having another recipe in :term:`DEPENDS` does not by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001645 itself add any runtime dependencies between the packages
1646 produced by the two recipes. However, as explained in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001647 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001648 section in the Yocto Project Overview and Concepts Manual,
1649 runtime dependencies will often be added automatically, meaning
Andrew Geissler5f350902021-07-23 13:09:54 -04001650 :term:`DEPENDS` alone is sufficient for most recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001651
Andrew Geissler09036742021-06-25 14:25:14 -05001652 - Counterintuitively, :term:`DEPENDS` is often necessary even for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001653 recipes that install precompiled components. For example, if
1654 ``libfoo`` is a precompiled library that links against
1655 ``libbar``, then linking against ``libfoo`` requires both
1656 ``libfoo`` and ``libbar`` to be available in the sysroot.
Andrew Geissler09036742021-06-25 14:25:14 -05001657 Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001658 to the recipe that installs ``libbar``, other recipes might
1659 fail to link against ``libfoo``.
1660
1661 For information on runtime dependencies, see the
1662 :term:`RDEPENDS` variable. You can also see the
Patrick Williams213cb262021-08-07 19:21:33 -05001663 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
1664 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001665 BitBake User Manual for additional information on tasks and
1666 dependencies.
1667
Andrew Geisslerf0343792020-11-18 10:42:21 -06001668 :term:`DEPLOY_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001669 Points to the general area that the OpenEmbedded build system uses to
1670 place images, packages, SDKs, and other output files that are ready
1671 to be used outside of the build system. By default, this directory
1672 resides within the :term:`Build Directory` as
1673 ``${TMPDIR}/deploy``.
1674
1675 For more information on the structure of the Build Directory, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06001676 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001677 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001678 ":ref:`overview-manual/concepts:images`",
1679 ":ref:`overview-manual/concepts:package feeds`", and
1680 ":ref:`overview-manual/concepts:application development sdk`" sections all in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001681 Yocto Project Overview and Concepts Manual.
1682
Andrew Geisslerf0343792020-11-18 10:42:21 -06001683 :term:`DEPLOY_DIR_DEB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001684 Points to the area that the OpenEmbedded build system uses to place
1685 Debian packages that are ready to be used outside of the build
1686 system. This variable applies only when
1687 :term:`PACKAGE_CLASSES` contains
1688 "package_deb".
1689
1690 The BitBake configuration file initially defines the
Andrew Geissler5f350902021-07-23 13:09:54 -04001691 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of
Andrew Geisslerc926e172021-05-07 16:11:35 -05001692 :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001693
1694 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
1695
1696 The :ref:`package_deb <ref-classes-package_deb>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001697 :term:`DEPLOY_DIR_DEB` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001698 :ref:`ref-tasks-package_write_deb` task
1699 writes Debian packages into the appropriate folder. For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06001700 information on how packaging works, see the
1701 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001702 in the Yocto Project Overview and Concepts Manual.
1703
Andrew Geisslerf0343792020-11-18 10:42:21 -06001704 :term:`DEPLOY_DIR_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001705 Points to the area that the OpenEmbedded build system uses to place
1706 images and other associated output files that are ready to be
1707 deployed onto the target machine. The directory is machine-specific
1708 as it contains the ``${MACHINE}`` name. By default, this directory
1709 resides within the :term:`Build Directory` as
1710 ``${DEPLOY_DIR}/images/${MACHINE}/``.
1711
Andrew Geissler09036742021-06-25 14:25:14 -05001712 It must not be used directly in recipes when deploying files. Instead,
1713 it's only useful when a recipe needs to "read" a file already deployed
1714 by a dependency. So, it should be filled with the contents of
1715 :term:`DEPLOYDIR` by the :ref:`deploy <ref-classes-deploy>` class or
1716 with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image
1717 <ref-classes-image>` class.
1718
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001719 For more information on the structure of the Build Directory, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06001720 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001721 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001722 ":ref:`overview-manual/concepts:images`" and
1723 ":ref:`overview-manual/concepts:application development sdk`" sections both in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001724 the Yocto Project Overview and Concepts Manual.
1725
Andrew Geisslerf0343792020-11-18 10:42:21 -06001726 :term:`DEPLOY_DIR_IPK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001727 Points to the area that the OpenEmbedded build system uses to place
1728 IPK packages that are ready to be used outside of the build system.
1729 This variable applies only when
1730 :term:`PACKAGE_CLASSES` contains
1731 "package_ipk".
1732
1733 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001734 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001735
1736 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
1737
1738 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001739 :term:`DEPLOY_DIR_IPK` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001740 :ref:`ref-tasks-package_write_ipk` task
1741 writes IPK packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001742 on how packaging works, see the
1743 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001744 in the Yocto Project Overview and Concepts Manual.
1745
Andrew Geisslerf0343792020-11-18 10:42:21 -06001746 :term:`DEPLOY_DIR_RPM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001747 Points to the area that the OpenEmbedded build system uses to place
1748 RPM packages that are ready to be used outside of the build system.
1749 This variable applies only when
1750 :term:`PACKAGE_CLASSES` contains
1751 "package_rpm".
1752
1753 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001754 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001755
1756 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
1757
1758 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001759 :term:`DEPLOY_DIR_RPM` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001760 :ref:`ref-tasks-package_write_rpm` task
1761 writes RPM packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001762 on how packaging works, see the
1763 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001764 in the Yocto Project Overview and Concepts Manual.
1765
Andrew Geisslerf0343792020-11-18 10:42:21 -06001766 :term:`DEPLOY_DIR_TAR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001767 Points to the area that the OpenEmbedded build system uses to place
1768 tarballs that are ready to be used outside of the build system. This
1769 variable applies only when
1770 :term:`PACKAGE_CLASSES` contains
1771 "package_tar".
1772
1773 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001774 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001775
1776 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
1777
1778 The :ref:`package_tar <ref-classes-package_tar>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001779 :term:`DEPLOY_DIR_TAR` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001780 :ref:`ref-tasks-package_write_tar` task
1781 writes TAR packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001782 on how packaging works, see the
1783 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001784 in the Yocto Project Overview and Concepts Manual.
1785
Andrew Geisslerf0343792020-11-18 10:42:21 -06001786 :term:`DEPLOYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001787 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the
Andrew Geissler09036742021-06-25 14:25:14 -05001788 :term:`DEPLOYDIR` points to a temporary work area for deployed files that
Andrew Geisslerc926e172021-05-07 16:11:35 -05001789 is set in the ``deploy`` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001790
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001791 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001792
1793 Recipes inheriting the ``deploy`` class should copy files to be
Andrew Geissler09036742021-06-25 14:25:14 -05001794 deployed into :term:`DEPLOYDIR`, and the class will take care of copying
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001795 them into :term:`DEPLOY_DIR_IMAGE`
1796 afterwards.
1797
Andrew Geisslerf0343792020-11-18 10:42:21 -06001798 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001799 The package description used by package managers. If not set,
Andrew Geissler09036742021-06-25 14:25:14 -05001800 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001801 variable.
1802
Andrew Geisslerf0343792020-11-18 10:42:21 -06001803 :term:`DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001804 The short name of the distribution. For information on the long name
1805 of the distribution, see the :term:`DISTRO_NAME`
1806 variable.
1807
Andrew Geissler09036742021-06-25 14:25:14 -05001808 The :term:`DISTRO` variable corresponds to a distribution configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001809 file whose root name is the same as the variable's argument and whose
1810 filename extension is ``.conf``. For example, the distribution
1811 configuration file for the Poky distribution is named ``poky.conf``
1812 and resides in the ``meta-poky/conf/distro`` directory of the
1813 :term:`Source Directory`.
1814
Andrew Geissler09036742021-06-25 14:25:14 -05001815 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05001816 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001817
1818 DISTRO = "poky"
1819
1820 Distribution configuration files are located in a ``conf/distro``
1821 directory within the :term:`Metadata` that contains the
Andrew Geissler09036742021-06-25 14:25:14 -05001822 distribution configuration. The value for :term:`DISTRO` must not contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001823 spaces, and is typically all lower-case.
1824
1825 .. note::
1826
Andrew Geissler09036742021-06-25 14:25:14 -05001827 If the :term:`DISTRO` variable is blank, a set of default configurations
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001828 are used, which are specified within
1829 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001830
Andrew Geisslerf0343792020-11-18 10:42:21 -06001831 :term:`DISTRO_CODENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001832 Specifies a codename for the distribution being built.
1833
Andrew Geisslerf0343792020-11-18 10:42:21 -06001834 :term:`DISTRO_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001835 Specifies a list of distro-specific packages to add to all images.
1836 This variable takes affect through ``packagegroup-base`` so the
1837 variable only really applies to the more full-featured images that
1838 include ``packagegroup-base``. You can use this variable to keep
1839 distro policy out of generic images. As with all other distro
1840 variables, you set this variable in the distro ``.conf`` file.
1841
Andrew Geisslerf0343792020-11-18 10:42:21 -06001842 :term:`DISTRO_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001843 Specifies a list of distro-specific packages to add to all images if
1844 the packages exist. The packages might not exist or be empty (e.g.
1845 kernel modules). The list of packages are automatically installed but
1846 you can remove them.
1847
Andrew Geisslerf0343792020-11-18 10:42:21 -06001848 :term:`DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001849 The software support you want in your distribution for various
1850 features. You define your distribution features in the distribution
1851 configuration file.
1852
1853 In most cases, the presence or absence of a feature in
Andrew Geissler09036742021-06-25 14:25:14 -05001854 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001855 to the configure script during the
1856 :ref:`ref-tasks-configure` task for recipes that
1857 optionally support the feature. For example, specifying "x11" in
Andrew Geissler09036742021-06-25 14:25:14 -05001858 :term:`DISTRO_FEATURES`, causes every piece of software built for the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001859 target that can optionally support X11 to have its X11 support
1860 enabled.
1861
1862 Two more examples are Bluetooth and NFS support. For a more complete
1863 list of features that ships with the Yocto Project and that you can
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001864 provide with this variable, see the ":ref:`ref-features-distro`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001865
Andrew Geisslerf0343792020-11-18 10:42:21 -06001866 :term:`DISTRO_FEATURES_BACKFILL`
Andrew Geissler09036742021-06-25 14:25:14 -05001867 Features to be added to :term:`DISTRO_FEATURES` if not also present in
1868 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001869
1870 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1871 not intended to be user-configurable. It is best to just reference
1872 the variable to see which distro features are being backfilled for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001873 all distro configurations. See the ":ref:`ref-features-backfill`" section
1874 for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001875
Andrew Geisslerf0343792020-11-18 10:42:21 -06001876 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
Andrew Geissler09036742021-06-25 14:25:14 -05001877 Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be
1878 backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001879 the ":ref:`ref-features-backfill`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001880
Andrew Geisslerf0343792020-11-18 10:42:21 -06001881 :term:`DISTRO_FEATURES_DEFAULT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001882 A convenience variable that gives you the default list of distro
1883 features with the exception of any features specific to the C library
1884 (``libc``).
1885
1886 When creating a custom distribution, you might find it useful to be
1887 able to reuse the default
1888 :term:`DISTRO_FEATURES` options without the
1889 need to write out the full set. Here is an example that uses
Andrew Geissler09036742021-06-25 14:25:14 -05001890 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001891
1892 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
1893
Andrew Geisslerf0343792020-11-18 10:42:21 -06001894 :term:`DISTRO_FEATURES_FILTER_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001895 Specifies a list of features that if present in the target
1896 :term:`DISTRO_FEATURES` value should be
Andrew Geissler09036742021-06-25 14:25:14 -05001897 included in :term:`DISTRO_FEATURES` when building native recipes. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001898 variable is used in addition to the features filtered using the
1899 :term:`DISTRO_FEATURES_NATIVE`
1900 variable.
1901
Andrew Geisslerf0343792020-11-18 10:42:21 -06001902 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001903 Specifies a list of features that if present in the target
1904 :term:`DISTRO_FEATURES` value should be
Andrew Geissler09036742021-06-25 14:25:14 -05001905 included in :term:`DISTRO_FEATURES` when building nativesdk recipes. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001906 variable is used in addition to the features filtered using the
1907 :term:`DISTRO_FEATURES_NATIVESDK`
1908 variable.
1909
Andrew Geisslerf0343792020-11-18 10:42:21 -06001910 :term:`DISTRO_FEATURES_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001911 Specifies a list of features that should be included in
1912 :term:`DISTRO_FEATURES` when building native
1913 recipes. This variable is used in addition to the features filtered
1914 using the
1915 :term:`DISTRO_FEATURES_FILTER_NATIVE`
1916 variable.
1917
Andrew Geisslerf0343792020-11-18 10:42:21 -06001918 :term:`DISTRO_FEATURES_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001919 Specifies a list of features that should be included in
1920 :term:`DISTRO_FEATURES` when building
1921 nativesdk recipes. This variable is used in addition to the features
1922 filtered using the
1923 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
1924 variable.
1925
Andrew Geisslerf0343792020-11-18 10:42:21 -06001926 :term:`DISTRO_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001927 The long name of the distribution. For information on the short name
1928 of the distribution, see the :term:`DISTRO` variable.
1929
Andrew Geissler09036742021-06-25 14:25:14 -05001930 The :term:`DISTRO_NAME` variable corresponds to a distribution
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001931 configuration file whose root name is the same as the variable's
1932 argument and whose filename extension is ``.conf``. For example, the
1933 distribution configuration file for the Poky distribution is named
1934 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
1935 of the :term:`Source Directory`.
1936
Andrew Geissler09036742021-06-25 14:25:14 -05001937 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
Andrew Geisslerc926e172021-05-07 16:11:35 -05001938 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001939
1940 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
1941
1942 Distribution configuration files are located in a ``conf/distro``
1943 directory within the :term:`Metadata` that contains the
1944 distribution configuration.
1945
1946 .. note::
1947
Andrew Geissler09036742021-06-25 14:25:14 -05001948 If the :term:`DISTRO_NAME` variable is blank, a set of default
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001949 configurations are used, which are specified within
1950 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001951
Andrew Geisslerf0343792020-11-18 10:42:21 -06001952 :term:`DISTRO_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001953 The version of the distribution.
1954
Andrew Geisslerf0343792020-11-18 10:42:21 -06001955 :term:`DISTROOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001956 A colon-separated list of overrides specific to the current
1957 distribution. By default, this list includes the value of
1958 :term:`DISTRO`.
1959
Andrew Geissler09036742021-06-25 14:25:14 -05001960 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001961 apply to the distribution.
1962
Andrew Geissler09036742021-06-25 14:25:14 -05001963 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001964 is included in the default value of
1965 :term:`OVERRIDES`.
1966
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001967 :term:`DISTUTILS_SETUP_PATH`
1968 When used by recipes that inherit the
1969 :ref:`distutils3 <ref-classes-distutils3>` or
1970 :ref:`setuptools3 <ref-classes-setuptools3>` class, this variable should
1971 be used to specify the directory in which the ``setup.py`` file is
1972 located if it is not at the root of the source tree (as specified by
1973 :term:`S`). For example, in a recipe where the sources are fetched from
1974 a Git repository and ``setup.py`` is in a ``python/pythonmodule``
1975 subdirectory, you would have this::
1976
1977 S = "${WORKDIR}/git"
1978 DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
1979
Andrew Geisslerf0343792020-11-18 10:42:21 -06001980 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001981 The central download directory used by the build process to store
Andrew Geissler09036742021-06-25 14:25:14 -05001982 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001983 for everything except Git repositories. If you want tarballs of Git
1984 repositories, use the
1985 :term:`BB_GENERATE_MIRROR_TARBALLS`
1986 variable.
1987
Andrew Geissler09036742021-06-25 14:25:14 -05001988 You can set this directory by defining the :term:`DL_DIR` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001989 ``conf/local.conf`` file. This directory is self-maintaining and you
1990 should not have to touch it. By default, the directory is
1991 ``downloads`` in the :term:`Build Directory`.
1992 ::
1993
1994 #DL_DIR ?= "${TOPDIR}/downloads"
1995
1996 To specify a different download directory,
1997 simply remove the comment from the line and provide your directory.
1998
1999 During a first build, the system downloads many different source code
2000 tarballs from various upstream projects. Downloading can take a
2001 while, particularly if your network connection is slow. Tarballs are
Andrew Geissler09036742021-06-25 14:25:14 -05002002 all stored in the directory defined by :term:`DL_DIR` and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002003 system looks there first to find source tarballs.
2004
2005 .. note::
2006
2007 When wiping and rebuilding, you can preserve this directory to
2008 speed up this part of subsequent builds.
2009
2010 You can safely share this directory between multiple builds on the
2011 same development machine. For additional information on how the build
2012 process gets source files when working behind a firewall or proxy
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002013 server, see this specific question in the ":doc:`faq`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002014 chapter. You can also refer to the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002015 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002016 Wiki page.
2017
Andrew Geisslerf0343792020-11-18 10:42:21 -06002018 :term:`DOC_COMPRESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002019 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>`
2020 class, this variable sets the compression policy used when the
2021 OpenEmbedded build system compresses man pages and info pages. By
2022 default, the compression method used is gz (gzip). Other policies
2023 available are xz and bz2.
2024
2025 For information on policies and on how to use this variable, see the
2026 comments in the ``meta/classes/compress_doc.bbclass`` file.
2027
Andrew Geisslerf0343792020-11-18 10:42:21 -06002028 :term:`EFI_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002029 When building bootable images (i.e. where ``hddimg``, ``iso``, or
2030 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
Andrew Geissler09036742021-06-25 14:25:14 -05002031 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002032 default is "grub-efi", but "systemd-boot" can be used instead.
2033
2034 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and
2035 :ref:`image-live <ref-classes-image-live>` classes for more
2036 information.
2037
Andrew Geisslerf0343792020-11-18 10:42:21 -06002038 :term:`ENABLE_BINARY_LOCALE_GENERATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002039 Variable that controls which locales for ``glibc`` are generated
2040 during the build (useful if the target device has 64Mbytes of RAM or
2041 less).
2042
Andrew Geisslerf0343792020-11-18 10:42:21 -06002043 :term:`ERR_REPORT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002044 When used with the :ref:`report-error <ref-classes-report-error>`
2045 class, specifies the path used for storing the debug files created by
2046 the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002047 tool <dev-manual/common-tasks:using the error reporting tool>`, which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002048 allows you to submit build errors you encounter to a central
2049 database. By default, the value of this variable is
2050 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2051
Andrew Geissler09036742021-06-25 14:25:14 -05002052 You can set :term:`ERR_REPORT_DIR` to the path you want the error
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002053 reporting tool to store the debug files as follows in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05002054 ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002055
2056 ERR_REPORT_DIR = "path"
2057
Andrew Geisslerf0343792020-11-18 10:42:21 -06002058 :term:`ERROR_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002059 Specifies the quality assurance checks whose failures are reported as
2060 errors by the OpenEmbedded build system. You set this variable in
2061 your distribution configuration file. For a list of the checks you
2062 can control with this variable, see the
2063 ":ref:`insane.bbclass <ref-classes-insane>`" section.
2064
Andrew Geisslerf0343792020-11-18 10:42:21 -06002065 :term:`EXCLUDE_FROM_SHLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002066 Triggers the OpenEmbedded build system's shared libraries resolver to
2067 exclude an entire package when scanning for shared libraries.
2068
2069 .. note::
2070
2071 The shared libraries resolver's functionality results in part from
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002072 the internal function ``package_do_shlibs``, which is part of the
2073 :ref:`ref-tasks-package` task. You should be aware that the shared
2074 libraries resolver might implicitly define some dependencies between
2075 packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002076
Andrew Geissler09036742021-06-25 14:25:14 -05002077 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002078 :term:`PRIVATE_LIBS` variable, which excludes a
2079 package's particular libraries only and not the whole package.
2080
Andrew Geissler09036742021-06-25 14:25:14 -05002081 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002082 particular package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002083
2084 EXCLUDE_FROM_SHLIBS = "1"
2085
Andrew Geisslerf0343792020-11-18 10:42:21 -06002086 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002087 Directs BitBake to exclude a recipe from world builds (i.e.
2088 ``bitbake world``). During world builds, BitBake locates, parses and
2089 builds all recipes found in every layer exposed in the
2090 ``bblayers.conf`` configuration file.
2091
2092 To exclude a recipe from a world build using this variable, set the
2093 variable to "1" in the recipe.
2094
2095 .. note::
2096
Andrew Geissler09036742021-06-25 14:25:14 -05002097 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002098 world build in order to satisfy dependencies of other recipes. Adding
Andrew Geissler09036742021-06-25 14:25:14 -05002099 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002100 explicitly added to the list of build targets in a world build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002101
Andrew Geisslerf0343792020-11-18 10:42:21 -06002102 :term:`EXTENDPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002103 Used with file and pathnames to create a prefix for a recipe's
Andrew Geissler09036742021-06-25 14:25:14 -05002104 version based on the recipe's :term:`PE` value. If :term:`PE`
2105 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
2106 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
2107 If a recipe's :term:`PE` is not set (the default) or is equal to zero,
2108 :term:`EXTENDPE` becomes "".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002109
2110 See the :term:`STAMP` variable for an example.
2111
Andrew Geisslerf0343792020-11-18 10:42:21 -06002112 :term:`EXTENDPKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002113 The full package version specification as it appears on the final
2114 packages produced by a recipe. The variable's value is normally used
2115 to fix a runtime dependency to the exact same version of another
Andrew Geisslerc926e172021-05-07 16:11:35 -05002116 package in the same recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002117
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002118 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002119
2120 The dependency relationships are intended to force the package
2121 manager to upgrade these types of packages in lock-step.
2122
Andrew Geisslerf0343792020-11-18 10:42:21 -06002123 :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geissler09036742021-06-25 14:25:14 -05002124 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002125 tools are not in the source tree.
2126
2127 When kernel tools are available in the tree, they are preferred over
Andrew Geissler09036742021-06-25 14:25:14 -05002128 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002129 variable tells the OpenEmbedded build system to prefer the installed
2130 external tools. See the
2131 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in
2132 ``meta/classes`` to see how the variable is used.
2133
Andrew Geisslerf0343792020-11-18 10:42:21 -06002134 :term:`EXTERNALSRC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002135 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
2136 class, this variable points to the source tree, which is outside of
2137 the OpenEmbedded build system. When set, this variable sets the
2138 :term:`S` variable, which is what the OpenEmbedded build
2139 system uses to locate unpacked recipe source code.
2140
2141 For more information on ``externalsrc.bbclass``, see the
2142 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2143 can also find information on how to use this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002144 ":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002145 section in the Yocto Project Development Tasks Manual.
2146
Andrew Geisslerf0343792020-11-18 10:42:21 -06002147 :term:`EXTERNALSRC_BUILD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002148 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
2149 class, this variable points to the directory in which the recipe's
2150 source code is built, which is outside of the OpenEmbedded build
2151 system. When set, this variable sets the :term:`B` variable,
2152 which is what the OpenEmbedded build system uses to locate the Build
2153 Directory.
2154
2155 For more information on ``externalsrc.bbclass``, see the
2156 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2157 can also find information on how to use this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002158 ":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002159 section in the Yocto Project Development Tasks Manual.
2160
Andrew Geisslerf0343792020-11-18 10:42:21 -06002161 :term:`EXTRA_AUTORECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002162 For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
Andrew Geissler09036742021-06-25 14:25:14 -05002163 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002164 pass to the ``autoreconf`` command that is executed during the
2165 :ref:`ref-tasks-configure` task.
2166
2167 The default value is "--exclude=autopoint".
2168
Andrew Geisslerf0343792020-11-18 10:42:21 -06002169 :term:`EXTRA_IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002170 A list of additional features to include in an image. When listing
2171 more than one feature, separate them with a space.
2172
2173 Typically, you configure this variable in your ``local.conf`` file,
2174 which is found in the :term:`Build Directory`.
2175 Although you can use this variable from within a recipe, best
2176 practices dictate that you do not.
2177
2178 .. note::
2179
2180 To enable primary features from within the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002181 :term:`IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002182
2183 Here are some examples of features you can add:
2184
2185 - "dbg-pkgs" - Adds -dbg packages for all installed packages including
2186 symbol information for debugging and profiling.
2187
2188 - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and
2189 enables post-installation logging. See the 'allow-empty-password' and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002190 'post-install-logging' features in the ":ref:`ref-features-image`"
2191 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002192 - "dev-pkgs" - Adds -dev packages for all installed packages. This is
2193 useful if you want to develop against the libraries in the image.
2194 - "read-only-rootfs" - Creates an image whose root filesystem is
2195 read-only. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002196 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002197 section in the Yocto Project Development Tasks Manual for more
2198 information
2199 - "tools-debug" - Adds debugging tools such as gdb and strace.
2200 - "tools-sdk" - Adds development tools such as gcc, make,
2201 pkgconfig and so forth.
2202 - "tools-testapps" - Adds useful testing tools
2203 such as ts_print, aplay, arecord and so forth.
2204
2205 For a complete list of image features that ships with the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002206 Project, see the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002207
2208 For an example that shows how to customize your image by using this
Andrew Geissler09209ee2020-12-13 08:44:15 -06002209 variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002210 section in the Yocto Project Development Tasks Manual.
2211
Andrew Geisslerf0343792020-11-18 10:42:21 -06002212 :term:`EXTRA_IMAGECMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002213 Specifies additional options for the image creation command that has
2214 been specified in :term:`IMAGE_CMD`. When setting
2215 this variable, use an override for the associated image type. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002216 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002217
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002218 EXTRA_IMAGECMD:ext3 ?= "-i 4096"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002219
Andrew Geisslerf0343792020-11-18 10:42:21 -06002220 :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002221 A list of recipes to build that do not provide packages for
2222 installing into the root filesystem.
2223
2224 Sometimes a recipe is required to build the final image but is not
Andrew Geissler09036742021-06-25 14:25:14 -05002225 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002226 variable to list these recipes and thus specify the dependencies. A
2227 typical example is a required bootloader in a machine configuration.
2228
2229 .. note::
2230
2231 To add packages to the root filesystem, see the various
Andrew Geissler95ac1b82021-03-31 14:34:31 -05002232 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002233
Andrew Geisslerf0343792020-11-18 10:42:21 -06002234 :term:`EXTRANATIVEPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002235 A list of subdirectories of
2236 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2237 added to the beginning of the environment variable ``PATH``. As an
2238 example, the following prepends
2239 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
Andrew Geisslerc926e172021-05-07 16:11:35 -05002240 ``PATH``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002241
2242 EXTRANATIVEPATH = "foo bar"
2243
Andrew Geisslerf0343792020-11-18 10:42:21 -06002244 :term:`EXTRA_OECMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002245 Additional `CMake <https://cmake.org/overview/>`__ options. See the
2246 :ref:`cmake <ref-classes-cmake>` class for additional information.
2247
Andrew Geisslerf0343792020-11-18 10:42:21 -06002248 :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002249 Additional ``configure`` script options. See
2250 :term:`PACKAGECONFIG_CONFARGS` for
2251 additional information on passing configure script options.
2252
Andrew Geisslerf0343792020-11-18 10:42:21 -06002253 :term:`EXTRA_OEMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002254 Additional GNU ``make`` options.
2255
Andrew Geissler09036742021-06-25 14:25:14 -05002256 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002257 variable to specify any required GNU options.
2258
2259 :term:`PARALLEL_MAKE` and
2260 :term:`PARALLEL_MAKEINST` also make use of
Andrew Geissler09036742021-06-25 14:25:14 -05002261 :term:`EXTRA_OEMAKE` to pass the required flags.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002262
Andrew Geisslerf0343792020-11-18 10:42:21 -06002263 :term:`EXTRA_OESCONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002264 When inheriting the :ref:`scons <ref-classes-scons>` class, this
2265 variable specifies additional configuration options you want to pass
2266 to the ``scons`` command line.
2267
Andrew Geisslerf0343792020-11-18 10:42:21 -06002268 :term:`EXTRA_USERS_PARAMS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002269 When inheriting the :ref:`extrausers <ref-classes-extrausers>`
2270 class, this variable provides image level user and group operations.
2271 This is a more global method of providing user and group
2272 configuration as compared to using the
2273 :ref:`useradd <ref-classes-useradd>` class, which ties user and
2274 group configurations to a specific recipe.
2275
2276 The set list of commands you can configure using the
Andrew Geissler09036742021-06-25 14:25:14 -05002277 :term:`EXTRA_USERS_PARAMS` is shown in the ``extrausers`` class. These
Andrew Geisslerc926e172021-05-07 16:11:35 -05002278 commands map to the normal Unix commands of the same names::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002279
2280 # EXTRA_USERS_PARAMS = "\
2281 # useradd -p '' tester; \
2282 # groupadd developers; \
2283 # userdel nobody; \
2284 # groupdel -g video; \
2285 # groupmod -g 1020 developers; \
2286 # usermod -s /bin/sh tester; \
2287 # "
2288
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002289 Additionally there is a special ``passwd-expire`` command that will
2290 cause the password for a user to be expired and thus force changing it
2291 on first login, for example::
2292
2293 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
2294
2295 .. note::
2296
2297 At present, ``passwd-expire`` may only work for remote logins when
2298 using OpenSSH and not dropbear as an SSH server.
2299
Andrew Geisslerf0343792020-11-18 10:42:21 -06002300 :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002301 Defines one or more packages to include in an image when a specific
2302 item is included in :term:`IMAGE_FEATURES`.
Andrew Geissler09036742021-06-25 14:25:14 -05002303 When setting the value, :term:`FEATURE_PACKAGES` should have the name of
Andrew Geisslerc926e172021-05-07 16:11:35 -05002304 the feature item as an override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002305
2306 FEATURE_PACKAGES_widget = "package1 package2"
2307
Andrew Geissler09036742021-06-25 14:25:14 -05002308 In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002309 package1 and package2 would be included in the image.
2310
2311 .. note::
2312
Andrew Geissler09036742021-06-25 14:25:14 -05002313 Packages installed by features defined through :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002314 are often package groups. While similarly named, you should not
Andrew Geissler09036742021-06-25 14:25:14 -05002315 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002316 are discussed elsewhere in the documentation.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002317
Andrew Geisslerf0343792020-11-18 10:42:21 -06002318 :term:`FEED_DEPLOYDIR_BASE_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002319 Points to the base URL of the server and location within the
2320 document-root that provides the metadata and packages required by
2321 OPKG to support runtime package management of IPK packages. You set
2322 this variable in your ``local.conf`` file.
2323
Andrew Geisslerc926e172021-05-07 16:11:35 -05002324 Consider the following example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002325
2326 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2327
2328 This example assumes you are serving
2329 your packages over HTTP and your databases are located in a directory
2330 named ``BOARD-dir``, which is underneath your HTTP server's
2331 document-root. In this case, the OpenEmbedded build system generates
2332 a set of configuration files for you in your target that work with
2333 the feed.
2334
Andrew Geisslerf0343792020-11-18 10:42:21 -06002335 :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002336 The list of files and directories that are placed in a package. The
2337 :term:`PACKAGES` variable lists the packages
2338 generated by a recipe.
2339
Andrew Geissler09036742021-06-25 14:25:14 -05002340 To use the :term:`FILES` variable, provide a package name override that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002341 identifies the resulting package. Then, provide a space-separated
2342 list of files or paths that identify the files you want included as
Andrew Geisslerc926e172021-05-07 16:11:35 -05002343 part of the resulting package. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002344
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002345 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002346
2347 .. note::
2348
2349 - When specifying files or paths, you can pattern match using
2350 Python's
2351 `glob <https://docs.python.org/3/library/glob.html>`_
2352 syntax. For details on the syntax, see the documentation by
2353 following the previous link.
2354
Andrew Geissler09036742021-06-25 14:25:14 -05002355 - When specifying paths as part of the :term:`FILES` variable, it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002356 good practice to use appropriate path variables. For example,
2357 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2358 rather than ``/usr/bin``. You can find a list of these
2359 variables at the top of the ``meta/conf/bitbake.conf`` file in
2360 the :term:`Source Directory`. You will also
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002361 find the default values of the various ``FILES:*`` variables in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002362 this file.
2363
Andrew Geissler09036742021-06-25 14:25:14 -05002364 If some of the files you provide with the :term:`FILES` variable are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002365 editable and you know they should not be overwritten during the
2366 package update process by the Package Management System (PMS), you
2367 can identify these files so that the PMS will not overwrite them. See
2368 the :term:`CONFFILES` variable for information on
2369 how to identify these files to the PMS.
2370
Andrew Geisslerf0343792020-11-18 10:42:21 -06002371 :term:`FILES_SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002372 Defines the file specification to match
2373 :term:`SOLIBSDEV`. In other words,
Andrew Geissler09036742021-06-25 14:25:14 -05002374 :term:`FILES_SOLIBSDEV` defines the full path name of the development
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002375 symbolic link (symlink) for shared libraries on the target platform.
2376
2377 The following statement from the ``bitbake.conf`` shows how it is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002378 set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002379
2380 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2381
Andrew Geisslerf0343792020-11-18 10:42:21 -06002382 :term:`FILESEXTRAPATHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002383 Extends the search path the OpenEmbedded build system uses when
2384 looking for files and patches as it processes recipes and append
2385 files. The default directories BitBake uses when it processes recipes
2386 are initially defined by the :term:`FILESPATH`
Andrew Geissler09036742021-06-25 14:25:14 -05002387 variable. You can extend :term:`FILESPATH` variable by using
2388 :term:`FILESEXTRAPATHS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002389
2390 Best practices dictate that you accomplish this by using
Andrew Geissler09036742021-06-25 14:25:14 -05002391 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
Andrew Geisslerc926e172021-05-07 16:11:35 -05002392 prepend paths as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002393
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002394 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002395
2396 In the above example, the build system first
2397 looks for files in a directory that has the same name as the
2398 corresponding append file.
2399
2400 .. note::
2401
Andrew Geissler09036742021-06-25 14:25:14 -05002402 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002403 expansion (``:=``) operator. Immediate expansion makes sure that
2404 BitBake evaluates :term:`THISDIR` at the time the
2405 directive is encountered rather than at some later time when
2406 expansion might result in a directory that does not contain the
2407 files you need.
2408
2409 Also, include the trailing separating colon character if you are
2410 prepending. The trailing colon character is necessary because you
2411 are directing BitBake to extend the path by prepending directories
2412 to the search path.
2413
Andrew Geisslerc926e172021-05-07 16:11:35 -05002414 Here is another common use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002415
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002416 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002417
2418 In this example, the build system extends the
Andrew Geissler09036742021-06-25 14:25:14 -05002419 :term:`FILESPATH` variable to include a directory named ``files`` that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002420 in the same directory as the corresponding append file.
2421
Andrew Geisslerc926e172021-05-07 16:11:35 -05002422 This next example specifically adds three paths::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002423
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002424 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002425
2426 A final example shows how you can extend the search path and include
2427 a :term:`MACHINE`-specific override, which is useful
Andrew Geisslerc926e172021-05-07 16:11:35 -05002428 in a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002429
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002430 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002431
2432 The previous statement appears in the
2433 ``linux-yocto-dev.bbappend`` file, which is found in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002434 :ref:`overview-manual/development-environment:yocto project source repositories` in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002435 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2436 override is a special :term:`PACKAGE_ARCH`
2437 definition for multiple ``meta-intel`` machines.
2438
2439 .. note::
2440
2441 For a layer that supports a single BSP, the override could just be
Andrew Geissler09036742021-06-25 14:25:14 -05002442 the value of :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002443
2444 By prepending paths in ``.bbappend`` files, you allow multiple append
2445 files that reside in different layers but are used for the same
2446 recipe to correctly extend the path.
2447
Andrew Geisslerf0343792020-11-18 10:42:21 -06002448 :term:`FILESOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002449 A subset of :term:`OVERRIDES` used by the
2450 OpenEmbedded build system for creating
Andrew Geissler09036742021-06-25 14:25:14 -05002451 :term:`FILESPATH`. The :term:`FILESOVERRIDES` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002452 uses overrides to automatically extend the
2453 :term:`FILESPATH` variable. For an example of how
2454 that works, see the :term:`FILESPATH` variable
2455 description. Additionally, you find more information on how overrides
2456 are handled in the
2457 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2458 section of the BitBake User Manual.
2459
Andrew Geissler09036742021-06-25 14:25:14 -05002460 By default, the :term:`FILESOVERRIDES` variable is defined as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002461
2462 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2463
2464 .. note::
2465
Andrew Geissler09036742021-06-25 14:25:14 -05002466 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002467 with expected overrides and are used in an expected manner by the
2468 build system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002469
Andrew Geisslerf0343792020-11-18 10:42:21 -06002470 :term:`FILESPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002471 The default set of directories the OpenEmbedded build system uses
2472 when searching for patches and files.
2473
2474 During the build process, BitBake searches each directory in
Andrew Geissler09036742021-06-25 14:25:14 -05002475 :term:`FILESPATH` in the specified order when looking for files and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002476 patches specified by each ``file://`` URI in a recipe's
2477 :term:`SRC_URI` statements.
2478
Andrew Geissler09036742021-06-25 14:25:14 -05002479 The default value for the :term:`FILESPATH` variable is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002480 ``base.bbclass`` class found in ``meta/classes`` in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002481 :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002482
2483 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2484 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2485
2486 The
Andrew Geissler09036742021-06-25 14:25:14 -05002487 :term:`FILESPATH` variable is automatically extended using the overrides
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002488 from the :term:`FILESOVERRIDES` variable.
2489
2490 .. note::
2491
Andrew Geissler09036742021-06-25 14:25:14 -05002492 - Do not hand-edit the :term:`FILESPATH` variable. If you want the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002493 build system to look in directories other than the defaults,
Andrew Geissler09036742021-06-25 14:25:14 -05002494 extend the :term:`FILESPATH` variable by using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002495 :term:`FILESEXTRAPATHS` variable.
2496
Andrew Geissler09036742021-06-25 14:25:14 -05002497 - Be aware that the default :term:`FILESPATH` directories do not map
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002498 to directories in custom layers where append files
2499 (``.bbappend``) are used. If you want the build system to find
2500 patches or files that reside with your append files, you need
Andrew Geissler09036742021-06-25 14:25:14 -05002501 to extend the :term:`FILESPATH` variable by using the
2502 :term:`FILESEXTRAPATHS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002503
2504 You can take advantage of this searching behavior in useful ways. For
William A. Kennington IIIac69b482021-06-02 12:28:27 -07002505 example, consider a case where there is the following directory structure
2506 for general and machine-specific configurations::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002507
2508 files/defconfig
2509 files/MACHINEA/defconfig
2510 files/MACHINEB/defconfig
2511
Andrew Geissler09036742021-06-25 14:25:14 -05002512 Also in the example, the :term:`SRC_URI` statement contains
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002513 "file://defconfig". Given this scenario, you can set
2514 :term:`MACHINE` to "MACHINEA" and cause the build
Andrew Geissler09036742021-06-25 14:25:14 -05002515 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002516 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2517 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2518 build system uses files from ``files/defconfig``.
2519
2520 You can find out more about the patching process in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002521 ":ref:`overview-manual/concepts:patching`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002522 in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002523 ":ref:`dev-manual/common-tasks:patching code`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002524 the Yocto Project Development Tasks Manual. See the
2525 :ref:`ref-tasks-patch` task as well.
2526
Andrew Geisslerf0343792020-11-18 10:42:21 -06002527 :term:`FILESYSTEM_PERMS_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002528 Allows you to define your own file permissions settings table as part
2529 of your configuration for the packaging process. For example, suppose
2530 you need a consistent set of custom permissions for a set of groups
2531 and users across an entire work project. It is best to do this in the
2532 packages themselves but this is not always possible.
2533
2534 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2535 which is located in the ``meta/files`` folder in the :term:`Source Directory`.
2536 If you create your own file
2537 permissions setting table, you should place it in your layer or the
2538 distro's layer.
2539
Andrew Geissler09036742021-06-25 14:25:14 -05002540 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002541 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2542 to point to your custom
2543 ``fs-perms.txt``. You can specify more than a single file permissions
2544 setting table. The paths you specify to these files must be defined
2545 within the :term:`BBPATH` variable.
2546
2547 For guidance on how to create your own file permissions settings
2548 table file, examine the existing ``fs-perms.txt``.
2549
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002550 :term:`FIT_DESC`
2551 Specifies the description string encoded into a fitImage. The default
2552 value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
2553 class as follows::
2554
2555 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
2556
Andrew Geisslerf0343792020-11-18 10:42:21 -06002557 :term:`FIT_GENERATE_KEYS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002558 Decides whether to generate the keys for signing fitImage if they
Andrew Geissler09036742021-06-25 14:25:14 -05002559 don't already exist. The keys are created in :term:`UBOOT_SIGN_KEYDIR`.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002560 The default value is 0.
2561
Andrew Geisslerf0343792020-11-18 10:42:21 -06002562 :term:`FIT_HASH_ALG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002563 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
2564
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002565 :term:`FIT_KERNEL_COMP_ALG`
2566 Compression algorithm to use for the kernel image inside the FIT Image.
2567 At present, the only supported values are "gzip" (default) or "none"
2568 If you set this variable to anything other than "none" you may also need
2569 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
2570
2571 :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
2572 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
2573 value is ".gz".
2574
Andrew Geisslerf0343792020-11-18 10:42:21 -06002575 :term:`FIT_KEY_GENRSA_ARGS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002576 Arguments to openssl genrsa for generating RSA private key for signing
2577 fitImage. The default value is "-F4". i.e. the public exponent 65537 to
2578 use.
2579
Andrew Geisslerf0343792020-11-18 10:42:21 -06002580 :term:`FIT_KEY_REQ_ARGS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002581 Arguments to openssl req for generating certificate for signing fitImage.
2582 The default value is "-batch -new". batch for non interactive mode
2583 and new for generating new keys.
2584
Andrew Geisslerf0343792020-11-18 10:42:21 -06002585 :term:`FIT_KEY_SIGN_PKCS`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002586 Format for public key certificate used in signing fitImage.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002587 The default value is "x509".
2588
Andrew Geisslerf0343792020-11-18 10:42:21 -06002589 :term:`FIT_SIGN_ALG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002590 Specifies the signature algorithm used in creating the FIT Image.
2591 For e.g. rsa2048.
2592
Andrew Geisslerf0343792020-11-18 10:42:21 -06002593 :term:`FIT_SIGN_NUMBITS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002594 Size of private key in number of bits used in fitImage. The default
2595 value is "2048".
2596
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002597 :term:`FIT_SIGN_INDIVIDUAL`
2598 If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
2599 class will sign the kernel, dtb and ramdisk images individually in addition
2600 to signing the fitImage itself. This could be useful if you are
2601 intending to verify signatures in another context than booting via
2602 U-Boot.
2603
Andrew Geisslerf0343792020-11-18 10:42:21 -06002604 :term:`FONT_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002605 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2606 this variable specifies the runtime dependencies for font packages.
Andrew Geissler5f350902021-07-23 13:09:54 -04002607 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002608
Andrew Geisslerf0343792020-11-18 10:42:21 -06002609 :term:`FONT_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002610 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2611 this variable identifies packages containing font files that need to
2612 be cached by Fontconfig. By default, the ``fontcache`` class assumes
2613 that fonts are in the recipe's main package (i.e.
2614 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
2615 need are in a package other than that main package.
2616
Andrew Geisslerf0343792020-11-18 10:42:21 -06002617 :term:`FORCE_RO_REMOVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002618 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
2619 during the generation of the root filesystem.
2620
2621 Set the variable to "1" to force the removal of these packages.
2622
Andrew Geisslerf0343792020-11-18 10:42:21 -06002623 :term:`FULL_OPTIMIZATION`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07002624 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002625 compiling an optimized system. This variable defaults to "-O2 -pipe
2626 ${DEBUG_FLAGS}".
2627
Andrew Geisslerf0343792020-11-18 10:42:21 -06002628 :term:`GCCPIE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002629 Enables Position Independent Executables (PIE) within the GNU C
2630 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
2631 Programming (ROP) attacks much more difficult to execute.
2632
2633 By default the ``security_flags.inc`` file enables PIE by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002634 variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002635
2636 GCCPIE ?= "--enable-default-pie"
2637
Andrew Geisslerf0343792020-11-18 10:42:21 -06002638 :term:`GCCVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002639 Specifies the default version of the GNU C Compiler (GCC) used for
Andrew Geissler09036742021-06-25 14:25:14 -05002640 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002641 ``meta/conf/distro/include/tcmode-default.inc`` include file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002642
2643 GCCVERSION ?= "8.%"
2644
2645 You can override this value by setting it in a
2646 configuration file such as the ``local.conf``.
2647
Andrew Geisslerf0343792020-11-18 10:42:21 -06002648 :term:`GDB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002649 The minimal command and arguments to run the GNU Debugger.
2650
Andrew Geisslerf0343792020-11-18 10:42:21 -06002651 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002652 The directory in which a local copy of a Git repository is stored
2653 when it is cloned.
2654
Andrew Geisslerf0343792020-11-18 10:42:21 -06002655 :term:`GLIBC_GENERATE_LOCALES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002656 Specifies the list of GLIBC locales to generate should you not wish
2657 to generate all LIBC locals, which can be time consuming.
2658
2659 .. note::
2660
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002661 If you specifically remove the locale ``en_US.UTF-8``, you must set
2662 :term:`IMAGE_LINGUAS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002663
Andrew Geissler09036742021-06-25 14:25:14 -05002664 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002665 By default, all locales are generated.
2666 ::
2667
2668 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
2669
Andrew Geisslerf0343792020-11-18 10:42:21 -06002670 :term:`GROUPADD_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002671 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2672 this variable specifies for a package what parameters should be
2673 passed to the ``groupadd`` command if you wish to add a group to the
2674 system when the package is installed.
2675
Andrew Geisslerc926e172021-05-07 16:11:35 -05002676 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002677
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002678 GROUPADD_PARAM:${PN} = "-r netdev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002679
2680 For information on the standard Linux shell command
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002681 ``groupadd``, see https://linux.die.net/man/8/groupadd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002682
Andrew Geisslerf0343792020-11-18 10:42:21 -06002683 :term:`GROUPMEMS_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002684 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2685 this variable specifies for a package what parameters should be
2686 passed to the ``groupmems`` command if you wish to modify the members
2687 of a group when the package is installed.
2688
2689 For information on the standard Linux shell command ``groupmems``,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002690 see https://linux.die.net/man/8/groupmems.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002691
Andrew Geisslerf0343792020-11-18 10:42:21 -06002692 :term:`GRUB_GFXSERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002693 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
2694 and serial in the boot menu. Set this variable to "1" in your
2695 ``local.conf`` or distribution configuration file to enable graphics
2696 and serial in the menu.
2697
2698 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
2699 information on how this variable is used.
2700
Andrew Geisslerf0343792020-11-18 10:42:21 -06002701 :term:`GRUB_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002702 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
2703 configuration. Use a semi-colon character (``;``) to separate
2704 multiple options.
2705
Andrew Geissler09036742021-06-25 14:25:14 -05002706 The :term:`GRUB_OPTS` variable is optional. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002707 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2708 on how this variable is used.
2709
Andrew Geisslerf0343792020-11-18 10:42:21 -06002710 :term:`GRUB_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002711 Specifies the timeout before executing the default ``LABEL`` in the
2712 GNU GRand Unified Bootloader (GRUB).
2713
Andrew Geissler09036742021-06-25 14:25:14 -05002714 The :term:`GRUB_TIMEOUT` variable is optional. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002715 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2716 on how this variable is used.
2717
Andrew Geisslerf0343792020-11-18 10:42:21 -06002718 :term:`GTKIMMODULES_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002719 When inheriting the
2720 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
2721 this variable specifies the packages that contain the GTK+ input
2722 method modules being installed when the modules are in packages other
2723 than the main package.
2724
Andrew Geisslerf0343792020-11-18 10:42:21 -06002725 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002726 Website where more information about the software the recipe is
2727 building can be found.
2728
Andrew Geisslerf0343792020-11-18 10:42:21 -06002729 :term:`HOST_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002730 The name of the target architecture, which is normally the same as
2731 :term:`TARGET_ARCH`. The OpenEmbedded build system
2732 supports many architectures. Here is an example list of architectures
2733 supported. This list is by no means complete as the architecture is
2734 configurable:
2735
2736 - arm
2737 - i586
2738 - x86_64
2739 - powerpc
2740 - powerpc64
2741 - mips
2742 - mipsel
2743
Andrew Geisslerf0343792020-11-18 10:42:21 -06002744 :term:`HOST_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002745 Specifies architecture-specific compiler flags that are passed to the
2746 C compiler.
2747
Andrew Geissler09036742021-06-25 14:25:14 -05002748 Default initialization for :term:`HOST_CC_ARCH` varies depending on what
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002749 is being built:
2750
2751 - :term:`TARGET_CC_ARCH` when building for the
2752 target
2753
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002754 - :term:`BUILD_CC_ARCH` when building for the build host (i.e.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002755 ``-native``)
2756
2757 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
2758 ``nativesdk-``)
2759
Andrew Geisslerf0343792020-11-18 10:42:21 -06002760 :term:`HOST_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002761 Specifies the name of the target operating system, which is normally
2762 the same as the :term:`TARGET_OS`. The variable can
2763 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
2764 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
2765 "linux-musleabi" values possible.
2766
Andrew Geisslerf0343792020-11-18 10:42:21 -06002767 :term:`HOST_PREFIX`
Andrew Geissler09036742021-06-25 14:25:14 -05002768 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002769 is normally the same as :term:`TARGET_PREFIX`.
2770
Andrew Geisslerf0343792020-11-18 10:42:21 -06002771 :term:`HOST_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002772 Specifies the system, including the architecture and the operating
2773 system, for which the build is occurring in the context of the
2774 current recipe.
2775
2776 The OpenEmbedded build system automatically sets this variable based
2777 on :term:`HOST_ARCH`,
2778 :term:`HOST_VENDOR`, and
2779 :term:`HOST_OS` variables.
2780
2781 .. note::
2782
2783 You do not need to set the variable yourself.
2784
2785 Consider these two examples:
2786
2787 - Given a native recipe on a 32-bit x86 machine running Linux, the
2788 value is "i686-linux".
2789
2790 - Given a recipe being built for a little-endian MIPS target running
2791 Linux, the value might be "mipsel-linux".
2792
Andrew Geisslerf0343792020-11-18 10:42:21 -06002793 :term:`HOSTTOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002794 A space-separated list (filter) of tools on the build host that
2795 should be allowed to be called from within build tasks. Using this
2796 filter helps reduce the possibility of host contamination. If a tool
Andrew Geissler09036742021-06-25 14:25:14 -05002797 specified in the value of :term:`HOSTTOOLS` is not found on the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002798 host, the OpenEmbedded build system produces an error and the build
2799 is not started.
2800
2801 For additional information, see
2802 :term:`HOSTTOOLS_NONFATAL`.
2803
Andrew Geisslerf0343792020-11-18 10:42:21 -06002804 :term:`HOSTTOOLS_NONFATAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002805 A space-separated list (filter) of tools on the build host that
2806 should be allowed to be called from within build tasks. Using this
2807 filter helps reduce the possibility of host contamination. Unlike
2808 :term:`HOSTTOOLS`, the OpenEmbedded build system
2809 does not produce an error if a tool specified in the value of
Andrew Geissler09036742021-06-25 14:25:14 -05002810 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
2811 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002812
Andrew Geisslerf0343792020-11-18 10:42:21 -06002813 :term:`HOST_VENDOR`
Andrew Geissler09036742021-06-25 14:25:14 -05002814 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002815 same as :term:`TARGET_VENDOR`.
2816
Andrew Geisslerf0343792020-11-18 10:42:21 -06002817 :term:`ICECC_DISABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002818 Disables or enables the ``icecc`` (Icecream) function. For more
2819 information on this function and best practices for using this
2820 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`"
2821 section.
2822
2823 Setting this variable to "1" in your ``local.conf`` disables the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002824 function::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002825
2826 ICECC_DISABLED ??= "1"
2827
Andrew Geisslerc926e172021-05-07 16:11:35 -05002828 To enable the function, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002829
2830 ICECC_DISABLED = ""
2831
Andrew Geisslerf0343792020-11-18 10:42:21 -06002832 :term:`ICECC_ENV_EXEC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002833 Points to the ``icecc-create-env`` script that you provide. This
2834 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You
2835 set this variable in your ``local.conf`` file.
2836
2837 If you do not point to a script that you provide, the OpenEmbedded
2838 build system uses the default script provided by the
2839 ``icecc-create-env.bb`` recipe, which is a modified version and not
2840 the one that comes with ``icecc``.
2841
Andrew Geisslerf0343792020-11-18 10:42:21 -06002842 :term:`ICECC_PARALLEL_MAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002843 Extra options passed to the ``make`` command during the
2844 :ref:`ref-tasks-compile` task that specify parallel
2845 compilation. This variable usually takes the form of "-j x", where x
2846 represents the maximum number of parallel threads ``make`` can run.
2847
2848 .. note::
2849
2850 The options passed affect builds on all enabled machines on the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002851 network, which are machines running the ``iceccd`` daemon.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002852
2853 If your enabled machines support multiple cores, coming up with the
2854 maximum number of parallel threads that gives you the best
2855 performance could take some experimentation since machine speed,
2856 network lag, available memory, and existing machine loads can all
2857 affect build time. Consequently, unlike the
2858 :term:`PARALLEL_MAKE` variable, there is no
Andrew Geissler09036742021-06-25 14:25:14 -05002859 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002860 performance.
2861
Andrew Geissler09036742021-06-25 14:25:14 -05002862 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002863 use it (i.e. the system does not detect and assign the number of
Andrew Geissler09036742021-06-25 14:25:14 -05002864 cores as is done with :term:`PARALLEL_MAKE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002865
Andrew Geisslerf0343792020-11-18 10:42:21 -06002866 :term:`ICECC_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002867 The location of the ``icecc`` binary. You can set this variable in
2868 your ``local.conf`` file. If your ``local.conf`` file does not define
2869 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts
2870 to define it by locating ``icecc`` using ``which``.
2871
Andrew Geisslerf0343792020-11-18 10:42:21 -06002872 :term:`ICECC_USER_CLASS_BL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002873 Identifies user classes that you do not want the Icecream distributed
2874 compile support to consider. This variable is used by the
2875 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2876 your ``local.conf`` file.
2877
2878 When you list classes using this variable, you are "blacklisting"
2879 them from distributed compilation across remote hosts. Any classes
2880 you list will be distributed and compiled locally.
2881
Andrew Geisslerf0343792020-11-18 10:42:21 -06002882 :term:`ICECC_USER_PACKAGE_BL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002883 Identifies user recipes that you do not want the Icecream distributed
2884 compile support to consider. This variable is used by the
2885 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2886 your ``local.conf`` file.
2887
2888 When you list packages using this variable, you are "blacklisting"
2889 them from distributed compilation across remote hosts. Any packages
2890 you list will be distributed and compiled locally.
2891
Andrew Geisslerf0343792020-11-18 10:42:21 -06002892 :term:`ICECC_USER_PACKAGE_WL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002893 Identifies user recipes that use an empty
2894 :term:`PARALLEL_MAKE` variable that you want to
2895 force remote distributed compilation on using the Icecream
2896 distributed compile support. This variable is used by the
2897 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2898 your ``local.conf`` file.
2899
Andrew Geisslerf0343792020-11-18 10:42:21 -06002900 :term:`IMAGE_BASENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002901 The base name of image output files. This variable defaults to the
2902 recipe name (``${``\ :term:`PN`\ ``}``).
2903
Andrew Geisslerf0343792020-11-18 10:42:21 -06002904 :term:`IMAGE_EFI_BOOT_FILES`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002905 A space-separated list of files installed into the boot partition
2906 when preparing an image using the Wic tool with the
2907 ``bootimg-efi`` source plugin. By default,
2908 the files are
2909 installed under the same name as the source files. To change the
2910 installed name, separate it from the original name with a semi-colon
2911 (;). Source files need to be located in
2912 :term:`DEPLOY_DIR_IMAGE`. Here are two
Andrew Geisslerc926e172021-05-07 16:11:35 -05002913 examples::
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002914
2915 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
2916 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
2917
2918 Alternatively, source files can be picked up using a glob pattern. In
2919 this case, the destination file must have the same name as the base
2920 name of the source file path. To install files into a directory
2921 within the target location, pass its name after a semi-colon (;).
Andrew Geisslerc926e172021-05-07 16:11:35 -05002922 Here are two examples::
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002923
2924 IMAGE_EFI_BOOT_FILES = "boot/loader/*"
2925 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
2926
2927 The first example
2928 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
2929 into the root of the target partition. The second example installs
2930 the same files into a ``boot`` directory within the target partition.
2931
2932 You can find information on how to use the Wic tool in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002933 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002934 section of the Yocto Project Development Tasks Manual. Reference
2935 material for Wic is located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002936 ":doc:`/ref-manual/kickstart`" chapter.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002937
Andrew Geisslerf0343792020-11-18 10:42:21 -06002938 :term:`IMAGE_BOOT_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002939 A space-separated list of files installed into the boot partition
2940 when preparing an image using the Wic tool with the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002941 ``bootimg-partition`` source plugin. By default,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002942 the files are
2943 installed under the same name as the source files. To change the
2944 installed name, separate it from the original name with a semi-colon
2945 (;). Source files need to be located in
2946 :term:`DEPLOY_DIR_IMAGE`. Here are two
Andrew Geisslerc926e172021-05-07 16:11:35 -05002947 examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002948
2949 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2950 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
2951
2952 Alternatively, source files can be picked up using a glob pattern. In
2953 this case, the destination file must have the same name as the base
2954 name of the source file path. To install files into a directory
2955 within the target location, pass its name after a semi-colon (;).
Andrew Geisslerc926e172021-05-07 16:11:35 -05002956 Here are two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002957
2958 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2959 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
2960
2961 The first example
2962 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
2963 into the root of the target partition. The second example installs
2964 the same files into a ``boot`` directory within the target partition.
2965
2966 You can find information on how to use the Wic tool in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002967 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002968 section of the Yocto Project Development Tasks Manual. Reference
2969 material for Wic is located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002970 ":doc:`/ref-manual/kickstart`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002971
Andrew Geisslerf0343792020-11-18 10:42:21 -06002972 :term:`IMAGE_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002973 A list of classes that all images should inherit. You typically use
2974 this variable to specify the list of classes that register the
2975 different types of images the OpenEmbedded build system creates.
2976
Andrew Geissler09036742021-06-25 14:25:14 -05002977 The default value for :term:`IMAGE_CLASSES` is ``image_types``. You can
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002978 set this variable in your ``local.conf`` or in a distribution
2979 configuration file.
2980
2981 For more information, see ``meta/classes/image_types.bbclass`` in the
2982 :term:`Source Directory`.
2983
Andrew Geisslerf0343792020-11-18 10:42:21 -06002984 :term:`IMAGE_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002985 Specifies the command to create the image file for a specific image
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002986 type, which corresponds to the value set in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002987 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
2988 ``btrfs``, and so forth). When setting this variable, you should use
Andrew Geisslerc926e172021-05-07 16:11:35 -05002989 an override for the associated type. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002990
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002991 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
Andrew Geissler09036742021-06-25 14:25:14 -05002992 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002993 ${EXTRA_IMAGECMD}"
2994
2995 You typically do not need to set this variable unless you are adding
2996 support for a new image type. For more examples on how to set this
2997 variable, see the :ref:`image_types <ref-classes-image_types>`
2998 class file, which is ``meta/classes/image_types.bbclass``.
2999
Andrew Geisslerf0343792020-11-18 10:42:21 -06003000 :term:`IMAGE_DEVICE_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003001 Specifies one or more files that contain custom device tables that
3002 are passed to the ``makedevs`` command as part of creating an image.
3003 These files list basic device nodes that should be created under
Andrew Geissler09036742021-06-25 14:25:14 -05003004 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003005 ``files/device_table-minimal.txt`` is used, which is located by
3006 :term:`BBPATH`. For details on how you should write
3007 device table files, see ``meta/files/device_table-minimal.txt`` as an
3008 example.
3009
Andrew Geisslerf0343792020-11-18 10:42:21 -06003010 :term:`IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003011 The primary list of features to include in an image. Typically, you
3012 configure this variable in an image recipe. Although you can use this
3013 variable from your ``local.conf`` file, which is found in the
3014 :term:`Build Directory`, best practices dictate that you do
3015 not.
3016
3017 .. note::
3018
3019 To enable extra features from outside the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003020 :term:`EXTRA_IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003021
3022 For a list of image features that ships with the Yocto Project, see
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003023 the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003024
3025 For an example that shows how to customize your image by using this
Andrew Geissler09209ee2020-12-13 08:44:15 -06003026 variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003027 section in the Yocto Project Development Tasks Manual.
3028
Andrew Geisslerf0343792020-11-18 10:42:21 -06003029 :term:`IMAGE_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003030 Specifies the formats the OpenEmbedded build system uses during the
3031 build when creating the root filesystem. For example, setting
Andrew Geissler09036742021-06-25 14:25:14 -05003032 :term:`IMAGE_FSTYPES` as follows causes the build system to create root
Andrew Geisslerc926e172021-05-07 16:11:35 -05003033 filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003034
3035 IMAGE_FSTYPES = "ext3 tar.bz2"
3036
3037 For the complete list of supported image formats from which you can
3038 choose, see :term:`IMAGE_TYPES`.
3039
3040 .. note::
3041
3042 - If an image recipe uses the "inherit image" line and you are
Andrew Geissler09036742021-06-25 14:25:14 -05003043 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
Andrew Geissler5f350902021-07-23 13:09:54 -04003044 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003045
3046 - Due to the way the OpenEmbedded build system processes this
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003047 variable, you cannot update its contents by using ``:append``
3048 or ``:prepend``. You must use the ``+=`` operator to add one or
Andrew Geissler09036742021-06-25 14:25:14 -05003049 more options to the :term:`IMAGE_FSTYPES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003050
Andrew Geisslerf0343792020-11-18 10:42:21 -06003051 :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003052 Used by recipes to specify the packages to install into an image
3053 through the :ref:`image <ref-classes-image>` class. Use the
Andrew Geissler09036742021-06-25 14:25:14 -05003054 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003055
Andrew Geissler09036742021-06-25 14:25:14 -05003056 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003057 install into an image through ``image.bbclass``. Additionally,
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003058 there are "helper" classes such as the
3059 :ref:`core-image <ref-classes-core-image>` class which can
Andrew Geissler09036742021-06-25 14:25:14 -05003060 take lists used with :term:`IMAGE_FEATURES` and turn them into
3061 auto-generated entries in :term:`IMAGE_INSTALL` in addition to its
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003062 default contents.
3063
Andrew Geisslerc926e172021-05-07 16:11:35 -05003064 When you use this variable, it is best to use it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003065
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003066 IMAGE_INSTALL:append = " package-name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003067
3068 Be sure to include the space
3069 between the quotation character and the start of the package name or
3070 names.
3071
3072 .. note::
3073
3074 - When working with a
Andrew Geissler09209ee2020-12-13 08:44:15 -06003075 :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Andrew Geissler09036742021-06-25 14:25:14 -05003076 image, do not use the :term:`IMAGE_INSTALL` variable to specify
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003077 packages for installation. Instead, use the
3078 :term:`PACKAGE_INSTALL` variable, which
3079 allows the initial RAM filesystem (initramfs) recipe to use a
Andrew Geissler09036742021-06-25 14:25:14 -05003080 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003081 For information on creating an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003082 ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003083 section in the Yocto Project Development Tasks Manual.
3084
Andrew Geissler09036742021-06-25 14:25:14 -05003085 - Using :term:`IMAGE_INSTALL` with the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003086 :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003087 BitBake operator within the ``/conf/local.conf`` file or from
3088 within an image recipe is not recommended. Use of this operator
3089 in these ways can cause ordering issues. Since
Andrew Geissler09036742021-06-25 14:25:14 -05003090 ``core-image.bbclass`` sets :term:`IMAGE_INSTALL` to a default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003091 value using the
3092 :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
Andrew Geissler09036742021-06-25 14:25:14 -05003093 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003094 results in unexpected behavior when used within
3095 ``conf/local.conf``. Furthermore, the same operation from
3096 within an image recipe may or may not succeed depending on the
3097 specific situation. In both these cases, the behavior is
3098 contrary to how most users expect the ``+=`` operator to work.
3099
Andrew Geisslerf0343792020-11-18 10:42:21 -06003100 :term:`IMAGE_LINGUAS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003101 Specifies the list of locales to install into the image during the
3102 root filesystem construction process. The OpenEmbedded build system
3103 automatically splits locale files, which are used for localization,
Andrew Geissler09036742021-06-25 14:25:14 -05003104 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003105 ensures that any locale packages that correspond to packages already
3106 selected for installation into the image are also installed. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05003107 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003108
3109 IMAGE_LINGUAS = "pt-br de-de"
3110
3111 In this example, the build system ensures any Brazilian Portuguese
3112 and German locale files that correspond to packages in the image are
3113 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
3114 ``*-locale-pt`` and ``*-locale-de``, since some software packages
3115 only provide locale files by language and not by country-specific
3116 language).
3117
3118 See the :term:`GLIBC_GENERATE_LOCALES`
3119 variable for information on generating GLIBC locales.
3120
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003121
3122 :term:`IMAGE_LINK_NAME`
3123 The name of the output image symlink (which does not include
3124 the version part as :term:`IMAGE_NAME` does). The default value
3125 is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003126 variables::
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003127
3128 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}"
3129
3130
Andrew Geisslerf0343792020-11-18 10:42:21 -06003131 :term:`IMAGE_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003132 The manifest file for the image. This file lists all the installed
3133 packages that make up the image. The file contains package
Andrew Geisslerc926e172021-05-07 16:11:35 -05003134 information on a line-per-package basis as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003135
3136 packagename packagearch version
3137
Andrew Geissler09036742021-06-25 14:25:14 -05003138 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
Andrew Geisslerc926e172021-05-07 16:11:35 -05003139 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003140
Andrew Geissler09036742021-06-25 14:25:14 -05003141 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003142
3143 The location is
Andrew Geissler09036742021-06-25 14:25:14 -05003144 derived using the :term:`IMGDEPLOYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003145 and :term:`IMAGE_NAME` variables. You can find
Andrew Geissler09209ee2020-12-13 08:44:15 -06003146 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003147 section in the Yocto Project Overview and Concepts Manual.
3148
Andrew Geisslerf0343792020-11-18 10:42:21 -06003149 :term:`IMAGE_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003150 The name of the output image files minus the extension. This variable
3151 is derived using the :term:`IMAGE_BASENAME`,
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003152 :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003153 variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003154
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003155 IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3156
3157 :term:`IMAGE_NAME_SUFFIX`
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003158 Suffix used for the image output filename - defaults to ``".rootfs"``
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003159 to distinguish the image file from other files created during image
3160 building; however if this suffix is redundant or not desired you can
3161 clear the value of this variable (set the value to ""). For example,
3162 this is typically cleared in initramfs image recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003163
Andrew Geisslerf0343792020-11-18 10:42:21 -06003164 :term:`IMAGE_OVERHEAD_FACTOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003165 Defines a multiplier that the build system applies to the initial
3166 image size for cases when the multiplier times the returned disk
3167 usage value for the image is greater than the sum of
Andrew Geissler09036742021-06-25 14:25:14 -05003168 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003169 the multiplier applied to the initial image size creates free disk
3170 space in the image as overhead. By default, the build process uses a
3171 multiplier of 1.3 for this variable. This default value results in
3172 30% free disk space added to the image when this method is used to
3173 determine the final generated image size. You should be aware that
3174 post install scripts and the package management system uses disk
3175 space inside this overhead area. Consequently, the multiplier does
3176 not produce an image with all the theoretical free disk space. See
Andrew Geissler09036742021-06-25 14:25:14 -05003177 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003178 determines the overall image size.
3179
3180 The default 30% free disk space typically gives the image enough room
3181 to boot and allows for basic post installs while still leaving a
3182 small amount of free disk space. If 30% free space is inadequate, you
3183 can increase the default value. For example, the following setting
Andrew Geisslerc926e172021-05-07 16:11:35 -05003184 gives you 50% free space added to the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003185
3186 IMAGE_OVERHEAD_FACTOR = "1.5"
3187
3188 Alternatively, you can ensure a specific amount of free disk space is
Andrew Geissler09036742021-06-25 14:25:14 -05003189 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003190 variable.
3191
Andrew Geisslerf0343792020-11-18 10:42:21 -06003192 :term:`IMAGE_PKGTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003193 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
3194 OpenEmbedded build system. The variable is defined appropriately by
3195 the :ref:`package_deb <ref-classes-package_deb>`,
3196 :ref:`package_rpm <ref-classes-package_rpm>`,
3197 :ref:`package_ipk <ref-classes-package_ipk>`, or
3198 :ref:`package_tar <ref-classes-package_tar>` class.
3199
3200 .. note::
3201
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003202 The ``package_tar`` class is broken and is not supported. It is
3203 recommended that you do not use it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003204
3205 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
Andrew Geissler09036742021-06-25 14:25:14 -05003206 :ref:`image <ref-classes-image>` classes use the :term:`IMAGE_PKGTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003207 for packaging up images and SDKs.
3208
Andrew Geissler09036742021-06-25 14:25:14 -05003209 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003210 variable is set indirectly through the appropriate
3211 :ref:`package_* <ref-classes-package>` class using the
3212 :term:`PACKAGE_CLASSES` variable. The
3213 OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
3214 or IPK) that appears with the variable
3215
3216 .. note::
3217
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003218 Files using the ``.tar`` format are never used as a substitute
3219 packaging format for DEB, RPM, and IPK formatted files for your image
3220 or SDK.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003221
Andrew Geisslerf0343792020-11-18 10:42:21 -06003222 :term:`IMAGE_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003223 Specifies a list of functions to call once the OpenEmbedded build
3224 system creates the final image output files. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05003225 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003226
3227 IMAGE_POSTPROCESS_COMMAND += "function; ... "
3228
3229 If you need to pass the root filesystem path to a command within the
3230 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3231 directory that becomes the root filesystem image. See the
3232 :term:`IMAGE_ROOTFS` variable for more
3233 information.
3234
Andrew Geisslerf0343792020-11-18 10:42:21 -06003235 :term:`IMAGE_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003236 Specifies a list of functions to call before the OpenEmbedded build
3237 system creates the final image output files. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05003238 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003239
3240 IMAGE_PREPROCESS_COMMAND += "function; ... "
3241
3242 If you need to pass the root filesystem path to a command within the
3243 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3244 directory that becomes the root filesystem image. See the
3245 :term:`IMAGE_ROOTFS` variable for more
3246 information.
3247
Andrew Geisslerf0343792020-11-18 10:42:21 -06003248 :term:`IMAGE_ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003249 The location of the root filesystem while it is under construction
3250 (i.e. during the :ref:`ref-tasks-rootfs` task). This
3251 variable is not configurable. Do not change it.
3252
Andrew Geisslerf0343792020-11-18 10:42:21 -06003253 :term:`IMAGE_ROOTFS_ALIGNMENT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003254 Specifies the alignment for the output image file in Kbytes. If the
3255 size of the image is not a multiple of this value, then the size is
3256 rounded up to the nearest multiple of the value. The default value is
3257 "1". See :term:`IMAGE_ROOTFS_SIZE` for
3258 additional information.
3259
Andrew Geisslerf0343792020-11-18 10:42:21 -06003260 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003261 Defines additional free disk space created in the image in Kbytes. By
3262 default, this variable is set to "0". This free disk space is added
3263 to the image after the build system determines the image size as
Andrew Geissler09036742021-06-25 14:25:14 -05003264 described in :term:`IMAGE_ROOTFS_SIZE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003265
3266 This variable is particularly useful when you want to ensure that a
3267 specific amount of free disk space is available on a device after an
3268 image is installed and running. For example, to be sure 5 Gbytes of
Andrew Geisslerc926e172021-05-07 16:11:35 -05003269 free disk space is available, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003270
3271 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3272
3273 For example, the Yocto Project Build Appliance specifically requests
Andrew Geisslerc926e172021-05-07 16:11:35 -05003274 40 Gbytes of extra space with the line::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003275
3276 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3277
Andrew Geisslerf0343792020-11-18 10:42:21 -06003278 :term:`IMAGE_ROOTFS_SIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003279 Defines the size in Kbytes for the generated image. The OpenEmbedded
3280 build system determines the final size for the generated image using
3281 an algorithm that takes into account the initial disk space used for
3282 the generated image, a requested size for the image, and requested
3283 additional free disk space to be added to the image. Programatically,
3284 the build system determines the final size of the generated image as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003285 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003286
3287 if (image-du * overhead) < rootfs-size:
3288 internal-rootfs-size = rootfs-size + xspace
3289 else:
3290 internal-rootfs-size = (image-du * overhead) + xspace
3291 where:
3292 image-du = Returned value of the du command on the image.
3293 overhead = IMAGE_OVERHEAD_FACTOR
3294 rootfs-size = IMAGE_ROOTFS_SIZE
3295 internal-rootfs-size = Initial root filesystem size before any modifications.
3296 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3297
3298 See the :term:`IMAGE_OVERHEAD_FACTOR`
3299 and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3300 variables for related information.
3301
Andrew Geisslerf0343792020-11-18 10:42:21 -06003302 :term:`IMAGE_TYPEDEP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003303 Specifies a dependency from one image type on another. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05003304 example from the :ref:`image-live <ref-classes-image-live>` class::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003305
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003306 IMAGE_TYPEDEP:live = "ext3"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003307
3308 In the previous example, the variable ensures that when "live" is
3309 listed with the :term:`IMAGE_FSTYPES` variable,
3310 the OpenEmbedded build system produces an ``ext3`` image first since
3311 one of the components of the live image is an ``ext3`` formatted
3312 partition containing the root filesystem.
3313
Andrew Geisslerf0343792020-11-18 10:42:21 -06003314 :term:`IMAGE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003315 Specifies the complete list of supported image types by default:
3316
3317 - btrfs
3318 - container
3319 - cpio
3320 - cpio.gz
3321 - cpio.lz4
3322 - cpio.lzma
3323 - cpio.xz
3324 - cramfs
Andrew Geissler09036742021-06-25 14:25:14 -05003325 - erofs
3326 - erofs-lz4
3327 - erofs-lz4hc
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003328 - ext2
3329 - ext2.bz2
3330 - ext2.gz
3331 - ext2.lzma
3332 - ext3
3333 - ext3.gz
3334 - ext4
3335 - ext4.gz
3336 - f2fs
3337 - hddimg
3338 - iso
3339 - jffs2
3340 - jffs2.sum
3341 - multiubi
3342 - squashfs
3343 - squashfs-lz4
3344 - squashfs-lzo
3345 - squashfs-xz
3346 - tar
3347 - tar.bz2
3348 - tar.gz
3349 - tar.lz4
3350 - tar.xz
3351 - tar.zst
3352 - ubi
3353 - ubifs
3354 - wic
3355 - wic.bz2
3356 - wic.gz
3357 - wic.lzma
3358
3359 For more information about these types of images, see
3360 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`.
3361
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003362 :term:`IMAGE_VERSION_SUFFIX`
3363 Version suffix that is part of the default :term:`IMAGE_NAME` and
3364 :term:`KERNEL_ARTIFACT_NAME` values.
3365 Defaults to ``"-${DATETIME}"``, however you could set this to a
3366 version string that comes from your external build environment if
3367 desired, and this suffix would then be used consistently across
3368 the build artifacts.
3369
Andrew Geissler09036742021-06-25 14:25:14 -05003370 :term:`IMGDEPLOYDIR`
3371 When inheriting the :ref:`image <ref-classes-image>` class directly or
3372 through the :ref:`core-image <ref-classes-core-image>` class, the
Andrew Geissler5f350902021-07-23 13:09:54 -04003373 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
Andrew Geissler09036742021-06-25 14:25:14 -05003374 that is set in the ``image`` class as follows::
3375
3376 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
3377
3378 Recipes inheriting the ``image`` class should copy files to be
Andrew Geissler5f350902021-07-23 13:09:54 -04003379 deployed into :term:`IMGDEPLOYDIR`, and the class will take care of
Andrew Geissler09036742021-06-25 14:25:14 -05003380 copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
3381
Andrew Geisslerf0343792020-11-18 10:42:21 -06003382 :term:`INC_PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003383 Helps define the recipe revision for recipes that share a common
3384 ``include`` file. You can think of this variable as part of the
3385 recipe revision as set from within an include file.
3386
3387 Suppose, for example, you have a set of recipes that are used across
3388 several projects. And, within each of those recipes the revision (its
3389 :term:`PR` value) is set accordingly. In this case, when
3390 the revision of those recipes changes, the burden is on you to find
3391 all those recipes and be sure that they get changed to reflect the
3392 updated version of the recipe. In this scenario, it can get
3393 complicated when recipes that are used in many places and provide
3394 common functionality are upgraded to a new revision.
3395
3396 A more efficient way of dealing with this situation is to set the
Andrew Geissler09036742021-06-25 14:25:14 -05003397 :term:`INC_PR` variable inside the ``include`` files that the recipes
3398 share and then expand the :term:`INC_PR` variable within the recipes to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003399 help define the recipe revision.
3400
3401 The following provides an example that shows how to use the
Andrew Geissler09036742021-06-25 14:25:14 -05003402 :term:`INC_PR` variable given a common ``include`` file that defines the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003403 variable. Once the variable is defined in the ``include`` file, you
Andrew Geissler09036742021-06-25 14:25:14 -05003404 can use the variable to set the :term:`PR` values in each recipe. You
3405 will notice that when you set a recipe's :term:`PR` you can provide more
3406 granular revisioning by appending values to the :term:`INC_PR` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003407
3408 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3409 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3410 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3411 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3412
3413 The
3414 first line of the example establishes the baseline revision to be
3415 used for all recipes that use the ``include`` file. The remaining
3416 lines in the example are from individual recipes and show how the
Andrew Geissler09036742021-06-25 14:25:14 -05003417 :term:`PR` value is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003418
Andrew Geisslerf0343792020-11-18 10:42:21 -06003419 :term:`INCOMPATIBLE_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003420 Specifies a space-separated list of license names (as they would
3421 appear in :term:`LICENSE`) that should be excluded
3422 from the build. Recipes that provide no alternatives to listed
3423 incompatible licenses are not built. Packages that are individually
3424 licensed with the specified incompatible licenses will be deleted.
3425
3426 .. note::
3427
3428 This functionality is only regularly tested using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05003429 setting::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003430
3431 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
3432
3433
3434 Although you can use other settings, you might be required to
3435 remove dependencies on or provide alternatives to components that
3436 are required to produce a functional system image.
3437
3438 .. note::
3439
3440 It is possible to define a list of licenses that are allowed to be
3441 used instead of the licenses that are excluded. To do this, define
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003442 a variable ``COMPATIBLE_LICENSES`` with the names of the licenses
Andrew Geissler09036742021-06-25 14:25:14 -05003443 that are allowed. Then define :term:`INCOMPATIBLE_LICENSE` as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003444
3445 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
3446
3447
Andrew Geissler09036742021-06-25 14:25:14 -05003448 This will result in :term:`INCOMPATIBLE_LICENSE` containing the names of
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003449 all licenses from :term:`AVAILABLE_LICENSES` except the ones specified
3450 in ``COMPATIBLE_LICENSES``, thus only allowing the latter licenses to
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003451 be used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003452
Andrew Geisslerf0343792020-11-18 10:42:21 -06003453 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003454 Causes the named class or classes to be inherited globally. Anonymous
3455 functions in the class or classes are not executed for the base
3456 configuration and in each individual recipe. The OpenEmbedded build
Andrew Geissler09036742021-06-25 14:25:14 -05003457 system ignores changes to :term:`INHERIT` in individual recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003458
Andrew Geissler09036742021-06-25 14:25:14 -05003459 For more information on :term:`INHERIT`, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003460 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
3461 section in the Bitbake User Manual.
3462
Andrew Geisslerf0343792020-11-18 10:42:21 -06003463 :term:`INHERIT_DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003464 Lists classes that will be inherited at the distribution level. It is
3465 unlikely that you want to edit this variable.
3466
3467 The default value of the variable is set as follows in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003468 ``meta/conf/distro/defaultsetup.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003469
3470 INHERIT_DISTRO ?= "debian devshell sstate license"
3471
Andrew Geisslerf0343792020-11-18 10:42:21 -06003472 :term:`INHIBIT_DEFAULT_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003473 Prevents the default dependencies, namely the C compiler and standard
3474 C library (libc), from being added to :term:`DEPENDS`.
3475 This variable is usually used within recipes that do not require any
3476 compilation using the C compiler.
3477
3478 Set the variable to "1" to prevent the default dependencies from
3479 being added.
3480
Andrew Geisslerf0343792020-11-18 10:42:21 -06003481 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003482 Prevents the OpenEmbedded build system from splitting out debug
3483 information during packaging. By default, the build system splits out
3484 debugging information during the
3485 :ref:`ref-tasks-package` task. For more information on
3486 how debug information is split out, see the
3487 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
3488 variable.
3489
3490 To prevent the build system from splitting out debug information
Andrew Geissler09036742021-06-25 14:25:14 -05003491 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003492 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003493
3494 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
3495
Andrew Geisslerf0343792020-11-18 10:42:21 -06003496 :term:`INHIBIT_PACKAGE_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003497 If set to "1", causes the build to not strip binaries in resulting
3498 packages and prevents the ``-dbg`` package from containing the source
3499 files.
3500
3501 By default, the OpenEmbedded build system strips binaries and puts
3502 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
Andrew Geissler09036742021-06-25 14:25:14 -05003503 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003504 plan to debug in general.
3505
Andrew Geisslerf0343792020-11-18 10:42:21 -06003506 :term:`INHIBIT_SYSROOT_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003507 If set to "1", causes the build to not strip binaries in the
3508 resulting sysroot.
3509
3510 By default, the OpenEmbedded build system strips binaries in the
3511 resulting sysroot. When you specifically set the
Andrew Geissler09036742021-06-25 14:25:14 -05003512 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003513 this stripping.
3514
3515 If you want to use this variable, include the
3516 :ref:`staging <ref-classes-staging>` class. This class uses a
3517 ``sys_strip()`` function to test for the variable and acts
3518 accordingly.
3519
3520 .. note::
3521
Andrew Geissler09036742021-06-25 14:25:14 -05003522 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003523 special circumstances. For example, suppose you are building
3524 bare-metal firmware by using an external GCC toolchain. Furthermore,
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003525 even if the toolchain's binaries are strippable, there are other files
3526 needed for the build that are not strippable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003527
Andrew Geisslerf0343792020-11-18 10:42:21 -06003528 :term:`INITRAMFS_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003529 Defines the format for the output image of an initial RAM filesystem
3530 (initramfs), which is used during boot. Supported formats are the
3531 same as those supported by the
3532 :term:`IMAGE_FSTYPES` variable.
3533
3534 The default value of this variable, which is set in the
3535 ``meta/conf/bitbake.conf`` configuration file in the
3536 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
3537 initramfs mechanism, as opposed to the initial RAM filesystem
3538 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
3539 an optionally compressed cpio archive.
3540
Andrew Geisslerf0343792020-11-18 10:42:21 -06003541 :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003542 Specifies the :term:`PROVIDES` name of an image
3543 recipe that is used to build an initial RAM filesystem (initramfs)
Andrew Geissler09036742021-06-25 14:25:14 -05003544 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003545 additional recipe to be built as a dependency to whatever root
3546 filesystem recipe you might be using (e.g. ``core-image-sato``). The
3547 initramfs image recipe you provide should set
3548 :term:`IMAGE_FSTYPES` to
3549 :term:`INITRAMFS_FSTYPES`.
3550
3551 An initramfs image provides a temporary root filesystem used for
3552 early system initialization (e.g. loading of modules needed to locate
3553 and mount the "real" root filesystem).
3554
3555 .. note::
3556
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003557 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
3558 recipe in the :term:`Source Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003559 for an example initramfs recipe. To select this sample recipe as
Andrew Geissler09036742021-06-25 14:25:14 -05003560 the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003561 to "core-image-minimal-initramfs".
3562
3563 You can also find more information by referencing the
3564 ``meta-poky/conf/local.conf.sample.extended`` configuration file in
3565 the Source Directory, the :ref:`image <ref-classes-image>` class,
3566 and the :ref:`kernel <ref-classes-kernel>` class to see how to use
Andrew Geissler09036742021-06-25 14:25:14 -05003567 the :term:`INITRAMFS_IMAGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003568
Andrew Geissler09036742021-06-25 14:25:14 -05003569 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003570 initramfs image is built.
3571
3572 For more information, you can also see the
3573 :term:`INITRAMFS_IMAGE_BUNDLE`
3574 variable, which allows the generated image to be bundled inside the
3575 kernel image. Additionally, for information on creating an initramfs
Andrew Geissler09209ee2020-12-13 08:44:15 -06003576 image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003577 in the Yocto Project Development Tasks Manual.
3578
Andrew Geisslerf0343792020-11-18 10:42:21 -06003579 :term:`INITRAMFS_IMAGE_BUNDLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003580 Controls whether or not the image recipe specified by
3581 :term:`INITRAMFS_IMAGE` is run through an
3582 extra pass
3583 (:ref:`ref-tasks-bundle_initramfs`) during
3584 kernel compilation in order to build a single binary that contains
3585 both the kernel image and the initial RAM filesystem (initramfs)
3586 image. This makes use of the
3587 :term:`CONFIG_INITRAMFS_SOURCE` kernel
3588 feature.
3589
3590 .. note::
3591
3592 Using an extra compilation pass to bundle the initramfs avoids a
3593 circular dependency between the kernel recipe and the initramfs
3594 recipe should the initramfs include kernel modules. Should that be
3595 the case, the initramfs recipe depends on the kernel for the
3596 kernel modules, and the kernel depends on the initramfs recipe
3597 since the initramfs is bundled inside the kernel image.
3598
3599 The combined binary is deposited into the ``tmp/deploy`` directory,
3600 which is part of the :term:`Build Directory`.
3601
3602 Setting the variable to "1" in a configuration file causes the
3603 OpenEmbedded build system to generate a kernel image with the
Andrew Geissler09036742021-06-25 14:25:14 -05003604 initramfs specified in :term:`INITRAMFS_IMAGE` bundled within::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003605
3606 INITRAMFS_IMAGE_BUNDLE = "1"
3607
3608 By default, the
3609 :ref:`kernel <ref-classes-kernel>` class sets this variable to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05003610 null string as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003611
3612 INITRAMFS_IMAGE_BUNDLE ?= ""
3613
3614 .. note::
3615
Andrew Geissler09036742021-06-25 14:25:14 -05003616 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003617 configuration file. You cannot set the variable in a recipe file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003618
3619 See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003620 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003621 file for additional information. Also, for information on creating an
Andrew Geissler09209ee2020-12-13 08:44:15 -06003622 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003623 in the Yocto Project Development Tasks Manual.
3624
Andrew Geisslerf0343792020-11-18 10:42:21 -06003625 :term:`INITRAMFS_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003626 The link name of the initial RAM filesystem image. This variable is
3627 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003628 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003629
3630 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
3631
3632 The value of the
3633 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05003634 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003635
3636 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3637
3638 See the :term:`MACHINE` variable for additional
3639 information.
3640
Andrew Geisslerf0343792020-11-18 10:42:21 -06003641 :term:`INITRAMFS_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003642 The base name of the initial RAM filesystem image. This variable is
3643 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003644 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003645
3646 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
3647
3648 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003649 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003650
3651 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3652
Andrew Geisslerf0343792020-11-18 10:42:21 -06003653 :term:`INITRD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003654 Indicates list of filesystem images to concatenate and use as an
3655 initial RAM disk (``initrd``).
3656
Andrew Geissler09036742021-06-25 14:25:14 -05003657 The :term:`INITRD` variable is an optional variable used with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003658 :ref:`image-live <ref-classes-image-live>` class.
3659
Andrew Geisslerf0343792020-11-18 10:42:21 -06003660 :term:`INITRD_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003661 When building a "live" bootable image (i.e. when
3662 :term:`IMAGE_FSTYPES` contains "live"),
Andrew Geissler09036742021-06-25 14:25:14 -05003663 :term:`INITRD_IMAGE` specifies the image recipe that should be built to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003664 provide the initial RAM disk image. The default value is
3665 "core-image-minimal-initramfs".
3666
3667 See the :ref:`image-live <ref-classes-image-live>` class for more
3668 information.
3669
Andrew Geisslerf0343792020-11-18 10:42:21 -06003670 :term:`INITSCRIPT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003671 The filename of the initialization script as installed to
3672 ``${sysconfdir}/init.d``.
3673
3674 This variable is used in recipes when using ``update-rc.d.bbclass``.
3675 The variable is mandatory.
3676
Andrew Geisslerf0343792020-11-18 10:42:21 -06003677 :term:`INITSCRIPT_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003678 A list of the packages that contain initscripts. If multiple packages
3679 are specified, you need to append the package name to the other
3680 ``INITSCRIPT_*`` as an override.
3681
3682 This variable is used in recipes when using ``update-rc.d.bbclass``.
3683 The variable is optional and defaults to the :term:`PN`
3684 variable.
3685
Andrew Geisslerf0343792020-11-18 10:42:21 -06003686 :term:`INITSCRIPT_PARAMS`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003687 Specifies the options to pass to ``update-rc.d``. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003688
3689 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3690
3691 In this example, the script has a runlevel of 99, starts the script
3692 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3693
3694 The variable's default value is "defaults", which is set in the
3695 :ref:`update-rc.d <ref-classes-update-rc.d>` class.
3696
Andrew Geissler09036742021-06-25 14:25:14 -05003697 The value in :term:`INITSCRIPT_PARAMS` is passed through to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003698 ``update-rc.d`` command. For more information on valid parameters,
3699 please see the ``update-rc.d`` manual page at
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003700 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003701
Andrew Geisslerf0343792020-11-18 10:42:21 -06003702 :term:`INSANE_SKIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003703 Specifies the QA checks to skip for a specific package within a
3704 recipe. For example, to skip the check for symbolic link ``.so``
3705 files in the main package of a recipe, add the following to the
3706 recipe. The package name override must be used, which in this example
Andrew Geisslerc926e172021-05-07 16:11:35 -05003707 is ``${PN}``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003708
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003709 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003710
3711 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a
3712 list of the valid QA checks you can specify using this variable.
3713
Andrew Geisslerf0343792020-11-18 10:42:21 -06003714 :term:`INSTALL_TIMEZONE_FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003715 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
Andrew Geissler09036742021-06-25 14:25:14 -05003716 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003717 configuration level to disable this behavior.
3718
Andrew Geisslerf0343792020-11-18 10:42:21 -06003719 :term:`IPK_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003720 When the IPK backend is in use and package management is enabled on
3721 the target, you can use this variable to set up ``opkg`` in the
3722 target image to point to package feeds on a nominated server. Once
3723 the feed is established, you can perform installations or upgrades
3724 using the package manager at runtime.
3725
Andrew Geisslerf0343792020-11-18 10:42:21 -06003726 :term:`KARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003727 Defines the kernel architecture used when assembling the
3728 configuration. Architectures supported for this release are:
3729
3730 - powerpc
3731 - i386
3732 - x86_64
3733 - arm
3734 - qemu
3735 - mips
3736
Andrew Geissler5f350902021-07-23 13:09:54 -04003737 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003738
Andrew Geisslerf0343792020-11-18 10:42:21 -06003739 :term:`KBRANCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003740 A regular expression used by the build process to explicitly identify
3741 the kernel branch that is validated, patched, and configured during a
3742 build. You must set this variable to ensure the exact kernel branch
3743 you want is being used by the build process.
3744
3745 Values for this variable are set in the kernel's recipe file and the
3746 kernel's append file. For example, if you are using the
3747 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
Andrew Geissler09036742021-06-25 14:25:14 -05003748 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003749 is set as follows in that kernel recipe file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003750
3751 KBRANCH ?= "standard/base"
3752
3753 This variable is also used from the kernel's append file to identify
3754 the kernel branch specific to a particular machine or target
3755 hardware. Continuing with the previous kernel example, the kernel's
3756 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the
3757 BSP layer for a given machine. For example, the append file for the
3758 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA
3759 machines (``meta-yocto-bsp``) is named
3760 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
Andrew Geisslerc926e172021-05-07 16:11:35 -05003761 Here are the related statements from that append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003762
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003763 KBRANCH:genericx86 = "standard/base"
3764 KBRANCH:genericx86-64 = "standard/base"
3765 KBRANCH:edgerouter = "standard/edgerouter"
3766 KBRANCH:beaglebone = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003767
Andrew Geissler09036742021-06-25 14:25:14 -05003768 The :term:`KBRANCH` statements
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003769 identify the kernel branch to use when building for each supported
3770 BSP.
3771
Andrew Geisslerf0343792020-11-18 10:42:21 -06003772 :term:`KBUILD_DEFCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003773 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3774 class, specifies an "in-tree" kernel configuration file for use
3775 during a kernel build.
3776
3777 Typically, when using a ``defconfig`` to configure a kernel during a
3778 build, you place the file in your layer in the same manner as you
3779 would place patch files and configuration fragment files (i.e.
3780 "out-of-tree"). However, if you want to use a ``defconfig`` file that
3781 is part of the kernel tree (i.e. "in-tree"), you can use the
Andrew Geissler09036742021-06-25 14:25:14 -05003782 :term:`KBUILD_DEFCONFIG` variable and append the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003783 :term:`KMACHINE` variable to point to the
3784 ``defconfig`` file.
3785
3786 To use the variable, set it in the append file for your kernel recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05003787 using the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003788
3789 KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
3790
Andrew Geissler09036742021-06-25 14:25:14 -05003791 Here is an example from a "raspberrypi2" :term:`KMACHINE` build that uses
Andrew Geisslerc926e172021-05-07 16:11:35 -05003792 a ``defconfig`` file named "bcm2709_defconfig"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003793
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003794 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003795
Andrew Geisslerc926e172021-05-07 16:11:35 -05003796 As an alternative, you can use the following within your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003797
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003798 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003799
3800 For more
Andrew Geissler09036742021-06-25 14:25:14 -05003801 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003802 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003803 section in the Yocto Project Linux Kernel Development Manual.
3804
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003805 :term:`KCONFIG_MODE`
3806 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3807 class, specifies the kernel configuration values to use for options
3808 not specified in the provided ``defconfig`` file. Valid options are::
3809
3810 KCONFIG_MODE = "alldefconfig"
3811 KCONFIG_MODE = "allnoconfig"
3812
3813 In ``alldefconfig`` mode the options not explicitly specified will be
3814 assigned their Kconfig default value. In ``allnoconfig`` mode the
3815 options not explicitly specified will be disabled in the kernel
3816 config.
3817
Andrew Geissler09036742021-06-25 14:25:14 -05003818 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003819 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
3820 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
3821 in ``${WORKDIR}`` through a meta-layer will be handled in
3822 ``allnoconfig`` mode.
3823
3824 An "in-tree" ``defconfig`` file can be selected via the
Andrew Geissler09036742021-06-25 14:25:14 -05003825 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003826 be explicitly set.
3827
3828 A ``defconfig`` file compatible with ``allnoconfig`` mode can be
3829 generated by copying the ``.config`` file from a working Linux kernel
3830 build, renaming it to ``defconfig`` and placing it into the Linux
Andrew Geissler09036742021-06-25 14:25:14 -05003831 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003832 not need to be explicitly set.
3833
3834 A ``defconfig`` file compatible with ``alldefconfig`` mode can be
3835 generated using the
3836 :ref:`ref-tasks-savedefconfig`
3837 task and placed into the Linux kernel ``${WORKDIR}`` through your
Andrew Geissler09036742021-06-25 14:25:14 -05003838 meta-layer. Explicitely set :term:`KCONFIG_MODE`::
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003839
3840 KCONFIG_MODE = "alldefconfig"
3841
3842
Andrew Geisslerf0343792020-11-18 10:42:21 -06003843 :term:`KERNEL_ALT_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003844 Specifies an alternate kernel image type for creation in addition to
3845 the kernel image type specified using the
3846 :term:`KERNEL_IMAGETYPE` variable.
3847
Andrew Geisslerf0343792020-11-18 10:42:21 -06003848 :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003849 Specifies the name of all of the build artifacts. You can change the
Andrew Geissler09036742021-06-25 14:25:14 -05003850 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003851 variable.
3852
Andrew Geissler09036742021-06-25 14:25:14 -05003853 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003854 ``meta/classes/kernel-artifact-names.bbclass`` file, has the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003855 following default value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003856
3857 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3858
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003859 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`MACHINE`
3860 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003861
Andrew Geisslerf0343792020-11-18 10:42:21 -06003862 :term:`KERNEL_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003863 A list of classes defining kernel image types that the
3864 :ref:`kernel <ref-classes-kernel>` class should inherit. You
3865 typically append this variable to enable extended image types. An
3866 example is the "kernel-fitimage", which enables fitImage support and
3867 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register
3868 custom kernel image types with the ``kernel`` class using this
3869 variable.
3870
Andrew Geisslerf0343792020-11-18 10:42:21 -06003871 :term:`KERNEL_DEVICETREE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003872 Specifies the name of the generated Linux kernel device tree (i.e.
3873 the ``.dtb``) file.
3874
3875 .. note::
3876
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003877 There is legacy support for specifying the full path to the device
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003878 tree. However, providing just the ``.dtb`` file is preferred.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003879
3880 In order to use this variable, the
3881 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
3882 be inherited.
3883
Andrew Geisslerf0343792020-11-18 10:42:21 -06003884 :term:`KERNEL_DTB_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003885 The link name of the kernel device tree binary (DTB). This variable
3886 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003887 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003888
3889 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3890
3891 The
3892 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05003893 the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003894
3895 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3896
3897 See the :term:`MACHINE` variable for additional
3898 information.
3899
Andrew Geisslerf0343792020-11-18 10:42:21 -06003900 :term:`KERNEL_DTB_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003901 The base name of the kernel device tree binary (DTB). This variable
3902 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003903 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003904
3905 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3906
3907 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003908 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003909
3910 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3911
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003912 :term:`KERNEL_DTC_FLAGS`
3913 Specifies the ``dtc`` flags that are passed to the Linux kernel build
3914 system when generating the device trees (via ``DTC_FLAGS`` environment
3915 variable).
3916
3917 In order to use this variable, the
3918 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
3919 be inherited.
3920
Andrew Geisslerf0343792020-11-18 10:42:21 -06003921 :term:`KERNEL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003922 Specifies additional ``make`` command-line arguments the OpenEmbedded
3923 build system passes on when compiling the kernel.
3924
Andrew Geisslerf0343792020-11-18 10:42:21 -06003925 :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003926 Includes additional kernel metadata. In the OpenEmbedded build
3927 system, the default Board Support Packages (BSPs)
3928 :term:`Metadata` is provided through the
3929 :term:`KMACHINE` and :term:`KBRANCH`
Andrew Geissler09036742021-06-25 14:25:14 -05003930 variables. You can use the :term:`KERNEL_FEATURES` variable from within
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003931 the kernel recipe or kernel append file to further add metadata for
3932 all BSPs or specific BSPs.
3933
3934 The metadata you add through this variable includes config fragments
3935 and features descriptions, which usually includes patches as well as
Andrew Geissler09036742021-06-25 14:25:14 -05003936 config fragments. You typically override the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003937 variable for a specific machine. In this way, you can provide
3938 validated, but optional, sets of kernel configurations and features.
3939
3940 For example, the following example from the ``linux-yocto-rt_4.12``
3941 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
3942 as well as "virtio" configurations to all QEMU machines. The last two
Andrew Geisslerc926e172021-05-07 16:11:35 -05003943 statements add specific configurations to targeted machine types::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003944
3945 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003946 KERNEL_FEATURES:append = "${KERNEL_EXTRA_FEATURES}"
3947 KERNEL_FEATURES:append:qemuall = "cfg/virtio.scc"
3948 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
3949 KERNEL_FEATURES:append:qemux86-64 = "cfg/sound.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003950
Andrew Geisslerf0343792020-11-18 10:42:21 -06003951 :term:`KERNEL_FIT_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003952 The link name of the kernel flattened image tree (FIT) image. This
3953 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05003954 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003955
3956 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3957
3958 The value of the
3959 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05003960 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003961
3962 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3963
3964 See the :term:`MACHINE` variable for additional
3965 information.
3966
Andrew Geisslerf0343792020-11-18 10:42:21 -06003967 :term:`KERNEL_FIT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003968 The base name of the kernel flattened image tree (FIT) image. This
3969 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05003970 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003971
3972 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3973
3974 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003975 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003976
3977 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3978
Andrew Geisslerf0343792020-11-18 10:42:21 -06003979 :term:`KERNEL_IMAGE_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003980 The link name for the kernel image. This variable is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003981 ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003982
3983 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3984
3985 The value of
3986 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05003987 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003988
3989 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3990
3991 See the :term:`MACHINE` variable for additional
3992 information.
3993
Andrew Geisslerf0343792020-11-18 10:42:21 -06003994 :term:`KERNEL_IMAGE_MAXSIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003995 Specifies the maximum size of the kernel image file in kilobytes. If
Andrew Geissler09036742021-06-25 14:25:14 -05003996 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003997 checked against the set value during the
3998 :ref:`ref-tasks-sizecheck` task. The task fails if
3999 the kernel image file is larger than the setting.
4000
Andrew Geissler09036742021-06-25 14:25:14 -05004001 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004002 limited amount of space in which the kernel image must be stored.
4003
4004 By default, this variable is not set, which means the size of the
4005 kernel image is not checked.
4006
Andrew Geisslerf0343792020-11-18 10:42:21 -06004007 :term:`KERNEL_IMAGE_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004008 The base name of the kernel image. This variable is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004009 ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004010
4011 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4012
4013 The value of the
4014 :term:`KERNEL_ARTIFACT_NAME` variable,
Andrew Geisslerc926e172021-05-07 16:11:35 -05004015 which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004016
4017 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4018
Andrew Geisslerf0343792020-11-18 10:42:21 -06004019 :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004020 The type of kernel to build for a device, usually set by the machine
4021 configuration files and defaults to "zImage". This variable is used
4022 when building the kernel and is passed to ``make`` as the target to
4023 build.
4024
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004025 If you want to build an alternate kernel image type in addition to that
Andrew Geissler09036742021-06-25 14:25:14 -05004026 specified by :term:`KERNEL_IMAGETYPE`, use the :term:`KERNEL_ALT_IMAGETYPE`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004027 variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004028
Andrew Geisslerf0343792020-11-18 10:42:21 -06004029 :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004030 Lists kernel modules that need to be auto-loaded during boot.
4031
4032 .. note::
4033
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004034 This variable replaces the deprecated :term:`module_autoload`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004035 variable.
4036
Andrew Geissler09036742021-06-25 14:25:14 -05004037 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004038 can be recognized by the kernel recipe or by an out-of-tree kernel
4039 module recipe (e.g. a machine configuration file, a distribution
4040 configuration file, an append file for the recipe, or the recipe
4041 itself).
4042
Andrew Geisslerc926e172021-05-07 16:11:35 -05004043 Specify it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004044
4045 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
4046
Andrew Geissler09036742021-06-25 14:25:14 -05004047 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004048 system to populate the ``/etc/modules-load.d/modname.conf`` file with
4049 the list of modules to be auto-loaded on boot. The modules appear
4050 one-per-line in the file. Here is an example of the most common use
Andrew Geisslerc926e172021-05-07 16:11:35 -05004051 case::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004052
4053 KERNEL_MODULE_AUTOLOAD += "module_name"
4054
4055 For information on how to populate the ``modname.conf`` file with
4056 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable.
4057
Andrew Geisslerf0343792020-11-18 10:42:21 -06004058 :term:`KERNEL_MODULE_PROBECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004059 Provides a list of modules for which the OpenEmbedded build system
4060 expects to find ``module_conf_``\ modname values that specify
4061 configuration for each of the modules. For information on how to
4062 provide those module configurations, see the
4063 :term:`module_conf_* <module_conf>` variable.
4064
Andrew Geisslerf0343792020-11-18 10:42:21 -06004065 :term:`KERNEL_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004066 The location of the kernel sources. This variable is set to the value
4067 of the :term:`STAGING_KERNEL_DIR` within
4068 the :ref:`module <ref-classes-module>` class. For information on
4069 how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004070 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004071 section in the Yocto Project Linux Kernel Development Manual.
4072
4073 To help maximize compatibility with out-of-tree drivers used to build
4074 modules, the OpenEmbedded build system also recognizes and uses the
4075 :term:`KERNEL_SRC` variable, which is identical to
Andrew Geissler09036742021-06-25 14:25:14 -05004076 the :term:`KERNEL_PATH` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004077 used by external Makefiles to point to the kernel source directory.
4078
Andrew Geisslerf0343792020-11-18 10:42:21 -06004079 :term:`KERNEL_SRC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004080 The location of the kernel sources. This variable is set to the value
4081 of the :term:`STAGING_KERNEL_DIR` within
4082 the :ref:`module <ref-classes-module>` class. For information on
4083 how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004084 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004085 section in the Yocto Project Linux Kernel Development Manual.
4086
4087 To help maximize compatibility with out-of-tree drivers used to build
4088 modules, the OpenEmbedded build system also recognizes and uses the
4089 :term:`KERNEL_PATH` variable, which is identical
Andrew Geissler09036742021-06-25 14:25:14 -05004090 to the :term:`KERNEL_SRC` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004091 used by external Makefiles to point to the kernel source directory.
4092
Andrew Geisslerf0343792020-11-18 10:42:21 -06004093 :term:`KERNEL_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004094 Specifies the version of the kernel as extracted from ``version.h``
4095 or ``utsrelease.h`` within the kernel sources. Effects of setting
4096 this variable do not take affect until the kernel has been
4097 configured. Consequently, attempting to refer to this variable in
4098 contexts prior to configuration will not work.
4099
Andrew Geisslerf0343792020-11-18 10:42:21 -06004100 :term:`KERNELDEPMODDEPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004101 Specifies whether the data referenced through
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004102 :term:`PKGDATA_DIR` is needed or not.
Andrew Geissler09036742021-06-25 14:25:14 -05004103 :term:`KERNELDEPMODDEPEND` does not control whether or not that data
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004104 exists, but simply whether or not it is used. If you do not need to
Andrew Geissler09036742021-06-25 14:25:14 -05004105 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004106 ``initramfs`` recipe. Setting the variable there when the data is not
4107 needed avoids a potential dependency loop.
4108
Andrew Geisslerf0343792020-11-18 10:42:21 -06004109 :term:`KFEATURE_DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004110 Provides a short description of a configuration fragment. You use
4111 this variable in the ``.scc`` file that describes a configuration
4112 fragment file. Here is the variable used in a file named ``smp.scc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004113 to describe SMP being enabled::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004114
4115 define KFEATURE_DESCRIPTION "Enable SMP"
4116
Andrew Geisslerf0343792020-11-18 10:42:21 -06004117 :term:`KMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004118 The machine as known by the kernel. Sometimes the machine name used
4119 by the kernel does not match the machine name used by the
4120 OpenEmbedded build system. For example, the machine name that the
4121 OpenEmbedded build system understands as ``core2-32-intel-common``
4122 goes by a different name in the Linux Yocto kernel. The kernel
4123 understands that machine as ``intel-core2-32``. For cases like these,
Andrew Geissler09036742021-06-25 14:25:14 -05004124 the :term:`KMACHINE` variable maps the kernel machine name to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004125 OpenEmbedded build system machine name.
4126
4127 These mappings between different names occur in the Yocto Linux
4128 Kernel's ``meta`` branch. As an example take a look in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004129 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004130
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004131 LINUX_VERSION:core2-32-intel-common = "3.19.0"
4132 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
4133 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
4134 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
4135 KMACHINE:core2-32-intel-common = "intel-core2-32"
4136 KBRANCH:core2-32-intel-common = "standard/base"
4137 KERNEL_FEATURES:append:core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004138
Andrew Geissler09036742021-06-25 14:25:14 -05004139 The :term:`KMACHINE` statement says
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004140 that the kernel understands the machine name as "intel-core2-32".
4141 However, the OpenEmbedded build system understands the machine as
4142 "core2-32-intel-common".
4143
Andrew Geisslerf0343792020-11-18 10:42:21 -06004144 :term:`KTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004145 Defines the kernel type to be used in assembling the configuration.
4146 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06004147 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004148 section in the
4149 Yocto Project Linux Kernel Development Manual for more information on
4150 kernel types.
4151
Andrew Geissler09036742021-06-25 14:25:14 -05004152 You define the :term:`KTYPE` variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004153 :ref:`kernel-dev/advanced:bsp descriptions`. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004154 value you use must match the value used for the
4155 :term:`LINUX_KERNEL_TYPE` value used by the
4156 kernel recipe.
4157
Andrew Geisslerf0343792020-11-18 10:42:21 -06004158 :term:`LABELS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004159 Provides a list of targets for automatic configuration.
4160
4161 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
4162 information on how this variable is used.
4163
Andrew Geisslerf0343792020-11-18 10:42:21 -06004164 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004165 Lists the layers, separated by spaces, on which this recipe depends.
4166 Optionally, you can specify a specific layer version for a dependency
Andrew Geisslerc926e172021-05-07 16:11:35 -05004167 by adding it to the end of the layer name. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004168
4169 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4170
4171 In this previous example,
4172 version 3 of "anotherlayer" is compared against
4173 :term:`LAYERVERSION`\ ``_anotherlayer``.
4174
4175 An error is produced if any dependency is missing or the version
4176 numbers (if specified) do not match exactly. This variable is used in
4177 the ``conf/layer.conf`` file and must be suffixed with the name of
4178 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
4179
Andrew Geisslerf0343792020-11-18 10:42:21 -06004180 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004181 When used inside the ``layer.conf`` configuration file, this variable
4182 provides the path of the current layer. This variable is not
4183 available outside of ``layer.conf`` and references are expanded
4184 immediately when parsing of the file completes.
4185
Andrew Geisslerf0343792020-11-18 10:42:21 -06004186 :term:`LAYERRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004187 Lists the layers, separated by spaces, recommended for use with this
4188 layer.
4189
4190 Optionally, you can specify a specific layer version for a
4191 recommendation by adding the version to the end of the layer name.
Andrew Geisslerc926e172021-05-07 16:11:35 -05004192 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004193
4194 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
4195
4196 In this previous example, version 3 of "anotherlayer" is compared
4197 against ``LAYERVERSION_anotherlayer``.
4198
4199 This variable is used in the ``conf/layer.conf`` file and must be
4200 suffixed with the name of the specific layer (e.g.
4201 ``LAYERRECOMMENDS_mylayer``).
4202
Andrew Geisslerf0343792020-11-18 10:42:21 -06004203 :term:`LAYERSERIES_COMPAT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004204 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which
Andrew Geissler09036742021-06-25 14:25:14 -05004205 a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004206 allows the layer maintainer to indicate which combinations of the
4207 layer and OE-Core can be expected to work. The variable gives the
4208 system a way to detect when a layer has not been tested with new
4209 releases of OE-Core (e.g. the layer is not maintained).
4210
4211 To specify the OE-Core versions for which a layer is compatible, use
4212 this variable in your layer's ``conf/layer.conf`` configuration file.
4213 For the list, use the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -06004214 :yocto_wiki:`Release Name </Releases>` (e.g.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004215 &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004216 layer, use a space-separated list::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004217
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004218 LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004219
4220 .. note::
4221
Andrew Geissler09036742021-06-25 14:25:14 -05004222 Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004223 Compatible version 2 standard.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004224 The OpenEmbedded build system produces a warning if the variable
4225 is not set for any given layer.
4226
Andrew Geissler09209ee2020-12-13 08:44:15 -06004227 See the ":ref:`dev-manual/common-tasks:creating your own layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004228 section in the Yocto Project Development Tasks Manual.
4229
Andrew Geisslerf0343792020-11-18 10:42:21 -06004230 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004231 Optionally specifies the version of a layer as a single number. You
4232 can use this within :term:`LAYERDEPENDS` for
4233 another layer in order to depend on a specific version of the layer.
4234 This variable is used in the ``conf/layer.conf`` file and must be
4235 suffixed with the name of the specific layer (e.g.
4236 ``LAYERVERSION_mylayer``).
4237
Andrew Geisslerf0343792020-11-18 10:42:21 -06004238 :term:`LD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004239 The minimal command and arguments used to run the linker.
4240
Andrew Geisslerf0343792020-11-18 10:42:21 -06004241 :term:`LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004242 Specifies the flags to pass to the linker. This variable is exported
4243 to an environment variable and thus made visible to the software
4244 being built during the compilation step.
4245
Andrew Geissler09036742021-06-25 14:25:14 -05004246 Default initialization for :term:`LDFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004247 being built:
4248
4249 - :term:`TARGET_LDFLAGS` when building for the
4250 target
4251
4252 - :term:`BUILD_LDFLAGS` when building for the
4253 build host (i.e. ``-native``)
4254
4255 - :term:`BUILDSDK_LDFLAGS` when building for
4256 an SDK (i.e. ``nativesdk-``)
4257
Andrew Geisslerf0343792020-11-18 10:42:21 -06004258 :term:`LEAD_SONAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004259 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
4260 that the :ref:`debian <ref-classes-debian>` class applies its
4261 naming policy to given a recipe that packages multiple libraries.
4262
4263 This variable works in conjunction with the ``debian`` class.
4264
Andrew Geisslerf0343792020-11-18 10:42:21 -06004265 :term:`LIC_FILES_CHKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004266 Checksums of the license text in the recipe source code.
4267
4268 This variable tracks changes in license text of the source code
4269 files. If the license text is changed, it will trigger a build
4270 failure, which gives the developer an opportunity to review any
4271 license change.
4272
4273 This variable must be defined for all recipes (unless
4274 :term:`LICENSE` is set to "CLOSED").
4275
Andrew Geissler09209ee2020-12-13 08:44:15 -06004276 For more information, see the ":ref:`dev-manual/common-tasks:tracking license changes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004277 section in the Yocto Project Development Tasks Manual.
4278
Andrew Geisslerf0343792020-11-18 10:42:21 -06004279 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004280 The list of source licenses for the recipe. Follow these rules:
4281
4282 - Do not use spaces within individual license names.
4283
4284 - Separate license names using \| (pipe) when there is a choice
4285 between licenses.
4286
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004287 - Separate license names using & (ampersand) when there are
4288 multiple licenses for different parts of the source.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004289
4290 - You can use spaces between license names.
4291
4292 - For standard licenses, use the names of the files in
4293 ``meta/files/common-licenses/`` or the
4294 :term:`SPDXLICENSEMAP` flag names defined in
4295 ``meta/conf/licenses.conf``.
4296
Andrew Geisslerc926e172021-05-07 16:11:35 -05004297 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004298
4299 LICENSE = "LGPLv2.1 | GPLv3"
4300 LICENSE = "MPL-1 & LGPLv2.1"
4301 LICENSE = "GPLv2+"
4302
4303 The first example is from the
4304 recipes for Qt, which the user may choose to distribute under either
4305 the LGPL version 2.1 or GPL version 3. The second example is from
4306 Cairo where two licenses cover different parts of the source code.
4307 The final example is from ``sysstat``, which presents a single
4308 license.
4309
4310 You can also specify licenses on a per-package basis to handle
4311 situations where components of the output have different licenses.
4312 For example, a piece of software whose code is licensed under GPLv2
4313 but has accompanying documentation licensed under the GNU Free
Andrew Geisslerc926e172021-05-07 16:11:35 -05004314 Documentation License 1.2 could be specified as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004315
4316 LICENSE = "GFDL-1.2 & GPLv2"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004317 LICENSE:${PN} = "GPLv2"
4318 LICENSE:${PN}-doc = "GFDL-1.2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004319
Andrew Geisslerf0343792020-11-18 10:42:21 -06004320 :term:`LICENSE_CREATE_PACKAGE`
Andrew Geissler09036742021-06-25 14:25:14 -05004321 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004322 build system to create an extra package (i.e.
4323 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
4324 those packages to the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004325 :term:`RRECOMMENDS`\ ``:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004326
4327 The ``${PN}-lic`` package installs a directory in
4328 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
4329 name, and installs files in that directory that contain license and
4330 copyright information (i.e. copies of the appropriate license files
4331 from ``meta/common-licenses`` that match the licenses specified in
4332 the :term:`LICENSE` variable of the recipe metadata
4333 and copies of files marked in
4334 :term:`LIC_FILES_CHKSUM` as containing
4335 license text).
4336
4337 For related information on providing license text, see the
4338 :term:`COPY_LIC_DIRS` variable, the
4339 :term:`COPY_LIC_MANIFEST` variable, and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004340 ":ref:`dev-manual/common-tasks:providing license text`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004341 section in the Yocto Project Development Tasks Manual.
4342
Andrew Geisslerf0343792020-11-18 10:42:21 -06004343 :term:`LICENSE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004344 Specifies additional flags for a recipe you must whitelist through
4345 :term:`LICENSE_FLAGS_WHITELIST` in
4346 order to allow the recipe to be built. When providing multiple flags,
4347 separate them with spaces.
4348
4349 This value is independent of :term:`LICENSE` and is
4350 typically used to mark recipes that might require additional licenses
4351 in order to be used in a commercial product. For more information,
4352 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004353 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004354 section in the Yocto Project Development Tasks Manual.
4355
Andrew Geisslerf0343792020-11-18 10:42:21 -06004356 :term:`LICENSE_FLAGS_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004357 Lists license flags that when specified in
4358 :term:`LICENSE_FLAGS` within a recipe should not
4359 prevent that recipe from being built. This practice is otherwise
4360 known as "whitelisting" license flags. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004361 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004362 section in the Yocto Project Development Tasks Manual.
4363
Andrew Geisslerf0343792020-11-18 10:42:21 -06004364 :term:`LICENSE_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004365 Path to additional licenses used during the build. By default, the
Andrew Geissler09036742021-06-25 14:25:14 -05004366 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004367 directory that holds common license text used during the build. The
Andrew Geissler09036742021-06-25 14:25:14 -05004368 :term:`LICENSE_PATH` variable allows you to extend that location to other
Andrew Geisslerc926e172021-05-07 16:11:35 -05004369 areas that have additional licenses::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004370
4371 LICENSE_PATH += "path-to-additional-common-licenses"
4372
Andrew Geisslerf0343792020-11-18 10:42:21 -06004373 :term:`LINUX_KERNEL_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004374 Defines the kernel type to be used in assembling the configuration.
4375 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06004376 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004377 section in the
4378 Yocto Project Linux Kernel Development Manual for more information on
4379 kernel types.
4380
Andrew Geissler09036742021-06-25 14:25:14 -05004381 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004382 "standard". Together with :term:`KMACHINE`, the
Andrew Geissler09036742021-06-25 14:25:14 -05004383 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004384 the kernel tools to find the appropriate description within the
4385 kernel :term:`Metadata` with which to build out the sources
4386 and configuration.
4387
Andrew Geisslerf0343792020-11-18 10:42:21 -06004388 :term:`LINUX_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004389 The Linux version from ``kernel.org`` on which the Linux kernel image
4390 being built using the OpenEmbedded build system is based. You define
4391 this variable in the kernel recipe. For example, the
4392 ``linux-yocto-3.4.bb`` kernel recipe found in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004393 ``meta/recipes-kernel/linux`` defines the variables as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004394
4395 LINUX_VERSION ?= "3.4.24"
4396
Andrew Geissler09036742021-06-25 14:25:14 -05004397 The :term:`LINUX_VERSION` variable is used to define :term:`PV`
Andrew Geisslerc926e172021-05-07 16:11:35 -05004398 for the recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004399
4400 PV = "${LINUX_VERSION}+git${SRCPV}"
4401
Andrew Geisslerf0343792020-11-18 10:42:21 -06004402 :term:`LINUX_VERSION_EXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004403 A string extension compiled into the version string of the Linux
4404 kernel built with the OpenEmbedded build system. You define this
4405 variable in the kernel recipe. For example, the linux-yocto kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05004406 recipes all define the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004407
4408 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
4409
4410 Defining this variable essentially sets the Linux kernel
4411 configuration item ``CONFIG_LOCALVERSION``, which is visible through
4412 the ``uname`` command. Here is an example that shows the extension
Andrew Geisslerc926e172021-05-07 16:11:35 -05004413 assuming it was set as previously shown::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004414
4415 $ uname -r
4416 3.7.0-rc8-custom
4417
Andrew Geisslerf0343792020-11-18 10:42:21 -06004418 :term:`LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004419 Specifies the directory to which the OpenEmbedded build system writes
4420 overall log files. The default directory is ``${TMPDIR}/log``.
4421
4422 For the directory containing logs specific to each task, see the
4423 :term:`T` variable.
4424
Andrew Geisslerf0343792020-11-18 10:42:21 -06004425 :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004426 Specifies the target device for which the image is built. You define
Andrew Geissler09036742021-06-25 14:25:14 -05004427 :term:`MACHINE` in the ``local.conf`` file found in the
4428 :term:`Build Directory`. By default, :term:`MACHINE` is set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004429 "qemux86", which is an x86-based architecture machine to be emulated
Andrew Geisslerc926e172021-05-07 16:11:35 -05004430 using QEMU::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004431
4432 MACHINE ?= "qemux86"
4433
4434 The variable corresponds to a machine configuration file of the same
4435 name, through which machine-specific configurations are set. Thus,
Andrew Geissler09036742021-06-25 14:25:14 -05004436 when :term:`MACHINE` is set to "qemux86", the corresponding
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004437 ``qemux86.conf`` machine configuration file can be found in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004438 the :term:`Source Directory` in
4439 ``meta/conf/machine``.
4440
4441 The list of machines supported by the Yocto Project as shipped
Andrew Geisslerc926e172021-05-07 16:11:35 -05004442 include the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004443
4444 MACHINE ?= "qemuarm"
4445 MACHINE ?= "qemuarm64"
4446 MACHINE ?= "qemumips"
4447 MACHINE ?= "qemumips64"
4448 MACHINE ?= "qemuppc"
4449 MACHINE ?= "qemux86"
4450 MACHINE ?= "qemux86-64"
4451 MACHINE ?= "genericx86"
4452 MACHINE ?= "genericx86-64"
4453 MACHINE ?= "beaglebone"
4454 MACHINE ?= "edgerouter"
4455
4456 The last five are Yocto Project reference hardware
4457 boards, which are provided in the ``meta-yocto-bsp`` layer.
4458
4459 .. note::
4460
4461 Adding additional Board Support Package (BSP) layers to your
Andrew Geissler09036742021-06-25 14:25:14 -05004462 configuration adds new possible settings for :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004463
Andrew Geisslerf0343792020-11-18 10:42:21 -06004464 :term:`MACHINE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004465 Specifies the name of the machine-specific architecture. This
4466 variable is set automatically from :term:`MACHINE` or
4467 :term:`TUNE_PKGARCH`. You should not hand-edit
Andrew Geissler09036742021-06-25 14:25:14 -05004468 the :term:`MACHINE_ARCH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004469
Andrew Geisslerf0343792020-11-18 10:42:21 -06004470 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004471 A list of required machine-specific packages to install as part of
4472 the image being built. The build process depends on these packages
4473 being present. Furthermore, because this is a "machine-essential"
4474 variable, the list of packages are essential for the machine to boot.
4475 The impact of this variable affects images based on
4476 ``packagegroup-core-boot``, including the ``core-image-minimal``
4477 image.
4478
4479 This variable is similar to the
Andrew Geissler09036742021-06-25 14:25:14 -05004480 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004481 that the image being built has a build dependency on the variable's
4482 list of packages. In other words, the image will not build if a file
4483 in this list is not found.
4484
4485 As an example, suppose the machine for which you are building
4486 requires ``example-init`` to be run during boot to initialize the
4487 hardware. In this case, you would use the following in the machine's
Andrew Geisslerc926e172021-05-07 16:11:35 -05004488 ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004489
4490 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4491
Andrew Geisslerf0343792020-11-18 10:42:21 -06004492 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004493 A list of recommended machine-specific packages to install as part of
4494 the image being built. The build process does not depend on these
4495 packages being present. However, because this is a
4496 "machine-essential" variable, the list of packages are essential for
4497 the machine to boot. The impact of this variable affects images based
4498 on ``packagegroup-core-boot``, including the ``core-image-minimal``
4499 image.
4500
Andrew Geissler09036742021-06-25 14:25:14 -05004501 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004502 variable with the exception that the image being built does not have
4503 a build dependency on the variable's list of packages. In other
4504 words, the image will still build if a package in this list is not
4505 found. Typically, this variable is used to handle essential kernel
4506 modules, whose functionality may be selected to be built into the
4507 kernel rather than as a module, in which case a package will not be
4508 produced.
4509
4510 Consider an example where you have a custom kernel where a specific
4511 touchscreen driver is required for the machine to be usable. However,
4512 the driver can be built as a module or into the kernel depending on
4513 the kernel configuration. If the driver is built as a module, you
4514 want it to be installed. But, when the driver is built into the
4515 kernel, you still want the build to succeed. This variable sets up a
4516 "recommends" relationship so that in the latter case, the build will
4517 not fail due to the missing package. To accomplish this, assuming the
4518 package for the module was called ``kernel-module-ab123``, you would
Andrew Geisslerc926e172021-05-07 16:11:35 -05004519 use the following in the machine's ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004520
4521 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4522
4523 .. note::
4524
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004525 In this example, the ``kernel-module-ab123`` recipe needs to
4526 explicitly set its :term:`PACKAGES` variable to ensure that BitBake
4527 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to
4528 satisfy the dependency.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004529
4530 Some examples of these machine essentials are flash, screen,
4531 keyboard, mouse, or touchscreen drivers (depending on the machine).
4532
Andrew Geisslerf0343792020-11-18 10:42:21 -06004533 :term:`MACHINE_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004534 A list of machine-specific packages to install as part of the image
4535 being built that are not essential for the machine to boot. However,
4536 the build process for more fully-featured images depends on the
4537 packages being present.
4538
4539 This variable affects all images based on ``packagegroup-base``,
4540 which does not include the ``core-image-minimal`` or
4541 ``core-image-full-cmdline`` images.
4542
Andrew Geissler09036742021-06-25 14:25:14 -05004543 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004544 with the exception that the image being built has a build dependency
4545 on the variable's list of packages. In other words, the image will
4546 not build if a file in this list is not found.
4547
4548 An example is a machine that has WiFi capability but is not essential
4549 for the machine to boot the image. However, if you are building a
4550 more fully-featured image, you want to enable the WiFi. The package
4551 containing the firmware for the WiFi hardware is always expected to
4552 exist, so it is acceptable for the build process to depend upon
4553 finding the package. In this case, assuming the package for the
4554 firmware was called ``wifidriver-firmware``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004555 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004556
4557 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4558
Andrew Geisslerf0343792020-11-18 10:42:21 -06004559 :term:`MACHINE_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004560 A list of machine-specific packages to install as part of the image
4561 being built that are not essential for booting the machine. The image
4562 being built has no build dependency on this list of packages.
4563
4564 This variable affects only images based on ``packagegroup-base``,
4565 which does not include the ``core-image-minimal`` or
4566 ``core-image-full-cmdline`` images.
4567
Andrew Geissler09036742021-06-25 14:25:14 -05004568 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004569 with the exception that the image being built does not have a build
4570 dependency on the variable's list of packages. In other words, the
4571 image will build if a file in this list is not found.
4572
4573 An example is a machine that has WiFi capability but is not essential
4574 For the machine to boot the image. However, if you are building a
4575 more fully-featured image, you want to enable WiFi. In this case, the
4576 package containing the WiFi kernel module will not be produced if the
4577 WiFi driver is built into the kernel, in which case you still want
4578 the build to succeed instead of failing as a result of the package
4579 not being found. To accomplish this, assuming the package for the
4580 module was called ``kernel-module-examplewifi``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004581 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004582
4583 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4584
Andrew Geisslerf0343792020-11-18 10:42:21 -06004585 :term:`MACHINE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004586 Specifies the list of hardware features the
4587 :term:`MACHINE` is capable of supporting. For related
4588 information on enabling features, see the
4589 :term:`DISTRO_FEATURES`,
4590 :term:`COMBINED_FEATURES`, and
4591 :term:`IMAGE_FEATURES` variables.
4592
4593 For a list of hardware features supported by the Yocto Project as
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004594 shipped, see the ":ref:`ref-features-machine`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004595
Andrew Geisslerf0343792020-11-18 10:42:21 -06004596 :term:`MACHINE_FEATURES_BACKFILL`
Andrew Geissler09036742021-06-25 14:25:14 -05004597 Features to be added to :term:`MACHINE_FEATURES` if not also present in
4598 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004599
4600 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
4601 not intended to be user-configurable. It is best to just reference
4602 the variable to see which machine features are being backfilled for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004603 all machine configurations. See the ":ref:`ref-features-backfill`"
4604 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004605
Andrew Geisslerf0343792020-11-18 10:42:21 -06004606 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
Andrew Geissler09036742021-06-25 14:25:14 -05004607 Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be
4608 backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004609 the ":ref:`ref-features-backfill`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004610
Andrew Geisslerf0343792020-11-18 10:42:21 -06004611 :term:`MACHINEOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004612 A colon-separated list of overrides that apply to the current
4613 machine. By default, this list includes the value of
4614 :term:`MACHINE`.
4615
Andrew Geissler09036742021-06-25 14:25:14 -05004616 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004617 should apply to a machine. For example, all machines emulated in QEMU
4618 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
4619 ``meta/conf/machine/include/qemu.inc`` that prepends the following
Andrew Geissler09036742021-06-25 14:25:14 -05004620 override to :term:`MACHINEOVERRIDES`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004621
4622 MACHINEOVERRIDES =. "qemuall:"
4623
4624 This
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004625 override allows variables to be overridden for all machines emulated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004626 in QEMU, like in the following example from the ``connman-conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004627 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004628
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004629 SRC_URI:append:qemuall = " file://wired.config \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004630 file://wired-setup \
4631 "
4632
4633 The underlying mechanism behind
Andrew Geissler09036742021-06-25 14:25:14 -05004634 :term:`MACHINEOVERRIDES` is simply that it is included in the default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004635 value of :term:`OVERRIDES`.
4636
Andrew Geisslerf0343792020-11-18 10:42:21 -06004637 :term:`MAINTAINER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004638 The email address of the distribution maintainer.
4639
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05004640 :term:`METADATA_BRANCH`
4641 The branch currently checked out for the OpenEmbedded-Core layer (path
4642 determined by :term:`COREBASE`).
4643
4644 :term:`METADATA_REVISION`
4645 The revision currently checked out for the OpenEmbedded-Core layer (path
4646 determined by :term:`COREBASE`).
4647
Andrew Geisslerf0343792020-11-18 10:42:21 -06004648 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004649 Specifies additional paths from which the OpenEmbedded build system
4650 gets source code. When the build system searches for source code, it
4651 first tries the local download directory. If that location fails, the
4652 build system tries locations defined by
4653 :term:`PREMIRRORS`, the upstream source, and then
Andrew Geissler09036742021-06-25 14:25:14 -05004654 locations specified by :term:`MIRRORS` in that order.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004655
4656 Assuming your distribution (:term:`DISTRO`) is "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05004657 the default value for :term:`MIRRORS` is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004658 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
4659
Andrew Geisslerf0343792020-11-18 10:42:21 -06004660 :term:`MLPREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004661 Specifies a prefix has been added to :term:`PN` to create a
4662 special version of a recipe or package (i.e. a Multilib version). The
4663 variable is used in places where the prefix needs to be added to or
4664 removed from a the name (e.g. the :term:`BPN` variable).
Andrew Geissler09036742021-06-25 14:25:14 -05004665 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004666
4667 .. note::
4668
Andrew Geissler09036742021-06-25 14:25:14 -05004669 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation is
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004670 historical and comes from a time when ``nativesdk`` was a suffix
4671 rather than a prefix on the recipe name. When ``nativesdk`` was turned
Andrew Geissler09036742021-06-25 14:25:14 -05004672 into a prefix, it made sense to set :term:`MLPREFIX` for it as well.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004673
Andrew Geissler09036742021-06-25 14:25:14 -05004674 To help understand when :term:`MLPREFIX` might be needed, consider when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004675 :term:`BBCLASSEXTEND` is used to provide a
4676 ``nativesdk`` version of a recipe in addition to the target version.
4677 If that recipe declares build-time dependencies on tasks in other
4678 recipes by using :term:`DEPENDS`, then a dependency on
4679 "foo" will automatically get rewritten to a dependency on
4680 "nativesdk-foo". However, dependencies like the following will not
Andrew Geisslerc926e172021-05-07 16:11:35 -05004681 get rewritten automatically::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004682
4683 do_foo[depends] += "recipe:do_foo"
4684
4685 If you want such a dependency to also get transformed, you can do the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004686 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004687
4688 do_foo[depends] += "${MLPREFIX}recipe:do_foo"
4689
Andrew Geissler09036742021-06-25 14:25:14 -05004690 :term:`module_autoload`
4691 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geissler5f350902021-07-23 13:09:54 -04004692 variable. You should replace all occurrences of :term:`module_autoload`
Andrew Geissler09036742021-06-25 14:25:14 -05004693 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004694
4695 module_autoload_rfcomm = "rfcomm"
4696
Andrew Geisslerc926e172021-05-07 16:11:35 -05004697 should now be replaced with::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004698
4699 KERNEL_MODULE_AUTOLOAD += "rfcomm"
4700
4701 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
4702
Andrew Geissler09036742021-06-25 14:25:14 -05004703 :term:`module_conf`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004704 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004705 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
4706 file.
4707
4708 You can use this variable anywhere that it can be recognized by the
4709 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
4710 configuration file, a distribution configuration file, an append file
4711 for the recipe, or the recipe itself). If you use this variable, you
4712 must also be sure to list the module name in the
4713 :term:`KERNEL_MODULE_AUTOLOAD`
4714 variable.
4715
Andrew Geisslerc926e172021-05-07 16:11:35 -05004716 Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004717
4718 module_conf_module_name = "modprobe.d-syntax"
4719
4720 You must use the kernel module name override.
4721
4722 Run ``man modprobe.d`` in the shell to find out more information on
Andrew Geissler5f350902021-07-23 13:09:54 -04004723 the exact syntax you want to provide with :term:`module_conf`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004724
Andrew Geissler5f350902021-07-23 13:09:54 -04004725 Including :term:`module_conf` causes the OpenEmbedded build system to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004726 populate the ``/etc/modprobe.d/modname.conf`` file with
4727 ``modprobe.d`` syntax lines. Here is an example that adds the options
Andrew Geisslerc926e172021-05-07 16:11:35 -05004728 ``arg1`` and ``arg2`` to a module named ``mymodule``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004729
4730 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
4731
4732 For information on how to specify kernel modules to auto-load on
4733 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable.
4734
Andrew Geisslerf0343792020-11-18 10:42:21 -06004735 :term:`MODULE_TARBALL_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004736 Controls creation of the ``modules-*.tgz`` file. Set this variable to
4737 "0" to disable creation of this file, which contains all of the
4738 kernel modules resulting from a kernel build.
4739
Andrew Geisslerf0343792020-11-18 10:42:21 -06004740 :term:`MODULE_TARBALL_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004741 The link name of the kernel module tarball. This variable is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004742 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004743
4744 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4745
4746 The value
4747 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004748 same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004749
4750 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4751
4752 See the :term:`MACHINE` variable for additional information.
4753
Andrew Geisslerf0343792020-11-18 10:42:21 -06004754 :term:`MODULE_TARBALL_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004755 The base name of the kernel module tarball. This variable is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004756 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004757
4758 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4759
4760 The value of the :term:`KERNEL_ARTIFACT_NAME` variable,
Andrew Geisslerc926e172021-05-07 16:11:35 -05004761 which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004762
4763 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4764
Andrew Geisslerf0343792020-11-18 10:42:21 -06004765 :term:`MULTIMACH_TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004766 Uniquely identifies the type of the target system for which packages
4767 are being built. This variable allows output for different types of
4768 target systems to be put into different subdirectories of the same
4769 output directory.
4770
Andrew Geisslerc926e172021-05-07 16:11:35 -05004771 The default value of this variable is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004772
4773 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
4774
4775 Some classes (e.g.
4776 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the
Andrew Geissler09036742021-06-25 14:25:14 -05004777 :term:`MULTIMACH_TARGET_SYS` value.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004778
4779 See the :term:`STAMP` variable for an example. See the
4780 :term:`STAGING_DIR_TARGET` variable for more information.
4781
Andrew Geisslerf0343792020-11-18 10:42:21 -06004782 :term:`NATIVELSBSTRING`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004783 A string identifying the host distribution. Strings consist of the
4784 host distributor ID followed by the release, as reported by the
4785 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
4786 example, when running a build on Ubuntu 12.10, the value is
4787 "Ubuntu-12.10". If this information is unable to be determined, the
4788 value resolves to "Unknown".
4789
4790 This variable is used by default to isolate native shared state
4791 packages for different distributions (e.g. to avoid problems with
4792 ``glibc`` version incompatibilities). Additionally, the variable is
4793 checked against
4794 :term:`SANITY_TESTED_DISTROS` if that
4795 variable is set.
4796
Andrew Geisslerf0343792020-11-18 10:42:21 -06004797 :term:`NM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004798 The minimal command and arguments to run ``nm``.
4799
Andrew Geisslerf0343792020-11-18 10:42:21 -06004800 :term:`NO_GENERIC_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004801 Avoids QA errors when you use a non-common, non-CLOSED license in a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004802 recipe. There are packages, such as the linux-firmware package, with many
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004803 licenses that are not in any way common. Also, new licenses are added
4804 occasionally to avoid introducing a lot of common license files,
4805 which are only applicable to a specific package.
Andrew Geissler09036742021-06-25 14:25:14 -05004806 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004807 not exist in common licenses.
4808
Andrew Geissler09036742021-06-25 14:25:14 -05004809 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05004810 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004811
4812 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
4813
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004814 Here is an example that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004815 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
Andrew Geisslerc926e172021-05-07 16:11:35 -05004816 source::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004817
4818 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
4819
Andrew Geisslerf0343792020-11-18 10:42:21 -06004820 :term:`NO_RECOMMENDATIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004821 Prevents installation of all "recommended-only" packages.
4822 Recommended-only packages are packages installed only through the
4823 :term:`RRECOMMENDS` variable). Setting the
Andrew Geissler09036742021-06-25 14:25:14 -05004824 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004825
4826 NO_RECOMMENDATIONS = "1"
4827
4828 You can set this variable globally in your ``local.conf`` file or you
4829 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05004830 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004831
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004832 NO_RECOMMENDATIONS:pn-target_image = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004833
4834 It is important to realize that if you choose to not install packages
4835 using this variable and some other packages are dependent on them
4836 (i.e. listed in a recipe's :term:`RDEPENDS`
4837 variable), the OpenEmbedded build system ignores your request and
4838 will install the packages to avoid dependency errors.
4839
4840 .. note::
4841
4842 Some recommended packages might be required for certain system
4843 functionality, such as kernel modules. It is up to you to add
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004844 packages with the :term:`IMAGE_INSTALL` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004845
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004846 This variable is only supported when using the IPK and RPM
4847 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004848
4849 See the :term:`BAD_RECOMMENDATIONS` and
4850 the :term:`PACKAGE_EXCLUDE` variables for
4851 related information.
4852
Andrew Geisslerf0343792020-11-18 10:42:21 -06004853 :term:`NOAUTOPACKAGEDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004854 Disables auto package from splitting ``.debug`` files. If a recipe
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004855 requires ``FILES:${PN}-dbg`` to be set manually, the
Andrew Geissler09036742021-06-25 14:25:14 -05004856 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004857 content of the debug package. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004858
4859 NOAUTOPACKAGEDEBUG = "1"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004860 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
4861 FILES:${PN}-dbg = "/usr/src/debug/"
4862 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004863
Andrew Geissler09036742021-06-25 14:25:14 -05004864 :term:`NON_MULTILIB_RECIPES`
4865 A list of recipes that should not be built for multilib. OE-Core's
4866 ``multilib.conf`` file defines a reasonable starting point for this
4867 list with::
4868
4869 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
4870
Andrew Geisslerf0343792020-11-18 10:42:21 -06004871 :term:`OBJCOPY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004872 The minimal command and arguments to run ``objcopy``.
4873
Andrew Geisslerf0343792020-11-18 10:42:21 -06004874 :term:`OBJDUMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004875 The minimal command and arguments to run ``objdump``.
4876
Andrew Geisslerf0343792020-11-18 10:42:21 -06004877 :term:`OE_BINCONFIG_EXTRA_MANGLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004878 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
4879 this variable specifies additional arguments passed to the "sed"
4880 command. The sed command alters any paths in configuration scripts
4881 that have been set up during compilation. Inheriting this class
4882 results in all paths in these scripts being changed to point into the
4883 ``sysroots/`` directory so that all builds that use the script will
4884 use the correct directories for the cross compiling layout.
4885
4886 See the ``meta/classes/binconfig.bbclass`` in the
4887 :term:`Source Directory` for details on how this class
4888 applies these additional sed command arguments. For general
4889 information on the ``binconfig`` class, see the
4890 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
4891
Andrew Geisslerf0343792020-11-18 10:42:21 -06004892 :term:`OE_IMPORTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004893 An internal variable used to tell the OpenEmbedded build system what
4894 Python modules to import for every Python function run by the system.
4895
4896 .. note::
4897
4898 Do not set this variable. It is for internal use only.
4899
Andrew Geisslerf0343792020-11-18 10:42:21 -06004900 :term:`OE_INIT_ENV_SCRIPT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004901 The name of the build environment setup script for the purposes of
4902 setting up the environment within the extensible SDK. The default
4903 value is "oe-init-build-env".
4904
4905 If you use a custom script to set up your build environment, set the
Andrew Geissler09036742021-06-25 14:25:14 -05004906 :term:`OE_INIT_ENV_SCRIPT` variable to its name.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004907
Andrew Geisslerf0343792020-11-18 10:42:21 -06004908 :term:`OE_TERMINAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004909 Controls how the OpenEmbedded build system spawns interactive
4910 terminals on the host development system (e.g. using the BitBake
4911 command with the ``-c devshell`` command-line option). For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06004912 information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004913 the Yocto Project Development Tasks Manual.
4914
Andrew Geissler5f350902021-07-23 13:09:54 -04004915 You can use the following values for the :term:`OE_TERMINAL` variable:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004916
4917 - auto
4918 - gnome
4919 - xfce
4920 - rxvt
4921 - screen
4922 - konsole
4923 - none
4924
Andrew Geisslerf0343792020-11-18 10:42:21 -06004925 :term:`OEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004926 The directory from which the top-level build environment setup script
4927 is sourced. The Yocto Project provides a top-level build environment
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004928 setup script: :ref:`structure-core-script`. When you run this
Andrew Geissler09036742021-06-25 14:25:14 -05004929 script, the :term:`OEROOT` variable resolves to the directory that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004930 contains the script.
4931
4932 For additional information on how this variable is used, see the
4933 initialization script.
4934
Andrew Geisslerf0343792020-11-18 10:42:21 -06004935 :term:`OLDEST_KERNEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004936 Declares the oldest version of the Linux kernel that the produced
4937 binaries must support. This variable is passed into the build of the
4938 Embedded GNU C Library (``glibc``).
4939
4940 The default for this variable comes from the
4941 ``meta/conf/bitbake.conf`` configuration file. You can override this
4942 default by setting the variable in a custom distribution
4943 configuration file.
4944
Andrew Geisslerf0343792020-11-18 10:42:21 -06004945 :term:`OVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004946 A colon-separated list of overrides that currently apply. Overrides
4947 are a BitBake mechanism that allows variables to be selectively
4948 overridden at the end of parsing. The set of overrides in
Andrew Geissler09036742021-06-25 14:25:14 -05004949 :term:`OVERRIDES` represents the "state" during building, which includes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004950 the current recipe being built, the machine for which it is being
4951 built, and so forth.
4952
4953 As an example, if the string "an-override" appears as an element in
Andrew Geissler09036742021-06-25 14:25:14 -05004954 the colon-separated list in :term:`OVERRIDES`, then the following
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004955 assignment will override ``FOO`` with the value "overridden" at the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004956 end of parsing::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004957
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004958 FOO:an-override = "overridden"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004959
4960 See the
4961 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
4962 section in the BitBake User Manual for more information on the
4963 overrides mechanism.
4964
Andrew Geissler09036742021-06-25 14:25:14 -05004965 The default value of :term:`OVERRIDES` includes the values of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004966 :term:`CLASSOVERRIDE`,
4967 :term:`MACHINEOVERRIDES`, and
4968 :term:`DISTROOVERRIDES` variables. Another
4969 important override included by default is ``pn-${PN}``. This override
4970 allows variables to be set for a single recipe within configuration
Andrew Geisslerc926e172021-05-07 16:11:35 -05004971 (``.conf``) files. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004972
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004973 FOO:pn-myrecipe = "myrecipe-specific value"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004974
4975 .. note::
4976
Andrew Geissler09036742021-06-25 14:25:14 -05004977 An easy way to see what overrides apply is to search for :term:`OVERRIDES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004978 in the output of the ``bitbake -e`` command. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004979 ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004980 Project Development Tasks Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004981
Andrew Geisslerf0343792020-11-18 10:42:21 -06004982 :term:`P`
Andrew Geissler09036742021-06-25 14:25:14 -05004983 The recipe name and version. :term:`P` is comprised of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004984
4985 ${PN}-${PV}
4986
Andrew Geisslerf0343792020-11-18 10:42:21 -06004987 :term:`PACKAGE_ADD_METADATA`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05004988 This variable defines additional metadata to add to packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004989
4990 You may find you need to inject additional metadata into packages.
4991 This variable allows you to do that by setting the injected data as
4992 the value. Multiple fields can be added by splitting the content with
4993 the literal separator "\n".
4994
4995 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
4996 to do package type specific settings. It can also be made package
4997 specific by using the package name as a suffix.
4998
4999 You can find out more about applying this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005000 ":ref:`dev-manual/common-tasks:adding custom metadata to packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005001 section in the Yocto Project Development Tasks Manual.
5002
Andrew Geisslerf0343792020-11-18 10:42:21 -06005003 :term:`PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005004 The architecture of the resulting package or packages.
5005
5006 By default, the value of this variable is set to
5007 :term:`TUNE_PKGARCH` when building for the
5008 target, :term:`BUILD_ARCH` when building for the
5009 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
5010 SDK.
5011
5012 .. note::
5013
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005014 See :term:`SDK_ARCH` for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005015
5016 However, if your recipe's output packages are built specific to the
5017 target machine rather than generally for the architecture of the
Andrew Geissler09036742021-06-25 14:25:14 -05005018 machine, you should set :term:`PACKAGE_ARCH` to the value of
Andrew Geisslerc926e172021-05-07 16:11:35 -05005019 :term:`MACHINE_ARCH` in the recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005020
5021 PACKAGE_ARCH = "${MACHINE_ARCH}"
5022
Andrew Geisslerf0343792020-11-18 10:42:21 -06005023 :term:`PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005024 Specifies a list of architectures compatible with the target machine.
5025 This variable is set automatically and should not normally be
5026 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05005027 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005028 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5029
Andrew Geisslerf0343792020-11-18 10:42:21 -06005030 :term:`PACKAGE_BEFORE_PN`
Andrew Geissler09036742021-06-25 14:25:14 -05005031 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005032 that those added packages can pick up files that would normally be
5033 included in the default package.
5034
Andrew Geisslerf0343792020-11-18 10:42:21 -06005035 :term:`PACKAGE_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005036 This variable, which is set in the ``local.conf`` configuration file
5037 found in the ``conf`` folder of the
5038 :term:`Build Directory`, specifies the package manager the
5039 OpenEmbedded build system uses when packaging data.
5040
5041 You can provide one or more of the following arguments for the
5042 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk
5043 package_tar"
5044
5045 .. note::
5046
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005047 While it is a legal option, the ``package_tar``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005048 class has limited functionality due to no support for package
5049 dependencies by that backend. Therefore, it is recommended that
5050 you do not use it.
5051
5052 The build system uses only the first argument in the list as the
5053 package manager when creating your image or SDK. However, packages
5054 will be created using any additional packaging classes you specify.
Andrew Geisslerc926e172021-05-07 16:11:35 -05005055 For example, if you use the following in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005056
5057 PACKAGE_CLASSES ?= "package_ipk"
5058
5059 The OpenEmbedded build system uses
5060 the IPK package manager to create your image or SDK.
5061
5062 For information on packaging and build performance effects as a
5063 result of the package manager in use, see the
5064 ":ref:`package.bbclass <ref-classes-package>`" section.
5065
Andrew Geisslerf0343792020-11-18 10:42:21 -06005066 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005067 Determines how to split up the binary and debug information when
5068 creating ``*-dbg`` packages to be used with the GNU Project Debugger
5069 (GDB).
5070
Andrew Geissler09036742021-06-25 14:25:14 -05005071 With the :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable, you can control
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005072 where debug information, which can include or exclude source files,
5073 is stored:
5074
5075 - ".debug": Debug symbol files are placed next to the binary in a
5076 ``.debug`` directory on the target. For example, if a binary is
5077 installed into ``/bin``, the corresponding debug symbol files are
5078 installed in ``/bin/.debug``. Source files are placed in
5079 ``/usr/src/debug``.
5080
5081 - "debug-file-directory": Debug symbol files are placed under
5082 ``/usr/lib/debug`` on the target, and separated by the path from
5083 where the binary is installed. For example, if a binary is
5084 installed in ``/bin``, the corresponding debug symbols are
5085 installed in ``/usr/lib/debug/bin``. Source files are placed in
5086 ``/usr/src/debug``.
5087
5088 - "debug-without-src": The same behavior as ".debug" previously
5089 described with the exception that no source files are installed.
5090
5091 - "debug-with-srcpkg": The same behavior as ".debug" previously
5092 described with the exception that all source files are placed in a
5093 separate ``*-src`` pkg. This is the default behavior.
5094
5095 You can find out more about debugging using GDB by reading the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005096 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005097 in the Yocto Project Development Tasks Manual.
5098
Andrew Geisslerf0343792020-11-18 10:42:21 -06005099 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005100 Prevents specific packages from being installed when you are
5101 installing complementary packages.
5102
5103 You might find that you want to prevent installing certain packages
5104 when you are installing complementary packages. For example, if you
5105 are using :term:`IMAGE_FEATURES` to install
5106 ``dev-pkgs``, you might not want to install all packages from a
5107 particular multilib. If you find yourself in this situation, you can
Andrew Geissler09036742021-06-25 14:25:14 -05005108 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005109 expressions to match the packages you want to exclude.
5110
Andrew Geisslerf0343792020-11-18 10:42:21 -06005111 :term:`PACKAGE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005112 Lists packages that should not be installed into an image. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05005113 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005114
5115 PACKAGE_EXCLUDE = "package_name package_name package_name ..."
5116
5117 You can set this variable globally in your ``local.conf`` file or you
5118 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05005119 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005120
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005121 PACKAGE_EXCLUDE:pn-target_image = "package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005122
5123 If you choose to not install a package using this variable and some
5124 other package is dependent on it (i.e. listed in a recipe's
5125 :term:`RDEPENDS` variable), the OpenEmbedded build
5126 system generates a fatal installation error. Because the build system
5127 halts the process with a fatal error, you can use the variable with
5128 an iterative development process to remove specific components from a
5129 system.
5130
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005131 This variable is supported only when using the IPK and RPM
5132 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005133
5134 See the :term:`NO_RECOMMENDATIONS` and the
5135 :term:`BAD_RECOMMENDATIONS` variables for
5136 related information.
5137
Andrew Geisslerf0343792020-11-18 10:42:21 -06005138 :term:`PACKAGE_EXTRA_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005139 Specifies the list of architectures compatible with the device CPU.
5140 This variable is useful when you build for several different devices
5141 that use miscellaneous processors such as XScale and ARM926-EJS.
5142
Andrew Geisslerf0343792020-11-18 10:42:21 -06005143 :term:`PACKAGE_FEED_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005144 Optionally specifies the package architectures used as part of the
5145 package feed URIs during the build. When used, the
Andrew Geissler09036742021-06-25 14:25:14 -05005146 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005147 URI, which is constructed using the
5148 :term:`PACKAGE_FEED_URIS` and
5149 :term:`PACKAGE_FEED_BASE_PATHS`
5150 variables.
5151
5152 .. note::
5153
Andrew Geissler09036742021-06-25 14:25:14 -05005154 You can use the :term:`PACKAGE_FEED_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005155 variable to whitelist specific package architectures. If you do
5156 not need to whitelist specific architectures, which is a common
5157 case, you can omit this variable. Omitting the variable results in
5158 all available architectures for the current machine being included
5159 into remote package feeds.
5160
Andrew Geissler09036742021-06-25 14:25:14 -05005161 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5162 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005163 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005164
5165 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5166 https://example.com/packagerepos/updates"
5167 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5168 PACKAGE_FEED_ARCHS = "all core2-64"
5169
5170 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005171
5172 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005173
5174 https://example.com/packagerepos/release/rpm/all
5175 https://example.com/packagerepos/release/rpm/core2-64
5176 https://example.com/packagerepos/release/rpm-dev/all
5177 https://example.com/packagerepos/release/rpm-dev/core2-64
5178 https://example.com/packagerepos/updates/rpm/all
5179 https://example.com/packagerepos/updates/rpm/core2-64
5180 https://example.com/packagerepos/updates/rpm-dev/all
5181 https://example.com/packagerepos/updates/rpm-dev/core2-64
5182
Andrew Geisslerf0343792020-11-18 10:42:21 -06005183 :term:`PACKAGE_FEED_BASE_PATHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005184 Specifies the base path used when constructing package feed URIs. The
Andrew Geissler09036742021-06-25 14:25:14 -05005185 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005186 package feed URI used by the OpenEmbedded build system. The base path
5187 lies between the :term:`PACKAGE_FEED_URIS`
5188 and :term:`PACKAGE_FEED_ARCHS` variables.
5189
Andrew Geissler09036742021-06-25 14:25:14 -05005190 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5191 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005192 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005193
5194 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5195 https://example.com/packagerepos/updates"
5196 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5197 PACKAGE_FEED_ARCHS = "all core2-64"
5198
5199 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005200
5201 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005202
5203 https://example.com/packagerepos/release/rpm/all
5204 https://example.com/packagerepos/release/rpm/core2-64
5205 https://example.com/packagerepos/release/rpm-dev/all
5206 https://example.com/packagerepos/release/rpm-dev/core2-64
5207 https://example.com/packagerepos/updates/rpm/all
5208 https://example.com/packagerepos/updates/rpm/core2-64
5209 https://example.com/packagerepos/updates/rpm-dev/all
5210 https://example.com/packagerepos/updates/rpm-dev/core2-64
5211
Andrew Geisslerf0343792020-11-18 10:42:21 -06005212 :term:`PACKAGE_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005213 Specifies the front portion of the package feed URI used by the
5214 OpenEmbedded build system. Each final package feed URI is comprised
Andrew Geissler09036742021-06-25 14:25:14 -05005215 of :term:`PACKAGE_FEED_URIS`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005216 :term:`PACKAGE_FEED_BASE_PATHS`, and
5217 :term:`PACKAGE_FEED_ARCHS` variables.
5218
Andrew Geissler09036742021-06-25 14:25:14 -05005219 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5220 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005221 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005222
5223 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5224 https://example.com/packagerepos/updates"
5225 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5226 PACKAGE_FEED_ARCHS = "all core2-64"
5227
5228 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005229
5230 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005231
5232 https://example.com/packagerepos/release/rpm/all
5233 https://example.com/packagerepos/release/rpm/core2-64
5234 https://example.com/packagerepos/release/rpm-dev/all
5235 https://example.com/packagerepos/release/rpm-dev/core2-64
5236 https://example.com/packagerepos/updates/rpm/all
5237 https://example.com/packagerepos/updates/rpm/core2-64
5238 https://example.com/packagerepos/updates/rpm-dev/all
5239 https://example.com/packagerepos/updates/rpm-dev/core2-64
5240
Andrew Geisslerf0343792020-11-18 10:42:21 -06005241 :term:`PACKAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005242 The final list of packages passed to the package manager for
5243 installation into the image.
5244
5245 Because the package manager controls actual installation of all
Andrew Geissler09036742021-06-25 14:25:14 -05005246 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005247 not the final list of packages that are actually installed. This
5248 variable is internal to the image construction code. Consequently, in
5249 general, you should use the
5250 :term:`IMAGE_INSTALL` variable to specify
5251 packages for installation. The exception to this is when working with
Andrew Geissler09209ee2020-12-13 08:44:15 -06005252 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005253 image. When working with an initial RAM filesystem (initramfs) image,
Andrew Geissler09036742021-06-25 14:25:14 -05005254 use the :term:`PACKAGE_INSTALL` variable. For information on creating an
Andrew Geissler09209ee2020-12-13 08:44:15 -06005255 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005256 in the Yocto Project Development Tasks Manual.
5257
Andrew Geisslerf0343792020-11-18 10:42:21 -06005258 :term:`PACKAGE_INSTALL_ATTEMPTONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005259 Specifies a list of packages the OpenEmbedded build system attempts
5260 to install when creating an image. If a listed package fails to
5261 install, the build system does not generate an error. This variable
5262 is generally not user-defined.
5263
Andrew Geisslerf0343792020-11-18 10:42:21 -06005264 :term:`PACKAGE_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005265 Specifies a list of functions run to pre-process the
5266 :term:`PKGD` directory prior to splitting the files out
5267 to individual packages.
5268
Andrew Geisslerf0343792020-11-18 10:42:21 -06005269 :term:`PACKAGE_WRITE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005270 Specifies a list of dependencies for post-installation and
5271 pre-installation scripts on native/cross tools. If your
5272 post-installation or pre-installation script can execute at rootfs
5273 creation time rather than on the target but depends on a native tool
5274 in order to execute, you need to list the tools in
Andrew Geissler09036742021-06-25 14:25:14 -05005275 :term:`PACKAGE_WRITE_DEPS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005276
5277 For information on running post-installation scripts, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005278 ":ref:`dev-manual/common-tasks:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005279 section in the Yocto Project Development Tasks Manual.
5280
Andrew Geisslerf0343792020-11-18 10:42:21 -06005281 :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005282 This variable provides a means of enabling or disabling features of a
Andrew Geissler09036742021-06-25 14:25:14 -05005283 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005284 recipes when you specify features and then arguments that define
5285 feature behaviors. Here is the basic block structure (broken over
Andrew Geisslerc926e172021-05-07 16:11:35 -05005286 multiple lines for readability)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005287
5288 PACKAGECONFIG ??= "f1 f2 f3 ..."
5289 PACKAGECONFIG[f1] = "\
5290 --with-f1, \
5291 --without-f1, \
5292 build-deps-for-f1, \
5293 runtime-deps-for-f1, \
5294 runtime-recommends-for-f1, \
5295 packageconfig-conflicts-for-f1"
5296 PACKAGECONFIG[f2] = "\
5297 ... and so on and so on ...
5298
Andrew Geissler5f350902021-07-23 13:09:54 -04005299 The :term:`PACKAGECONFIG` variable itself specifies a space-separated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005300 list of the features to enable. Following the features, you can
5301 determine the behavior of each feature by providing up to six
5302 order-dependent arguments, which are separated by commas. You can
5303 omit any argument you like but must retain the separating commas. The
5304 order is important and specifies the following:
5305
5306 1. Extra arguments that should be added to the configure script
5307 argument list (:term:`EXTRA_OECONF` or
5308 :term:`PACKAGECONFIG_CONFARGS`) if
5309 the feature is enabled.
5310
Andrew Geissler09036742021-06-25 14:25:14 -05005311 2. Extra arguments that should be added to :term:`EXTRA_OECONF` or
5312 :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005313
5314 3. Additional build dependencies (:term:`DEPENDS`)
5315 that should be added if the feature is enabled.
5316
5317 4. Additional runtime dependencies (:term:`RDEPENDS`)
5318 that should be added if the feature is enabled.
5319
5320 5. Additional runtime recommendations
5321 (:term:`RRECOMMENDS`) that should be added if
5322 the feature is enabled.
5323
Andrew Geissler09036742021-06-25 14:25:14 -05005324 6. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005325 settings for this feature.
5326
Andrew Geissler09036742021-06-25 14:25:14 -05005327 Consider the following :term:`PACKAGECONFIG` block taken from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005328 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
5329 three arguments that determine the feature's behavior.
5330 ::
5331
5332 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
5333
5334 The
5335 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
5336 enabled. In this case, ``--with-gtk3`` is added to the configure
Andrew Geissler09036742021-06-25 14:25:14 -05005337 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005338 other hand, if the feature is disabled say through a ``.bbappend``
5339 file in another layer, then the second argument ``--without-gtk3`` is
5340 added to the configure script instead.
5341
Andrew Geissler09036742021-06-25 14:25:14 -05005342 The basic :term:`PACKAGECONFIG` structure previously described holds true
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005343 regardless of whether you are creating a block or changing a block.
5344 When creating a block, use the structure inside your recipe.
5345
Andrew Geissler09036742021-06-25 14:25:14 -05005346 If you want to change an existing :term:`PACKAGECONFIG` block, you can do
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005347 so one of two ways:
5348
5349 - *Append file:* Create an append file named
5350 recipename\ ``.bbappend`` in your layer and override the value of
Andrew Geissler09036742021-06-25 14:25:14 -05005351 :term:`PACKAGECONFIG`. You can either completely override the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005352 variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005353
5354 PACKAGECONFIG = "f4 f5"
5355
Andrew Geisslerc926e172021-05-07 16:11:35 -05005356 Or, you can just append the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005357
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005358 PACKAGECONFIG:append = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005359
5360 - *Configuration file:* This method is identical to changing the
5361 block through an append file except you edit your ``local.conf``
5362 or ``mydistro.conf`` file. As with append files previously
Andrew Geisslerc926e172021-05-07 16:11:35 -05005363 described, you can either completely override the variable::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005364
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005365 PACKAGECONFIG:pn-recipename = "f4 f5"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005366
Andrew Geisslerc926e172021-05-07 16:11:35 -05005367 Or, you can just amend the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005368
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005369 PACKAGECONFIG:append:pn-recipename = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005370
Andrew Geisslerf0343792020-11-18 10:42:21 -06005371 :term:`PACKAGECONFIG_CONFARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005372 A space-separated list of configuration options generated from the
5373 :term:`PACKAGECONFIG` setting.
5374
5375 Classes such as :ref:`autotools <ref-classes-autotools>` and
Andrew Geissler09036742021-06-25 14:25:14 -05005376 :ref:`cmake <ref-classes-cmake>` use :term:`PACKAGECONFIG_CONFARGS` to
5377 pass :term:`PACKAGECONFIG` options to ``configure`` and ``cmake``,
5378 respectively. If you are using :term:`PACKAGECONFIG` but not a class that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005379 handles the ``do_configure`` task, then you need to use
Andrew Geissler09036742021-06-25 14:25:14 -05005380 :term:`PACKAGECONFIG_CONFARGS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005381
Andrew Geisslerf0343792020-11-18 10:42:21 -06005382 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005383 For recipes inheriting the
5384 :ref:`packagegroup <ref-classes-packagegroup>` class, setting
Andrew Geissler09036742021-06-25 14:25:14 -05005385 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005386 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
5387 should not be automatically created by the ``packagegroup`` recipe,
5388 which is the default behavior.
5389
Andrew Geisslerf0343792020-11-18 10:42:21 -06005390 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005391 The list of packages the recipe creates. The default value is the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005392 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005393
5394 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5395
5396 During packaging, the :ref:`ref-tasks-package` task
Andrew Geissler09036742021-06-25 14:25:14 -05005397 goes through :term:`PACKAGES` and uses the :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005398 variable corresponding to each package to assign files to the
Andrew Geissler09036742021-06-25 14:25:14 -05005399 package. If a file matches the :term:`FILES` variable for more than one
5400 package in :term:`PACKAGES`, it will be assigned to the earliest
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005401 (leftmost) package.
5402
5403 Packages in the variable's list that are empty (i.e. where none of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005404 the patterns in ``FILES:``\ pkg match any files installed by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005405 :ref:`ref-tasks-install` task) are not generated,
5406 unless generation is forced through the
5407 :term:`ALLOW_EMPTY` variable.
5408
Andrew Geisslerf0343792020-11-18 10:42:21 -06005409 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005410 A promise that your recipe satisfies runtime dependencies for
5411 optional modules that are found in other recipes.
Andrew Geissler09036742021-06-25 14:25:14 -05005412 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005413 only states that they should be satisfied. For example, if a hard,
5414 runtime dependency (:term:`RDEPENDS`) of another
Andrew Geissler09036742021-06-25 14:25:14 -05005415 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005416 variable, but a package with the module name is never actually
5417 produced, then the other package will be broken. Thus, if you attempt
5418 to include that package in an image, you will get a dependency
5419 failure from the packaging system during the
5420 :ref:`ref-tasks-rootfs` task.
5421
5422 Typically, if there is a chance that such a situation can occur and
5423 the package that is not created is valid without the dependency being
5424 satisfied, then you should use :term:`RRECOMMENDS`
Andrew Geissler09036742021-06-25 14:25:14 -05005425 (a soft runtime dependency) instead of :term:`RDEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005426
Andrew Geissler09036742021-06-25 14:25:14 -05005427 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005428 you are splitting packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005429 ":ref:`dev-manual/common-tasks:handling optional module packaging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005430 section in the Yocto Project Development Tasks Manual.
5431
Andrew Geisslerf0343792020-11-18 10:42:21 -06005432 :term:`PACKAGESPLITFUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005433 Specifies a list of functions run to perform additional splitting of
5434 files into individual packages. Recipes can either prepend to this
5435 variable or prepend to the ``populate_packages`` function in order to
5436 perform additional package splitting. In either case, the function
5437 should set :term:`PACKAGES`,
5438 :term:`FILES`, :term:`RDEPENDS` and
5439 other packaging variables appropriately in order to perform the
5440 desired splitting.
5441
Andrew Geisslerf0343792020-11-18 10:42:21 -06005442 :term:`PARALLEL_MAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005443 Extra options passed to the ``make`` command during the
5444 :ref:`ref-tasks-compile` task in order to specify
5445 parallel compilation on the local build host. This variable is
5446 usually in the form "-j x", where x represents the maximum number of
5447 parallel threads ``make`` can run.
5448
5449 .. note::
5450
Andrew Geissler09036742021-06-25 14:25:14 -05005451 In order for :term:`PARALLEL_MAKE` to be effective, ``make`` must be
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005452 called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure
5453 this is to use the ``oe_runmake`` function.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005454
5455 By default, the OpenEmbedded build system automatically sets this
5456 variable to be equal to the number of cores the build system uses.
5457
5458 .. note::
5459
5460 If the software being built experiences dependency issues during
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005461 the ``do_compile`` task that result in race conditions, you can clear
Andrew Geissler09036742021-06-25 14:25:14 -05005462 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005463 information on addressing race conditions, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005464 ":ref:`dev-manual/common-tasks:debugging parallel make races`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005465 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005466
5467 For single socket systems (i.e. one CPU), you should not have to
5468 override this variable to gain optimal parallelism during builds.
5469 However, if you have very large systems that employ multiple physical
Andrew Geissler09036742021-06-25 14:25:14 -05005470 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005471 not set higher than "-j 20".
5472
5473 For more information on speeding up builds, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005474 ":ref:`dev-manual/common-tasks:speeding up a build`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005475 section in the Yocto Project Development Tasks Manual.
5476
Andrew Geisslerf0343792020-11-18 10:42:21 -06005477 :term:`PARALLEL_MAKEINST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005478 Extra options passed to the ``make install`` command during the
5479 :ref:`ref-tasks-install` task in order to specify
5480 parallel installation. This variable defaults to the value of
5481 :term:`PARALLEL_MAKE`.
5482
5483 .. note::
5484
Andrew Geissler09036742021-06-25 14:25:14 -05005485 In order for :term:`PARALLEL_MAKEINST` to be effective, ``make`` must
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005486 be called with
5487 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
5488 way to ensure this is to use the ``oe_runmake`` function.
5489
5490 If the software being built experiences dependency issues during
5491 the ``do_install`` task that result in race conditions, you can
Andrew Geissler09036742021-06-25 14:25:14 -05005492 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005493 workaround. For information on addressing race conditions, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005494 ":ref:`dev-manual/common-tasks:debugging parallel make races`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005495 section in the Yocto Project Development Tasks Manual.
5496
Andrew Geisslerf0343792020-11-18 10:42:21 -06005497 :term:`PATCHRESOLVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005498 Determines the action to take when a patch fails. You can set this
5499 variable to one of two values: "noop" and "user".
5500
5501 The default value of "noop" causes the build to simply fail when the
5502 OpenEmbedded build system cannot successfully apply a patch. Setting
5503 the value to "user" causes the build system to launch a shell and
5504 places you in the right location so that you can manually resolve the
5505 conflicts.
5506
5507 Set this variable in your ``local.conf`` file.
5508
Andrew Geisslerf0343792020-11-18 10:42:21 -06005509 :term:`PATCHTOOL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005510 Specifies the utility used to apply patches for a recipe during the
5511 :ref:`ref-tasks-patch` task. You can specify one of
5512 three utilities: "patch", "quilt", or "git". The default utility used
5513 is "quilt" except for the quilt-native recipe itself. Because the
5514 quilt tool is not available at the time quilt-native is being
5515 patched, it uses "patch".
5516
5517 If you wish to use an alternative patching tool, set the variable in
Andrew Geisslerc926e172021-05-07 16:11:35 -05005518 the recipe using one of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005519
5520 PATCHTOOL = "patch"
5521 PATCHTOOL = "quilt"
5522 PATCHTOOL = "git"
5523
Andrew Geisslerf0343792020-11-18 10:42:21 -06005524 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005525 The epoch of the recipe. By default, this variable is unset. The
5526 variable is used to make upgrades possible when the versioning scheme
5527 changes in some backwards incompatible way.
5528
Andrew Geissler09036742021-06-25 14:25:14 -05005529 :term:`PE` is the default value of the :term:`PKGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005530
Andrew Geisslerf0343792020-11-18 10:42:21 -06005531 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005532 Specifies the recipe or package name and includes all version and
5533 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
5534 ``bash-4.2-r1/``). This variable is comprised of the following:
5535 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
5536
Andrew Geisslerf0343792020-11-18 10:42:21 -06005537 :term:`PIXBUF_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005538 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
5539 class, this variable identifies packages that contain the pixbuf
5540 loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache``
5541 class assumes that the loaders are in the recipe's main package (i.e.
5542 ``${``\ :term:`PN`\ ``}``). Use this variable if the
5543 loaders you need are in a package other than that main package.
5544
Andrew Geisslerf0343792020-11-18 10:42:21 -06005545 :term:`PKG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005546 The name of the resulting package created by the OpenEmbedded build
5547 system.
5548
5549 .. note::
5550
Andrew Geissler09036742021-06-25 14:25:14 -05005551 When using the :term:`PKG` variable, you must use a package name override.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005552
5553 For example, when the :ref:`debian <ref-classes-debian>` class
5554 renames the output package, it does so by setting
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005555 ``PKG:packagename``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005556
Andrew Geisslerf0343792020-11-18 10:42:21 -06005557 :term:`PKG_CONFIG_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005558 The path to ``pkg-config`` files for the current build context.
5559 ``pkg-config`` reads this variable from the environment.
5560
Andrew Geisslerf0343792020-11-18 10:42:21 -06005561 :term:`PKGD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005562 Points to the destination directory for files to be packaged before
5563 they are split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05005564 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005565
5566 ${WORKDIR}/package
5567
5568 Do not change this default.
5569
Andrew Geisslerf0343792020-11-18 10:42:21 -06005570 :term:`PKGDATA_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005571 Points to a shared, global-state directory that holds data generated
5572 during the packaging process. During the packaging process, the
5573 :ref:`ref-tasks-packagedata` task packages data
5574 for each recipe and installs it into this temporary, shared area.
5575 This directory defaults to the following, which you should not
Andrew Geisslerc926e172021-05-07 16:11:35 -05005576 change::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005577
5578 ${STAGING_DIR_HOST}/pkgdata
5579
5580 For examples of how this data is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005581 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005582 section in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005583 ":ref:`dev-manual/common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005584 section in the Yocto Project Development Tasks Manual. For more
5585 information on the shared, global-state directory, see
5586 :term:`STAGING_DIR_HOST`.
5587
Andrew Geisslerf0343792020-11-18 10:42:21 -06005588 :term:`PKGDEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005589 Points to the parent directory for files to be packaged after they
5590 have been split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05005591 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005592
5593 ${WORKDIR}/packages-split
5594
5595 Under this directory, the build system creates directories for each
5596 package specified in :term:`PACKAGES`. Do not change
5597 this default.
5598
Andrew Geisslerf0343792020-11-18 10:42:21 -06005599 :term:`PKGDESTWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005600 Points to a temporary work area where the
5601 :ref:`ref-tasks-package` task saves package metadata.
Andrew Geissler09036742021-06-25 14:25:14 -05005602 The :term:`PKGDESTWORK` location defaults to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005603
5604 ${WORKDIR}/pkgdata
5605
5606 Do not change this default.
5607
5608 The :ref:`ref-tasks-packagedata` task copies the
Andrew Geissler09036742021-06-25 14:25:14 -05005609 package metadata from :term:`PKGDESTWORK` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005610 :term:`PKGDATA_DIR` to make it available globally.
5611
Andrew Geisslerf0343792020-11-18 10:42:21 -06005612 :term:`PKGE`
Andrew Geissler09036742021-06-25 14:25:14 -05005613 The epoch of the package(s) built by the recipe. By default, :term:`PKGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005614 is set to :term:`PE`.
5615
Andrew Geisslerf0343792020-11-18 10:42:21 -06005616 :term:`PKGR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005617 The revision of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05005618 :term:`PKGR` is set to :term:`PR`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005619
Andrew Geisslerf0343792020-11-18 10:42:21 -06005620 :term:`PKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005621 The version of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05005622 :term:`PKGV` is set to :term:`PV`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005623
Andrew Geisslerf0343792020-11-18 10:42:21 -06005624 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005625 This variable can have two separate functions depending on the
5626 context: a recipe name or a resulting package name.
5627
Andrew Geissler09036742021-06-25 14:25:14 -05005628 :term:`PN` refers to a recipe name in the context of a file used by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005629 OpenEmbedded build system as input to create a package. The name is
5630 normally extracted from the recipe file name. For example, if the
Andrew Geissler09036742021-06-25 14:25:14 -05005631 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005632 will be "expat".
5633
5634 The variable refers to a package name in the context of a file
5635 created or produced by the OpenEmbedded build system.
5636
Andrew Geissler09036742021-06-25 14:25:14 -05005637 If applicable, the :term:`PN` variable also contains any special suffix
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005638 or prefix. For example, using ``bash`` to build packages for the
Andrew Geissler5f350902021-07-23 13:09:54 -04005639 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build
Andrew Geissler09036742021-06-25 14:25:14 -05005640 packages for the target and for Multilib, :term:`PN` would be ``bash``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005641 and ``lib64-bash``, respectively.
5642
Andrew Geisslerf0343792020-11-18 10:42:21 -06005643 :term:`PNBLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005644 Lists recipes you do not want the OpenEmbedded build system to build.
5645 This variable works in conjunction with the
5646 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited
5647 globally.
5648
Andrew Geissler09036742021-06-25 14:25:14 -05005649 To prevent a recipe from being built, use the :term:`PNBLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005650 variable in your ``local.conf`` file. Here is an example that
Andrew Geisslerc926e172021-05-07 16:11:35 -05005651 prevents ``myrecipe`` from being built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005652
5653 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5654
Andrew Geisslerf0343792020-11-18 10:42:21 -06005655 :term:`POPULATE_SDK_POST_HOST_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005656 Specifies a list of functions to call once the OpenEmbedded build
5657 system has created the host part of the SDK. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05005658 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005659
5660 POPULATE_SDK_POST_HOST_COMMAND += "function; ... "
5661
5662 If you need to pass the SDK path to a command within a function, you
5663 can use ``${SDK_DIR}``, which points to the parent directory used by
5664 the OpenEmbedded build system when creating SDK output. See the
5665 :term:`SDK_DIR` variable for more information.
5666
Andrew Geisslerf0343792020-11-18 10:42:21 -06005667 :term:`POPULATE_SDK_POST_TARGET_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005668 Specifies a list of functions to call once the OpenEmbedded build
5669 system has created the target part of the SDK. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05005670 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005671
5672 POPULATE_SDK_POST_TARGET_COMMAND += "function; ... "
5673
5674 If you need to pass the SDK path to a command within a function, you
5675 can use ``${SDK_DIR}``, which points to the parent directory used by
5676 the OpenEmbedded build system when creating SDK output. See the
5677 :term:`SDK_DIR` variable for more information.
5678
Andrew Geisslerf0343792020-11-18 10:42:21 -06005679 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005680 The revision of the recipe. The default value for this variable is
5681 "r0". Subsequent revisions of the recipe conventionally have the
5682 values "r1", "r2", and so forth. When :term:`PV` increases,
Andrew Geissler09036742021-06-25 14:25:14 -05005683 :term:`PR` is conventionally reset to "r0".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005684
5685 .. note::
5686
Andrew Geissler09036742021-06-25 14:25:14 -05005687 The OpenEmbedded build system does not need the aid of :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005688 to know when to rebuild a recipe. The build system uses the task
Andrew Geissler09209ee2020-12-13 08:44:15 -06005689 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005690 :ref:`stamp <structure-build-tmp-stamps>` and
Andrew Geissler09209ee2020-12-13 08:44:15 -06005691 :ref:`overview-manual/concepts:shared state cache`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005692 mechanisms.
5693
Andrew Geissler09036742021-06-25 14:25:14 -05005694 The :term:`PR` variable primarily becomes significant when a package
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005695 manager dynamically installs packages on an already built image. In
Andrew Geissler09036742021-06-25 14:25:14 -05005696 this case, :term:`PR`, which is the default value of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005697 :term:`PKGR`, helps the package manager distinguish which
5698 package is the most recent one in cases where many packages have the
Andrew Geissler09036742021-06-25 14:25:14 -05005699 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with
5700 the same :term:`PV` usually means that the packages all install the same
5701 upstream version, but with later (:term:`PR`) version packages including
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005702 packaging fixes.
5703
5704 .. note::
5705
Andrew Geissler09036742021-06-25 14:25:14 -05005706 :term:`PR` does not need to be increased for changes that do not change the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005707 package contents or metadata.
5708
Andrew Geissler5f350902021-07-23 13:09:54 -04005709 Because manually managing :term:`PR` can be cumbersome and error-prone,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005710 an automated solution exists. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005711 ":ref:`dev-manual/common-tasks:working with a pr service`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005712 in the Yocto Project Development Tasks Manual for more information.
5713
Andrew Geisslerf0343792020-11-18 10:42:21 -06005714 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005715 If multiple recipes provide the same item, this variable determines
5716 which recipe is preferred and thus provides the item (i.e. the
5717 preferred provider). You should always suffix this variable with the
5718 name of the provided item. And, you should define the variable using
5719 the preferred recipe's name (:term:`PN`). Here is a common
Andrew Geisslerc926e172021-05-07 16:11:35 -05005720 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005721
5722 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5723
5724 In the previous example, multiple recipes are providing "virtual/kernel".
Andrew Geissler09036742021-06-25 14:25:14 -05005725 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005726 the recipe you prefer to provide "virtual/kernel".
5727
Andrew Geisslerc926e172021-05-07 16:11:35 -05005728 Following are more examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005729
5730 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5731 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5732
5733 For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06005734 information, see the ":ref:`dev-manual/common-tasks:using virtual providers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005735 section in the Yocto Project Development Tasks Manual.
5736
5737 .. note::
5738
Andrew Geissler09036742021-06-25 14:25:14 -05005739 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005740 recipe that :term:`PROVIDES` that item but is not selected (defined)
Andrew Geissler09036742021-06-25 14:25:14 -05005741 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005742 desirable since this mechanism is designed to select between mutually
5743 exclusive alternative providers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005744
Andrew Geisslerf0343792020-11-18 10:42:21 -06005745 :term:`PREFERRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005746 If there are multiple versions of a recipe available, this variable
5747 determines which version should be given preference. You must always
5748 suffix the variable with the :term:`PN` you want to select (`python` in
5749 the first example below), and you should specify the :term:`PV`
5750 accordingly (`3.4.0` in the example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005751
Andrew Geissler09036742021-06-25 14:25:14 -05005752 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005753 through the "``%``" character. You can use the character to match any
5754 number of characters, which can be useful when specifying versions
5755 that contain long revision numbers that potentially change. Here are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005756 two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005757
5758 PREFERRED_VERSION_python = "3.4.0"
5759 PREFERRED_VERSION_linux-yocto = "5.0%"
5760
5761 .. note::
5762
5763 The use of the "%" character is limited in that it only works at the end of the
5764 string. You cannot use the wildcard character in any other
5765 location of the string.
5766
5767 The specified version is matched against :term:`PV`, which
5768 does not necessarily match the version part of the recipe's filename.
5769 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
Andrew Geisslerc926e172021-05-07 16:11:35 -05005770 where ``foo_git.bb`` contains the following assignment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005771
5772 PV = "1.1+git${SRCPV}"
5773
5774 In this case, the correct way to select
Andrew Geisslerc926e172021-05-07 16:11:35 -05005775 ``foo_git.bb`` is by using an assignment such as the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005776
5777 PREFERRED_VERSION_foo = "1.1+git%"
5778
5779 Compare that previous example
Andrew Geisslerc926e172021-05-07 16:11:35 -05005780 against the following incorrect example, which does not work::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005781
5782 PREFERRED_VERSION_foo = "git"
5783
Andrew Geissler09036742021-06-25 14:25:14 -05005784 Sometimes the :term:`PREFERRED_VERSION` variable can be set by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005785 configuration files in a way that is hard to change. You can use
5786 :term:`OVERRIDES` to set a machine-specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05005787 override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005788
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005789 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005790
5791 Although not recommended, worst case, you can also use the
5792 "forcevariable" override, which is the strongest override possible.
Andrew Geisslerc926e172021-05-07 16:11:35 -05005793 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005794
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005795 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005796
5797 .. note::
5798
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005799 The ``:forcevariable`` override is not handled specially. This override
Andrew Geissler09036742021-06-25 14:25:14 -05005800 only works because the default value of :term:`OVERRIDES` includes "forcevariable".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005801
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005802 If a recipe with the specified version is not available, a warning
5803 message will be shown. See :term:`REQUIRED_VERSION` if you want this
5804 to be an error instead.
5805
Andrew Geisslerf0343792020-11-18 10:42:21 -06005806 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005807 Specifies additional paths from which the OpenEmbedded build system
5808 gets source code. When the build system searches for source code, it
5809 first tries the local download directory. If that location fails, the
Andrew Geissler09036742021-06-25 14:25:14 -05005810 build system tries locations defined by :term:`PREMIRRORS`, the upstream
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005811 source, and then locations specified by
5812 :term:`MIRRORS` in that order.
5813
5814 Assuming your distribution (:term:`DISTRO`) is "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05005815 the default value for :term:`PREMIRRORS` is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005816 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
5817
5818 Typically, you could add a specific server for the build system to
5819 attempt before any others by adding something like the following to
5820 the ``local.conf`` configuration file in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005821 :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005822
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005823 PREMIRRORS:prepend = "\
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005824 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5825 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5826 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5827 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5828
5829 These changes cause the
5830 build system to intercept Git, FTP, HTTP, and HTTPS requests and
5831 direct them to the ``http://`` sources mirror. You can use
5832 ``file://`` URLs to point to local directories or network shares as
5833 well.
5834
Andrew Geisslerf0343792020-11-18 10:42:21 -06005835 :term:`PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005836 Indicates the importance of a package.
5837
Andrew Geissler09036742021-06-25 14:25:14 -05005838 :term:`PRIORITY` is considered to be part of the distribution policy
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005839 because the importance of any given recipe depends on the purpose for
Andrew Geissler09036742021-06-25 14:25:14 -05005840 which the distribution is being produced. Thus, :term:`PRIORITY` is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005841 normally set within recipes.
5842
Andrew Geissler09036742021-06-25 14:25:14 -05005843 You can set :term:`PRIORITY` to "required", "standard", "extra", and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005844 "optional", which is the default.
5845
Andrew Geisslerf0343792020-11-18 10:42:21 -06005846 :term:`PRIVATE_LIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005847 Specifies libraries installed within a recipe that should be ignored
5848 by the OpenEmbedded build system's shared library resolver. This
5849 variable is typically used when software being built by a recipe has
5850 its own private versions of a library normally provided by another
5851 recipe. In this case, you would not want the package containing the
5852 private libraries to be set as a dependency on other unrelated
5853 packages that should instead depend on the package providing the
5854 standard version of the library.
5855
5856 Libraries specified in this variable should be specified by their
Andrew Geisslerc926e172021-05-07 16:11:35 -05005857 file name. For example, from the Firefox recipe in meta-browser::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005858
5859 PRIVATE_LIBS = "libmozjs.so \
5860 libxpcom.so \
5861 libnspr4.so \
5862 libxul.so \
5863 libmozalloc.so \
5864 libplc4.so \
5865 libplds4.so"
5866
5867 For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005868 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005869 section in the Yocto Project Overview and Concepts Manual.
5870
Andrew Geisslerf0343792020-11-18 10:42:21 -06005871 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005872 A list of aliases by which a particular recipe can be known. By
Andrew Geissler09036742021-06-25 14:25:14 -05005873 default, a recipe's own :term:`PN` is implicitly already in its
5874 :term:`PROVIDES` list and therefore does not need to mention that it
5875 provides itself. If a recipe uses :term:`PROVIDES`, the additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005876 aliases are synonyms for the recipe and can be useful for satisfying
5877 dependencies of other recipes during the build as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05005878 :term:`DEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005879
Andrew Geissler09036742021-06-25 14:25:14 -05005880 Consider the following example :term:`PROVIDES` statement from the recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05005881 file ``eudev_3.2.9.bb``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005882
Andrew Geisslerd1e89492021-02-12 15:35:20 -06005883 PROVIDES += "udev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005884
Andrew Geissler09036742021-06-25 14:25:14 -05005885 The :term:`PROVIDES` statement
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005886 results in the "eudev" recipe also being available as simply "udev".
5887
5888 .. note::
5889
Andrew Geisslerd1e89492021-02-12 15:35:20 -06005890 A recipe's own recipe name (:term:`PN`) is always implicitly prepended
5891 to `PROVIDES`, so while using "+=" in the above example may not be
5892 strictly necessary it is recommended to avoid confusion.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005893
5894 In addition to providing recipes under alternate names, the
Andrew Geissler09036742021-06-25 14:25:14 -05005895 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005896 virtual target is a name that corresponds to some particular
5897 functionality (e.g. a Linux kernel). Recipes that provide the
Andrew Geissler09036742021-06-25 14:25:14 -05005898 functionality in question list the virtual target in :term:`PROVIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005899 Recipes that depend on the functionality in question can include the
Andrew Geissler09036742021-06-25 14:25:14 -05005900 virtual target in :term:`DEPENDS` to leave the choice of provider open.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005901
5902 Conventionally, virtual targets have names on the form
5903 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
5904 of the name and has no syntactical significance.
5905
5906 The :term:`PREFERRED_PROVIDER` variable is
5907 used to select which particular recipe provides a virtual target.
5908
5909 .. note::
5910
5911 A corresponding mechanism for virtual runtime dependencies
5912 (packages) exists. However, the mechanism does not depend on any
5913 special functionality beyond ordinary variable assignments. For
5914 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of
5915 the component that manages the ``/dev`` directory.
5916
5917 Setting the "preferred provider" for runtime dependencies is as
Andrew Geisslerc926e172021-05-07 16:11:35 -05005918 simple as using the following assignment in a configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005919
5920 VIRTUAL-RUNTIME_dev_manager = "udev"
5921
5922
Andrew Geisslerf0343792020-11-18 10:42:21 -06005923 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005924 The network based :term:`PR` service host and port.
5925
5926 The ``conf/local.conf.sample.extended`` configuration file in the
5927 :term:`Source Directory` shows how the
Andrew Geissler09036742021-06-25 14:25:14 -05005928 :term:`PRSERV_HOST` variable is set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005929
5930 PRSERV_HOST = "localhost:0"
5931
5932 You must
5933 set the variable if you want to automatically start a local :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06005934 service <dev-manual/common-tasks:working with a pr service>`. You can
Andrew Geissler09036742021-06-25 14:25:14 -05005935 set :term:`PRSERV_HOST` to other values to use a remote PR service.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005936
Andrew Geissler6ce62a22020-11-30 19:58:47 -06005937
5938 :term:`PSEUDO_IGNORE_PATHS`
5939 A comma-separated (without spaces) list of path prefixes that should be ignored
5940 by pseudo when monitoring and recording file operations, in order to avoid
5941 problems with files being written to outside of the pseudo context and
5942 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list
5943 and can include partial directory (or file) names.
5944
5945
Andrew Geisslerf0343792020-11-18 10:42:21 -06005946 :term:`PTEST_ENABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005947 Specifies whether or not :ref:`Package
Andrew Geissler09209ee2020-12-13 08:44:15 -06005948 Test <dev-manual/common-tasks:testing packages with ptest>` (ptest)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005949 functionality is enabled when building a recipe. You should not set
5950 this variable directly. Enabling and disabling building Package Tests
5951 at build time should be done by adding "ptest" to (or removing it
5952 from) :term:`DISTRO_FEATURES`.
5953
Andrew Geisslerf0343792020-11-18 10:42:21 -06005954 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005955 The version of the recipe. The version is normally extracted from the
5956 recipe filename. For example, if the recipe is named
Andrew Geissler09036742021-06-25 14:25:14 -05005957 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1".
5958 :term:`PV` is generally not overridden within a recipe unless it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005959 building an unstable (i.e. development) version from a source code
5960 repository (e.g. Git or Subversion).
5961
Andrew Geissler09036742021-06-25 14:25:14 -05005962 :term:`PV` is the default value of the :term:`PKGV` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005963
Andrew Geisslerf0343792020-11-18 10:42:21 -06005964 :term:`PYTHON_ABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005965 When used by recipes that inherit the
5966 :ref:`distutils3 <ref-classes-distutils3>`,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005967 :ref:`setuptools3 <ref-classes-setuptools3>` classes, denotes the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005968 Application Binary Interface (ABI) currently in use for Python. By
5969 default, the ABI is "m". You do not have to set this variable as the
5970 OpenEmbedded build system sets it for you.
5971
5972 The OpenEmbedded build system uses the ABI to construct directory
5973 names used when installing the Python headers and libraries in
5974 sysroot (e.g. ``.../python3.3m/...``).
5975
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005976 Recipes that inherit the ``distutils3`` class during cross-builds also
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005977 use this variable to locate the headers and libraries of the
5978 appropriate Python that the extension is targeting.
5979
Andrew Geisslerf0343792020-11-18 10:42:21 -06005980 :term:`PYTHON_PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005981 When used by recipes that inherit the
5982 `distutils3 <ref-classes-distutils3>`,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005983 :ref:`setuptools3 <ref-classes-setuptools3>` classes, specifies the
Andrew Geissler09036742021-06-25 14:25:14 -05005984 major Python version being built. For Python 3.x, :term:`PYTHON_PN` would
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005985 be "python3". You do not have to set this variable as the
5986 OpenEmbedded build system automatically sets it for you.
5987
5988 The variable allows recipes to use common infrastructure such as the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005989 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005990
5991 DEPENDS += "${PYTHON_PN}-native"
5992
5993 In the previous example,
Andrew Geissler09036742021-06-25 14:25:14 -05005994 the version of the dependency is :term:`PYTHON_PN`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005995
Andrew Geisslerf0343792020-11-18 10:42:21 -06005996 :term:`RANLIB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005997 The minimal command and arguments to run ``ranlib``.
5998
Andrew Geisslerf0343792020-11-18 10:42:21 -06005999 :term:`RCONFLICTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006000 The list of packages that conflict with packages. Note that packages
6001 will not be installed if conflicting packages are not first removed.
6002
6003 Like all package-controlling variables, you must always use them in
Andrew Geisslerc926e172021-05-07 16:11:35 -05006004 conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006005
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006006 RCONFLICTS:${PN} = "another_conflicting_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006007
6008 BitBake, which the OpenEmbedded build system uses, supports
6009 specifying versioned dependencies. Although the syntax varies
6010 depending on the packaging format, BitBake hides these differences
6011 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006012 :term:`RCONFLICTS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006013
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006014 RCONFLICTS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006015
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006016 For ``operator``, you can specify the following:
6017
6018 - =
6019 - <
6020 - >
6021 - <=
6022 - >=
6023
6024 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006025 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006026
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006027 RCONFLICTS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006028
Andrew Geisslerf0343792020-11-18 10:42:21 -06006029 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006030 Lists runtime dependencies of a package. These dependencies are other
6031 packages that must be installed in order for the package to function
6032 correctly. As an example, the following assignment declares that the
6033 package ``foo`` needs the packages ``bar`` and ``baz`` to be
Andrew Geisslerc926e172021-05-07 16:11:35 -05006034 installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006035
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006036 RDEPENDS:foo = "bar baz"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006037
6038 The most common types of package
6039 runtime dependencies are automatically detected and added. Therefore,
Andrew Geissler09036742021-06-25 14:25:14 -05006040 most recipes do not need to set :term:`RDEPENDS`. For more information,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006041 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006042 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006043 section in the Yocto Project Overview and Concepts Manual.
6044
Andrew Geissler09036742021-06-25 14:25:14 -05006045 The practical effect of the above :term:`RDEPENDS` assignment is that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006046 ``bar`` and ``baz`` will be declared as dependencies inside the
6047 package ``foo`` when it is written out by one of the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006048 :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006049 Exactly how this is done depends on which package format is used,
6050 which is determined by
6051 :term:`PACKAGE_CLASSES`. When the
6052 corresponding package manager installs the package, it will know to
6053 also install the packages on which it depends.
6054
6055 To ensure that the packages ``bar`` and ``baz`` get built, the
Andrew Geissler09036742021-06-25 14:25:14 -05006056 previous :term:`RDEPENDS` assignment also causes a task dependency to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006057 added. This dependency is from the recipe's
6058 :ref:`ref-tasks-build` (not to be confused with
6059 :ref:`ref-tasks-compile`) task to the
6060 ``do_package_write_*`` task of the recipes that build ``bar`` and
6061 ``baz``.
6062
Andrew Geissler09036742021-06-25 14:25:14 -05006063 The names of the packages you list within :term:`RDEPENDS` must be the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006064 names of other packages - they cannot be recipe names. Although
6065 package names and recipe names usually match, the important point
Andrew Geissler09036742021-06-25 14:25:14 -05006066 here is that you are providing package names within the :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006067 variable. For an example of the default list of packages created from
6068 a recipe, see the :term:`PACKAGES` variable.
6069
Andrew Geissler09036742021-06-25 14:25:14 -05006070 Because the :term:`RDEPENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006071 you should always use the variable in a form with an attached package
6072 name (remember that a single recipe can build multiple packages). For
6073 example, suppose you are building a development package that depends
6074 on the ``perl`` package. In this case, you would use the following
Andrew Geissler09036742021-06-25 14:25:14 -05006075 :term:`RDEPENDS` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006076
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006077 RDEPENDS:${PN}-dev += "perl"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006078
6079 In the example,
6080 the development package depends on the ``perl`` package. Thus, the
Andrew Geissler5f350902021-07-23 13:09:54 -04006081 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006082 the variable.
6083
6084 .. note::
6085
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006086 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006087 by default. This default is set in the BitBake configuration file
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006088 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006089 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006090 rather than the "=" operator.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006091
Andrew Geissler09036742021-06-25 14:25:14 -05006092 The package names you use with :term:`RDEPENDS` must appear as they would
6093 in the :term:`PACKAGES` variable. The :term:`PKG` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006094 allows a different name to be used for the final package (e.g. the
6095 :ref:`debian <ref-classes-debian>` class uses this to rename
6096 packages), but this final package name cannot be used with
Andrew Geissler09036742021-06-25 14:25:14 -05006097 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006098 independent of the package format used.
6099
6100 BitBake, which the OpenEmbedded build system uses, supports
6101 specifying versioned dependencies. Although the syntax varies
6102 depending on the packaging format, BitBake hides these differences
6103 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006104 :term:`RDEPENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006105
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006106 RDEPENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006107
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006108 For ``operator``, you can specify the following:
6109
6110 - =
6111 - <
6112 - >
6113 - <=
6114 - >=
6115
6116 For version, provide the version number.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006117
6118 .. note::
6119
Andrew Geissler09036742021-06-25 14:25:14 -05006120 You can use :term:`EXTENDPKGV` to provide a full package version
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006121 specification.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006122
6123 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006124 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006125
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006126 RDEPENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006127
6128 For information on build-time dependencies, see the
6129 :term:`DEPENDS` variable. You can also see the
Patrick Williams213cb262021-08-07 19:21:33 -05006130 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
6131 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006132 BitBake User Manual for additional information on tasks and
6133 dependencies.
6134
Andrew Geisslerf0343792020-11-18 10:42:21 -06006135 :term:`REQUIRED_DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006136 When inheriting the
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006137 :ref:`features_check <ref-classes-features_check>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006138 class, this variable identifies distribution features that must exist
6139 in the current configuration in order for the OpenEmbedded build
6140 system to build the recipe. In other words, if the
Andrew Geissler09036742021-06-25 14:25:14 -05006141 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not
6142 appear in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006143 the recipe will be skipped, and if the build system attempts to build
6144 the recipe then an error will be triggered.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006145
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006146 :term:`REQUIRED_VERSION`
6147 If there are multiple versions of a recipe available, this variable
6148 determines which version should be given preference.
6149 :term:`REQUIRED_VERSION` works in exactly the same manner as
6150 :term:`PREFERRED_VERSION`, except that if the specified version is not
6151 available then an error message is shown and the build fails
6152 immediately.
6153
6154 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
6155 for the same recipe, the :term:`REQUIRED_VERSION` value applies.
6156
Andrew Geisslerf0343792020-11-18 10:42:21 -06006157 :term:`RM_WORK_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006158 With ``rm_work`` enabled, this variable specifies a list of recipes
6159 whose work directories should not be removed. See the
6160 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more
6161 details.
6162
Andrew Geisslerf0343792020-11-18 10:42:21 -06006163 :term:`ROOT_HOME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006164 Defines the root home directory. By default, this directory is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006165 follows in the BitBake configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006166
6167 ROOT_HOME ??= "/home/root"
6168
6169 .. note::
6170
6171 This default value is likely used because some embedded solutions
6172 prefer to have a read-only root filesystem and prefer to keep
6173 writeable data in one place.
6174
6175 You can override the default by setting the variable in any layer or
6176 in the ``local.conf`` file. Because the default is set using a "weak"
6177 assignment (i.e. "??="), you can use either of the following forms to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006178 define your override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006179
6180 ROOT_HOME = "/root"
6181 ROOT_HOME ?= "/root"
6182
6183 These
6184 override examples use ``/root``, which is probably the most commonly
6185 used override.
6186
Andrew Geisslerf0343792020-11-18 10:42:21 -06006187 :term:`ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006188 Indicates a filesystem image to include as the root filesystem.
6189
Andrew Geissler09036742021-06-25 14:25:14 -05006190 The :term:`ROOTFS` variable is an optional variable used with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006191 :ref:`image-live <ref-classes-image-live>` class.
6192
Andrew Geisslerf0343792020-11-18 10:42:21 -06006193 :term:`ROOTFS_POSTINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006194 Specifies a list of functions to call after the OpenEmbedded build
6195 system has installed packages. You can specify functions separated by
Andrew Geisslerc926e172021-05-07 16:11:35 -05006196 semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006197
6198 ROOTFS_POSTINSTALL_COMMAND += "function; ... "
6199
6200 If you need to pass the root filesystem path to a command within a
6201 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6202 directory that becomes the root filesystem image. See the
6203 :term:`IMAGE_ROOTFS` variable for more
6204 information.
6205
Andrew Geisslerf0343792020-11-18 10:42:21 -06006206 :term:`ROOTFS_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006207 Specifies a list of functions to call once the OpenEmbedded build
6208 system has created the root filesystem. You can specify functions
Andrew Geisslerc926e172021-05-07 16:11:35 -05006209 separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006210
6211 ROOTFS_POSTPROCESS_COMMAND += "function; ... "
6212
6213 If you need to pass the root filesystem path to a command within a
6214 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6215 directory that becomes the root filesystem image. See the
6216 :term:`IMAGE_ROOTFS` variable for more
6217 information.
6218
Andrew Geisslerf0343792020-11-18 10:42:21 -06006219 :term:`ROOTFS_POSTUNINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006220 Specifies a list of functions to call after the OpenEmbedded build
6221 system has removed unnecessary packages. When runtime package
6222 management is disabled in the image, several packages are removed
6223 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
Andrew Geisslerc926e172021-05-07 16:11:35 -05006224 You can specify functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006225
6226 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... "
6227
6228 If you need to pass the root filesystem path to a command within a
6229 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6230 directory that becomes the root filesystem image. See the
6231 :term:`IMAGE_ROOTFS` variable for more
6232 information.
6233
Andrew Geisslerf0343792020-11-18 10:42:21 -06006234 :term:`ROOTFS_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006235 Specifies a list of functions to call before the OpenEmbedded build
6236 system has created the root filesystem. You can specify functions
Andrew Geisslerc926e172021-05-07 16:11:35 -05006237 separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006238
6239 ROOTFS_PREPROCESS_COMMAND += "function; ... "
6240
6241 If you need to pass the root filesystem path to a command within a
6242 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6243 directory that becomes the root filesystem image. See the
6244 :term:`IMAGE_ROOTFS` variable for more
6245 information.
6246
Andrew Geisslerf0343792020-11-18 10:42:21 -06006247 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006248 A list of package name aliases that a package also provides. These
6249 aliases are useful for satisfying runtime dependencies of other
6250 packages both during the build and on the target (as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05006251 :term:`RDEPENDS`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006252
6253 .. note::
6254
Andrew Geissler09036742021-06-25 14:25:14 -05006255 A package's own name is implicitly already in its :term:`RPROVIDES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006256
6257 As with all package-controlling variables, you must always use the
6258 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05006259 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006260
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006261 RPROVIDES:${PN} = "widget-abi-2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006262
Andrew Geisslerf0343792020-11-18 10:42:21 -06006263 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006264 A list of packages that extends the usability of a package being
6265 built. The package being built does not depend on this list of
6266 packages in order to successfully build, but rather uses them for
6267 extended usability. To specify runtime dependencies for packages, see
Andrew Geissler09036742021-06-25 14:25:14 -05006268 the :term:`RDEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006269
Andrew Geissler09036742021-06-25 14:25:14 -05006270 The package manager will automatically install the :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006271 list of packages when installing the built package. However, you can
6272 prevent listed packages from being installed by using the
6273 :term:`BAD_RECOMMENDATIONS`,
6274 :term:`NO_RECOMMENDATIONS`, and
6275 :term:`PACKAGE_EXCLUDE` variables.
6276
Andrew Geissler09036742021-06-25 14:25:14 -05006277 Packages specified in :term:`RRECOMMENDS` need not actually be produced.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07006278 However, there must be a recipe providing each package, either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006279 through the :term:`PACKAGES` or
6280 :term:`PACKAGES_DYNAMIC` variables or the
6281 :term:`RPROVIDES` variable, or an error will occur
6282 during the build. If such a recipe does exist and the package is not
6283 produced, the build continues without error.
6284
Andrew Geissler09036742021-06-25 14:25:14 -05006285 Because the :term:`RRECOMMENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006286 you should always attach an override to the variable to specify the
6287 particular package whose usability is being extended. For example,
6288 suppose you are building a development package that is extended to
6289 support wireless functionality. In this case, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006290 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006291
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006292 RRECOMMENDS:${PN}-dev += "wireless_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006293
6294 In the
6295 example, the package name (``${PN}-dev``) must appear as it would in
Andrew Geissler09036742021-06-25 14:25:14 -05006296 the :term:`PACKAGES` namespace before any renaming of the output package
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006297 by classes such as ``debian.bbclass``.
6298
6299 BitBake, which the OpenEmbedded build system uses, supports
6300 specifying versioned recommends. Although the syntax varies depending
6301 on the packaging format, BitBake hides these differences from you.
6302 Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006303 :term:`RRECOMMENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006304
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006305 RRECOMMENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006306
6307 For ``operator``, you can specify the following:
6308
6309 - =
6310 - <
6311 - >
6312 - <=
6313 - >=
6314
6315 For example, the following sets up a recommend on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006316 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006317
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006318 RRECOMMENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006319
Andrew Geisslerf0343792020-11-18 10:42:21 -06006320 :term:`RREPLACES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006321 A list of packages replaced by a package. The package manager uses
6322 this variable to determine which package should be installed to
6323 replace other package(s) during an upgrade. In order to also have the
6324 other package(s) removed at the same time, you must add the name of
Andrew Geissler09036742021-06-25 14:25:14 -05006325 the other package to the :term:`RCONFLICTS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006326
6327 As with all package-controlling variables, you must use this variable
Andrew Geisslerc926e172021-05-07 16:11:35 -05006328 in conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006329
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006330 RREPLACES:${PN} = "other_package_being_replaced"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006331
6332 BitBake, which the OpenEmbedded build system uses, supports
6333 specifying versioned replacements. Although the syntax varies
6334 depending on the packaging format, BitBake hides these differences
6335 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006336 :term:`RREPLACES` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006337
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006338 RREPLACES:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006339
6340 For ``operator``, you can specify the following:
6341
6342 - =
6343 - <
6344 - >
6345 - <=
6346 - >=
6347
6348 For example, the following sets up a replacement using version 1.2
Andrew Geisslerc926e172021-05-07 16:11:35 -05006349 or greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006350
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006351 RREPLACES:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006352
Andrew Geisslerf0343792020-11-18 10:42:21 -06006353 :term:`RSUGGESTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006354 A list of additional packages that you can suggest for installation
6355 by the package manager at the time a package is installed. Not all
6356 package managers support this functionality.
6357
6358 As with all package-controlling variables, you must always use this
6359 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05006360 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006361
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006362 RSUGGESTS:${PN} = "useful_package another_package"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006363
Andrew Geisslerf0343792020-11-18 10:42:21 -06006364 :term:`S`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006365 The location in the :term:`Build Directory` where
6366 unpacked recipe source code resides. By default, this directory is
6367 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
6368 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
6369 version. If the source tarball extracts the code to a directory named
6370 anything other than ``${BPN}-${PV}``, or if the source code is
6371 fetched from an SCM such as Git or Subversion, then you must set
Andrew Geissler09036742021-06-25 14:25:14 -05006372 :term:`S` in the recipe so that the OpenEmbedded build system knows where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006373 to find the unpacked source.
6374
6375 As an example, assume a :term:`Source Directory`
6376 top-level folder named ``poky`` and a default Build Directory at
6377 ``poky/build``. In this case, the work directory the build system
Andrew Geisslerc926e172021-05-07 16:11:35 -05006378 uses to keep the unpacked recipe for ``db`` is the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006379
6380 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6381
6382 The unpacked source code resides in the ``db-5.1.19`` folder.
6383
6384 This next example assumes a Git repository. By default, Git
6385 repositories are cloned to ``${WORKDIR}/git`` during
6386 :ref:`ref-tasks-fetch`. Since this path is different
Andrew Geissler09036742021-06-25 14:25:14 -05006387 from the default value of :term:`S`, you must set it specifically so the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006388 source can be located::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006389
6390 SRC_URI = "git://path/to/repo.git"
6391 S = "${WORKDIR}/git"
6392
Andrew Geisslerf0343792020-11-18 10:42:21 -06006393 :term:`SANITY_REQUIRED_UTILITIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006394 Specifies a list of command-line utilities that should be checked for
6395 during the initial sanity checking process when running BitBake. If
6396 any of the utilities are not installed on the build host, then
6397 BitBake immediately exits with an error.
6398
Andrew Geisslerf0343792020-11-18 10:42:21 -06006399 :term:`SANITY_TESTED_DISTROS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006400 A list of the host distribution identifiers that the build system has
6401 been tested against. Identifiers consist of the host distributor ID
6402 followed by the release, as reported by the ``lsb_release`` tool or
6403 as read from ``/etc/lsb-release``. Separate the list items with
Andrew Geissler09036742021-06-25 14:25:14 -05006404 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006405 not empty and the current value of
6406 :term:`NATIVELSBSTRING` does not appear in the
6407 list, then the build system reports a warning that indicates the
6408 current host distribution has not been tested as a build host.
6409
Andrew Geisslerf0343792020-11-18 10:42:21 -06006410 :term:`SDK_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006411 The target architecture for the SDK. Typically, you do not directly
6412 set this variable. Instead, use :term:`SDKMACHINE`.
6413
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006414 :term:`SDK_CUSTOM_TEMPLATECONF`
Andrew Geissler09036742021-06-25 14:25:14 -05006415 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006416 "1" and a ``conf/templateconf.conf`` file exists in the build directory
6417 (:term:`TOPDIR`) then this will be copied into the SDK.
6418
Andrew Geisslerf0343792020-11-18 10:42:21 -06006419 :term:`SDK_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006420 The directory set up and used by the
6421 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
6422 the SDK is deployed. The ``populate_sdk_base`` class defines
Andrew Geissler09036742021-06-25 14:25:14 -05006423 :term:`SDK_DEPLOY` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006424
6425 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
6426
Andrew Geisslerf0343792020-11-18 10:42:21 -06006427 :term:`SDK_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006428 The parent directory used by the OpenEmbedded build system when
6429 creating SDK output. The
6430 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
Andrew Geisslerc926e172021-05-07 16:11:35 -05006431 the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006432
6433 SDK_DIR = "${WORKDIR}/sdk"
6434
6435 .. note::
6436
Andrew Geissler09036742021-06-25 14:25:14 -05006437 The :term:`SDK_DIR` directory is a temporary directory as it is part of
6438 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006439
Andrew Geisslerf0343792020-11-18 10:42:21 -06006440 :term:`SDK_EXT_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006441 Controls whether or not shared state artifacts are copied into the
6442 extensible SDK. The default value of "full" copies all of the
6443 required shared state artifacts into the extensible SDK. The value
6444 "minimal" leaves these artifacts out of the SDK.
6445
6446 .. note::
6447
6448 If you set the variable to "minimal", you need to ensure
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006449 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the
6450 artifacts to be fetched as needed.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006451
Andrew Geisslerf0343792020-11-18 10:42:21 -06006452 :term:`SDK_HOST_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006453 The manifest file for the host part of the SDK. This file lists all
6454 the installed packages that make up the host part of the SDK. The
6455 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006456 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006457
6458 packagename packagearch version
6459
6460 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05006461 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006462
6463 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
6464
6465 The location is derived using the :term:`SDK_DEPLOY` and
6466 :term:`TOOLCHAIN_OUTPUTNAME` variables.
6467
Andrew Geisslerf0343792020-11-18 10:42:21 -06006468 :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006469 When set to "1", specifies to include the packagedata for all recipes
6470 in the "world" target in the extensible SDK. Including this data
6471 allows the ``devtool search`` command to find these recipes in search
6472 results, as well as allows the ``devtool add`` command to map
6473 dependencies more effectively.
6474
6475 .. note::
6476
Andrew Geissler09036742021-06-25 14:25:14 -05006477 Enabling the :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006478 variable significantly increases build time because all of world
6479 needs to be built. Enabling the variable also slightly increases
6480 the size of the extensible SDK.
6481
Andrew Geisslerf0343792020-11-18 10:42:21 -06006482 :term:`SDK_INCLUDE_TOOLCHAIN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006483 When set to "1", specifies to include the toolchain in the extensible
6484 SDK. Including the toolchain is useful particularly when
6485 :term:`SDK_EXT_TYPE` is set to "minimal" to keep
6486 the SDK reasonably small but you still want to provide a usable
6487 toolchain. For example, suppose you want to use the toolchain from an
6488 IDE or from other tools and you do not want to perform additional
6489 steps to install the toolchain.
6490
Andrew Geissler09036742021-06-25 14:25:14 -05006491 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if
6492 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
6493 :term:`SDK_EXT_TYPE` is set to "full".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006494
Andrew Geisslerf0343792020-11-18 10:42:21 -06006495 :term:`SDK_INHERIT_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006496 A list of classes to remove from the :term:`INHERIT`
6497 value globally within the extensible SDK configuration. The
6498 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006499 default value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006500
6501 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
6502
6503 Some classes are not generally applicable within the extensible SDK
6504 context. You can use this variable to disable those classes.
6505
6506 For additional information on how to customize the extensible SDK's
6507 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006508 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006509 section in the Yocto Project Application Development and the
6510 Extensible Software Development Kit (eSDK) manual.
6511
Andrew Geisslerf0343792020-11-18 10:42:21 -06006512 :term:`SDK_LOCAL_CONF_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006513 A list of variables not allowed through from the OpenEmbedded build
6514 system configuration into the extensible SDK configuration. Usually,
6515 these are variables that are specific to the machine on which the
6516 build system is running and thus would be potentially problematic
6517 within the extensible SDK.
6518
Andrew Geissler09036742021-06-25 14:25:14 -05006519 By default, :term:`SDK_LOCAL_CONF_BLACKLIST` is set in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006520 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
6521 excludes the following variables:
6522
6523 - :term:`CONF_VERSION`
6524 - :term:`BB_NUMBER_THREADS`
Patrick Williams213cb262021-08-07 19:21:33 -05006525 - :term:`BB_NUMBER_PARSE_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006526 - :term:`PARALLEL_MAKE`
6527 - :term:`PRSERV_HOST`
6528 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
6529 - :term:`SSTATE_DIR` :term:`TMPDIR`
6530 - :term:`BB_SERVER_TIMEOUT`
6531
6532 For additional information on how to customize the extensible SDK's
6533 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006534 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006535 section in the Yocto Project Application Development and the
6536 Extensible Software Development Kit (eSDK) manual.
6537
Andrew Geisslerf0343792020-11-18 10:42:21 -06006538 :term:`SDK_LOCAL_CONF_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006539 A list of variables allowed through from the OpenEmbedded build
6540 system configuration into the extensible SDK configuration. By
6541 default, the list of variables is empty and is set in the
6542 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
6543
6544 This list overrides the variables specified using the
6545 :term:`SDK_LOCAL_CONF_BLACKLIST`
6546 variable as well as any variables identified by automatic
6547 blacklisting due to the "/" character being found at the start of the
6548 value, which is usually indicative of being a path and thus might not
6549 be valid on the system where the SDK is installed.
6550
6551 For additional information on how to customize the extensible SDK's
6552 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006553 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006554 section in the Yocto Project Application Development and the
6555 Extensible Software Development Kit (eSDK) manual.
6556
Andrew Geisslerf0343792020-11-18 10:42:21 -06006557 :term:`SDK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006558 The base name for SDK output files. The name is derived from the
6559 :term:`DISTRO`, :term:`TCLIBC`,
6560 :term:`SDK_ARCH`,
6561 :term:`IMAGE_BASENAME`, and
Andrew Geisslerc926e172021-05-07 16:11:35 -05006562 :term:`TUNE_PKGARCH` variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006563
6564 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6565
Andrew Geisslerf0343792020-11-18 10:42:21 -06006566 :term:`SDK_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006567 Specifies the operating system for which the SDK will be built. The
6568 default value is the value of :term:`BUILD_OS`.
6569
Andrew Geisslerf0343792020-11-18 10:42:21 -06006570 :term:`SDK_OUTPUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006571 The location used by the OpenEmbedded build system when creating SDK
6572 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -05006573 class defines the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006574
6575 SDK_DIR = "${WORKDIR}/sdk"
6576 SDK_OUTPUT = "${SDK_DIR}/image"
6577 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
6578
6579 .. note::
6580
Andrew Geissler09036742021-06-25 14:25:14 -05006581 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006582 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is
6583 :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006584
Andrew Geisslerf0343792020-11-18 10:42:21 -06006585 :term:`SDK_PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006586 Specifies a list of architectures compatible with the SDK machine.
6587 This variable is set automatically and should not normally be
6588 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05006589 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006590 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
6591
Andrew Geisslerf0343792020-11-18 10:42:21 -06006592 :term:`SDK_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006593 Specifies a list of functions to call once the OpenEmbedded build
6594 system creates the SDK. You can specify functions separated by
6595 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... "
6596
6597 If you need to pass an SDK path to a command within a function, you
6598 can use ``${SDK_DIR}``, which points to the parent directory used by
6599 the OpenEmbedded build system when creating SDK output. See the
6600 :term:`SDK_DIR` variable for more information.
6601
Andrew Geisslerf0343792020-11-18 10:42:21 -06006602 :term:`SDK_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006603 The toolchain binary prefix used for ``nativesdk`` recipes. The
Andrew Geissler09036742021-06-25 14:25:14 -05006604 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006605 :term:`TARGET_PREFIX` when building
6606 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
6607
Andrew Geisslerf0343792020-11-18 10:42:21 -06006608 :term:`SDK_RECRDEP_TASKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006609 A list of shared state tasks added to the extensible SDK. By default,
6610 the following tasks are added:
6611
6612 - do_populate_lic
6613 - do_package_qa
6614 - do_populate_sysroot
6615 - do_deploy
6616
6617 Despite the default value of "" for the
Andrew Geissler09036742021-06-25 14:25:14 -05006618 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006619 to the SDK. To specify tasks beyond these four, you need to use the
Andrew Geissler09036742021-06-25 14:25:14 -05006620 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006621 tasks that are needed in order to build
6622 :term:`SDK_TARGETS`).
6623
Andrew Geisslerf0343792020-11-18 10:42:21 -06006624 :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006625 Specifies the system, including the architecture and the operating
6626 system, for which the SDK will be built.
6627
6628 The OpenEmbedded build system automatically sets this variable based
6629 on :term:`SDK_ARCH`,
6630 :term:`SDK_VENDOR`, and
Andrew Geissler09036742021-06-25 14:25:14 -05006631 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006632 variable yourself.
6633
Andrew Geisslerf0343792020-11-18 10:42:21 -06006634 :term:`SDK_TARGET_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006635 The manifest file for the target part of the SDK. This file lists all
6636 the installed packages that make up the target part of the SDK. The
6637 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006638 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006639
6640 packagename packagearch version
6641
6642 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05006643 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006644
6645 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
6646
6647 The location is derived using the :term:`SDK_DEPLOY` and
6648 :term:`TOOLCHAIN_OUTPUTNAME` variables.
6649
Andrew Geisslerf0343792020-11-18 10:42:21 -06006650 :term:`SDK_TARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006651 A list of targets to install from shared state as part of the
6652 standard or extensible SDK installation. The default value is "${PN}"
6653 (i.e. the image from which the SDK is built).
6654
Andrew Geissler09036742021-06-25 14:25:14 -05006655 The :term:`SDK_TARGETS` variable is an internal variable and typically
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006656 would not be changed.
6657
Andrew Geisslerf0343792020-11-18 10:42:21 -06006658 :term:`SDK_TITLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006659 The title to be printed when running the SDK installer. By default,
6660 this title is based on the :term:`DISTRO_NAME` or
6661 :term:`DISTRO` variable and is set in the
6662 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006663 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006664
6665 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
6666
6667 For the default distribution "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05006668 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006669
6670 For information on how to change this default title, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006671 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006672 section in the Yocto Project Application Development and the
6673 Extensible Software Development Kit (eSDK) manual.
6674
Andrew Geisslerf0343792020-11-18 10:42:21 -06006675 :term:`SDK_UPDATE_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006676 An optional URL for an update server for the extensible SDK. If set,
6677 the value is used as the default update server when running
6678 ``devtool sdk-update`` within the extensible SDK.
6679
Andrew Geisslerf0343792020-11-18 10:42:21 -06006680 :term:`SDK_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006681 Specifies the name of the SDK vendor.
6682
Andrew Geisslerf0343792020-11-18 10:42:21 -06006683 :term:`SDK_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006684 Specifies the version of the SDK. The Poky distribution configuration file
6685 (``/meta-poky/conf/distro/poky.conf``) sets the default
Andrew Geissler09036742021-06-25 14:25:14 -05006686 :term:`SDK_VERSION` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006687
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006688 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006689
6690 For additional information, see the
6691 :term:`DISTRO_VERSION` and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006692 :term:`METADATA_REVISION` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006693
Andrew Geisslerf0343792020-11-18 10:42:21 -06006694 :term:`SDKEXTPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006695 The default installation directory for the Extensible SDK. By
6696 default, this directory is based on the :term:`DISTRO`
6697 variable and is set in the
6698 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006699 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006700
6701 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
6702
6703 For the
Andrew Geissler09036742021-06-25 14:25:14 -05006704 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006705
6706 For information on how to change this default directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006707 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006708 section in the Yocto Project Application Development and the
6709 Extensible Software Development Kit (eSDK) manual.
6710
Andrew Geisslerf0343792020-11-18 10:42:21 -06006711 :term:`SDKIMAGE_FEATURES`
Andrew Geissler09036742021-06-25 14:25:14 -05006712 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006713 the SDK generated from an image using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006714
6715 $ bitbake -c populate_sdk imagename
6716
Andrew Geisslerf0343792020-11-18 10:42:21 -06006717 :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006718 The machine for which the SDK is built. In other words, the SDK is
6719 built such that it runs on the target you specify with the
Andrew Geissler09036742021-06-25 14:25:14 -05006720 :term:`SDKMACHINE` value. The value points to a corresponding ``.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006721 file under ``conf/machine-sdk/``.
6722
6723 You can use "i686" and "x86_64" as possible values for this variable.
6724 The variable defaults to "i686" and is set in the local.conf file in
6725 the Build Directory.
6726 ::
6727
6728 SDKMACHINE ?= "i686"
6729
6730 .. note::
6731
Andrew Geissler09036742021-06-25 14:25:14 -05006732 You cannot set the :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006733 variable in your distribution configuration file. If you do, the
6734 configuration will not take affect.
6735
Andrew Geisslerf0343792020-11-18 10:42:21 -06006736 :term:`SDKPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006737 Defines the path offered to the user for installation of the SDK that
6738 is generated by the OpenEmbedded build system. The path appears as
6739 the default location for installing the SDK when you run the SDK's
6740 installation script. You can override the offered path when you run
6741 the script.
6742
Andrew Geisslerf0343792020-11-18 10:42:21 -06006743 :term:`SDKTARGETSYSROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006744 The full path to the sysroot used for cross-compilation within an SDK
6745 as it will be when installed into the default
6746 :term:`SDKPATH`.
6747
Andrew Geisslerf0343792020-11-18 10:42:21 -06006748 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006749 The section in which packages should be categorized. Package
6750 management utilities can make use of this variable.
6751
Andrew Geisslerf0343792020-11-18 10:42:21 -06006752 :term:`SELECTED_OPTIMIZATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006753 Specifies the optimization flags passed to the C compiler when
6754 building for the target. The flags are passed through the default
6755 value of the :term:`TARGET_CFLAGS` variable.
6756
Andrew Geissler09036742021-06-25 14:25:14 -05006757 The :term:`SELECTED_OPTIMIZATION` variable takes the value of
William A. Kennington IIIac69b482021-06-02 12:28:27 -07006758 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which
6759 case the value of :term:`DEBUG_OPTIMIZATION` is used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006760
Andrew Geisslerf0343792020-11-18 10:42:21 -06006761 :term:`SERIAL_CONSOLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006762 Defines a serial console (TTY) to enable using
6763 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6764 value that specifies the baud rate followed by the TTY device name
Andrew Geisslerc926e172021-05-07 16:11:35 -05006765 separated by a space. You cannot specify more than one TTY device::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006766
6767 SERIAL_CONSOLE = "115200 ttyS0"
6768
6769 .. note::
6770
Andrew Geissler09036742021-06-25 14:25:14 -05006771 The :term:`SERIAL_CONSOLE` variable is deprecated. Please use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006772 :term:`SERIAL_CONSOLES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006773
Andrew Geisslerf0343792020-11-18 10:42:21 -06006774 :term:`SERIAL_CONSOLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006775 Defines a serial console (TTY) to enable using
6776 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6777 value that specifies the baud rate followed by the TTY device name
Andrew Geisslerc926e172021-05-07 16:11:35 -05006778 separated by a semicolon. Use spaces to separate multiple devices::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006779
6780 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6781
Andrew Geisslerf0343792020-11-18 10:42:21 -06006782 :term:`SERIAL_CONSOLES_CHECK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006783 Specifies serial consoles, which must be listed in
6784 :term:`SERIAL_CONSOLES`, to check against
6785 ``/proc/console`` before enabling them using getty. This variable
6786 allows aliasing in the format: <device>:<alias>. If a device was
6787 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in
Andrew Geisslerc926e172021-05-07 16:11:35 -05006788 ``/proc/console``, you would do the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006789
6790 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
6791
6792 This variable is currently only supported with SysVinit (i.e. not
Andrew Geisslerc926e172021-05-07 16:11:35 -05006793 with systemd). Note that :term:`SERIAL_CONSOLES_CHECK` also requires
6794 ``/etc/inittab`` to be writable when used with SysVinit. This makes it
6795 incompatible with customizations such as the following::
6796
6797 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006798
Andrew Geisslerf0343792020-11-18 10:42:21 -06006799 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006800 A list of recipe dependencies that should not be used to determine
6801 signatures of tasks from one recipe when they depend on tasks from
Andrew Geisslerc926e172021-05-07 16:11:35 -05006802 another recipe. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006803
6804 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6805
6806 In the previous example, ``intone`` depends on ``mplayer2``.
6807
6808 You can use the special token ``"*"`` on the left-hand side of the
6809 dependency to match all recipes except the one on the right-hand
Andrew Geisslerc926e172021-05-07 16:11:35 -05006810 side. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006811
6812 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
6813
6814 In the previous example, all recipes except ``quilt-native`` ignore
6815 task signatures from the ``quilt-native`` recipe when determining
6816 their task signatures.
6817
6818 Use of this variable is one mechanism to remove dependencies that
6819 affect task signatures and thus force rebuilds when a recipe changes.
6820
6821 .. note::
6822
6823 If you add an inappropriate dependency for a recipe relationship,
6824 the software might break during runtime if the interface of the
6825 second recipe was changed after the first recipe had been built.
6826
Andrew Geisslerf0343792020-11-18 10:42:21 -06006827 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006828 A list of recipes that are completely stable and will never change.
6829 The ABI for the recipes in the list are presented by output from the
6830 tasks run to build the recipe. Use of this variable is one way to
6831 remove dependencies from one recipe on another that affect task
6832 signatures and thus force rebuilds when the recipe changes.
6833
6834 .. note::
6835
6836 If you add an inappropriate variable to this list, the software
6837 might break at runtime if the interface of the recipe was changed
6838 after the other had been built.
6839
Andrew Geisslerf0343792020-11-18 10:42:21 -06006840 :term:`SITEINFO_BITS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006841 Specifies the number of bits for the target system CPU. The value
6842 should be either "32" or "64".
6843
Andrew Geisslerf0343792020-11-18 10:42:21 -06006844 :term:`SITEINFO_ENDIANNESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006845 Specifies the endian byte order of the target system. The value
6846 should be either "le" for little-endian or "be" for big-endian.
6847
Andrew Geisslerf0343792020-11-18 10:42:21 -06006848 :term:`SKIP_FILEDEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006849 Enables removal of all files from the "Provides" section of an RPM
6850 package. Removal of these files is required for packages containing
6851 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
6852
6853 To enable file removal, set the variable to "1" in your
6854 ``conf/local.conf`` configuration file in your:
6855 :term:`Build Directory`.
6856 ::
6857
6858 SKIP_FILEDEPS = "1"
6859
Andrew Geisslerf0343792020-11-18 10:42:21 -06006860 :term:`SOC_FAMILY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006861 Groups together machines based upon the same family of SOC (System On
6862 Chip). You typically set this variable in a common ``.inc`` file that
6863 you include in the configuration files of all the machines.
6864
6865 .. note::
6866
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006867 You must include ``conf/machine/include/soc-family.inc`` for this
6868 variable to appear in :term:`MACHINEOVERRIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006869
Andrew Geisslerf0343792020-11-18 10:42:21 -06006870 :term:`SOLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006871 Defines the suffix for shared libraries used on the target platform.
6872 By default, this suffix is ".so.*" for all Linux-based systems and is
6873 defined in the ``meta/conf/bitbake.conf`` configuration file.
6874
6875 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006876 ``FILES:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006877
Andrew Geisslerf0343792020-11-18 10:42:21 -06006878 :term:`SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006879 Defines the suffix for the development symbolic link (symlink) for
6880 shared libraries on the target platform. By default, this suffix is
6881 ".so" for Linux-based systems and is defined in the
6882 ``meta/conf/bitbake.conf`` configuration file.
6883
6884 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006885 ``FILES:${PN}-dev``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006886
Andrew Geisslerf0343792020-11-18 10:42:21 -06006887 :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006888 When you are fetching files to create a mirror of sources (i.e.
Andrew Geissler09036742021-06-25 14:25:14 -05006889 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006890 your ``local.conf`` configuration file ensures the source for all
6891 recipes are fetched regardless of whether or not a recipe is
6892 compatible with the configuration. A recipe is considered
6893 incompatible with the currently configured machine when either or
6894 both the :term:`COMPATIBLE_MACHINE`
6895 variable and :term:`COMPATIBLE_HOST` variables
6896 specify compatibility with a machine other than that of the current
6897 machine or host.
6898
6899 .. note::
6900
Andrew Geissler09036742021-06-25 14:25:14 -05006901 Do not set the :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006902 variable unless you are creating a source mirror. In other words,
6903 do not set the variable during a normal build.
6904
Andrew Geisslerf0343792020-11-18 10:42:21 -06006905 :term:`SOURCE_MIRROR_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006906 Defines your own :term:`PREMIRRORS` from which to
6907 first fetch source before attempting to fetch from the upstream
6908 specified in :term:`SRC_URI`.
6909
6910 To use this variable, you must globally inherit the
6911 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide
Andrew Geisslerc926e172021-05-07 16:11:35 -05006912 the URL to your mirrors. Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006913
6914 INHERIT += "own-mirrors"
6915 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
6916
6917 .. note::
6918
Andrew Geissler09036742021-06-25 14:25:14 -05006919 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006920
Andrew Geisslerf0343792020-11-18 10:42:21 -06006921 :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006922 Maps commonly used license names to their SPDX counterparts found in
Andrew Geissler09036742021-06-25 14:25:14 -05006923 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006924 mappings, see the ``meta/conf/licenses.conf`` file.
6925
6926 For additional information, see the :term:`LICENSE`
6927 variable.
6928
Andrew Geisslerf0343792020-11-18 10:42:21 -06006929 :term:`SPECIAL_PKGSUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006930 A list of prefixes for :term:`PN` used by the OpenEmbedded
6931 build system to create variants of recipes or packages. The list
6932 specifies the prefixes to strip off during certain circumstances such
6933 as the generation of the :term:`BPN` variable.
6934
Andrew Geisslerf0343792020-11-18 10:42:21 -06006935 :term:`SPL_BINARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006936 The file type for the Secondary Program Loader (SPL). Some devices
6937 use an SPL from which to boot (e.g. the BeagleBone development
6938 board). For such cases, you can declare the file type of the SPL
6939 binary in the ``u-boot.inc`` include file, which is used in the
6940 U-Boot recipe.
6941
6942 The SPL file type is set to "null" by default in the ``u-boot.inc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05006943 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006944
6945 # Some versions of u-boot build an SPL (Second Program Loader) image that
6946 # should be packaged along with the u-boot binary as well as placed in the
6947 # deploy directory. For those versions they can set the following variables
6948 # to allow packaging the SPL.
6949 SPL_BINARY ?= ""
6950 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
6951 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
6952 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
6953
Andrew Geissler09036742021-06-25 14:25:14 -05006954 The :term:`SPL_BINARY` variable helps form
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006955 various ``SPL_*`` variables used by the OpenEmbedded build system.
6956
6957 See the BeagleBone machine configuration example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006958 ":ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006959 section in the Yocto Project Board Support Package Developer's Guide
6960 for additional information.
6961
Andrew Geisslerf0343792020-11-18 10:42:21 -06006962 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006963 The list of source files - local or remote. This variable tells the
6964 OpenEmbedded build system which bits to pull in for the build and how
6965 to pull them in. For example, if the recipe or append file only needs
6966 to fetch a tarball from the Internet, the recipe or append file uses
Andrew Geissler09036742021-06-25 14:25:14 -05006967 a single :term:`SRC_URI` entry. On the other hand, if the recipe or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006968 append file needs to fetch a tarball, apply two patches, and include
6969 a custom file, the recipe or append file would include four instances
6970 of the variable.
6971
6972 The following list explains the available URI protocols. URI
6973 protocols are highly dependent on particular BitBake Fetcher
6974 submodules. Depending on the fetcher BitBake uses, various URL
6975 parameters are employed. For specifics on the supported Fetchers, see
Patrick Williams213cb262021-08-07 19:21:33 -05006976 the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006977 BitBake User Manual.
6978
6979 - ``file://`` - Fetches files, which are usually files shipped
6980 with the :term:`Metadata`, from the local machine (e.g.
Andrew Geissler09209ee2020-12-13 08:44:15 -06006981 :ref:`patch <overview-manual/concepts:patching>` files).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006982 The path is relative to the :term:`FILESPATH`
6983 variable. Thus, the build system searches, in order, from the
6984 following directories, which are assumed to be a subdirectories of
6985 the directory in which the recipe file (``.bb``) or append file
6986 (``.bbappend``) resides:
6987
6988 - ``${BPN}`` - The base recipe name without any special suffix
6989 or version numbers.
6990
6991 - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and
6992 version but without any special package name suffix.
6993
6994 - *files -* Files within a directory, which is named ``files``
6995 and is also alongside the recipe or append file.
6996
6997 .. note::
6998
6999 If you want the build system to pick up files specified through
7000 a
7001 SRC_URI
7002 statement from your append file, you need to be sure to extend
7003 the
7004 FILESPATH
7005 variable by also using the
7006 FILESEXTRAPATHS
7007 variable from within your append file.
7008
7009 - ``bzr://`` - Fetches files from a Bazaar revision control
7010 repository.
7011
7012 - ``git://`` - Fetches files from a Git revision control
7013 repository.
7014
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007015 - ``osc://`` - Fetches files from an OSC (openSUSE Build service)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007016 revision control repository.
7017
7018 - ``repo://`` - Fetches files from a repo (Git) repository.
7019
7020 - ``ccrc://`` - Fetches files from a ClearCase repository.
7021
7022 - ``http://`` - Fetches files from the Internet using ``http``.
7023
7024 - ``https://`` - Fetches files from the Internet using ``https``.
7025
7026 - ``ftp://`` - Fetches files from the Internet using ``ftp``.
7027
7028 - ``cvs://`` - Fetches files from a CVS revision control
7029 repository.
7030
7031 - ``hg://`` - Fetches files from a Mercurial (``hg``) revision
7032 control repository.
7033
7034 - ``p4://`` - Fetches files from a Perforce (``p4``) revision
7035 control repository.
7036
7037 - ``ssh://`` - Fetches files from a secure shell.
7038
7039 - ``svn://`` - Fetches files from a Subversion (``svn``) revision
7040 control repository.
7041
7042 - ``npm://`` - Fetches JavaScript modules from a registry.
7043
Andrew Geissler95ac1b82021-03-31 14:34:31 -05007044 - ``az://`` - Fetches files from an Azure Storage account.
7045
Andrew Geissler09036742021-06-25 14:25:14 -05007046 There are standard and recipe-specific options for :term:`SRC_URI`. Here are
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007047 standard ones:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007048
7049 - ``apply`` - Whether to apply the patch or not. The default
7050 action is to apply the patch.
7051
7052 - ``striplevel`` - Which striplevel to use when applying the
7053 patch. The default level is 1.
7054
7055 - ``patchdir`` - Specifies the directory in which the patch should
7056 be applied. The default is ``${``\ :term:`S`\ ``}``.
7057
7058 Here are options specific to recipes building code from a revision
7059 control system:
7060
7061 - ``mindate`` - Apply the patch only if
7062 :term:`SRCDATE` is equal to or greater than
7063 ``mindate``.
7064
Andrew Geissler09036742021-06-25 14:25:14 -05007065 - ``maxdate`` - Apply the patch only if :term:`SRCDATE` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007066 than ``maxdate``.
7067
Andrew Geissler09036742021-06-25 14:25:14 -05007068 - ``minrev`` - Apply the patch only if :term:`SRCREV` is equal to or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007069 greater than ``minrev``.
7070
Andrew Geissler09036742021-06-25 14:25:14 -05007071 - ``maxrev`` - Apply the patch only if :term:`SRCREV` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007072 than ``maxrev``.
7073
Andrew Geissler09036742021-06-25 14:25:14 -05007074 - ``rev`` - Apply the patch only if :term:`SRCREV` is equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007075 ``rev``.
7076
Andrew Geissler09036742021-06-25 14:25:14 -05007077 - ``notrev`` - Apply the patch only if :term:`SRCREV` is not equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007078 ``rev``.
7079
7080 Here are some additional options worth mentioning:
7081
7082 - ``unpack`` - Controls whether or not to unpack the file if it is
7083 an archive. The default action is to unpack the file.
7084
7085 - ``destsuffix`` - Places the file (or extracts its contents) into
7086 the specified subdirectory of :term:`WORKDIR` when
7087 the Git fetcher is used.
7088
7089 - ``subdir`` - Places the file (or extracts its contents) into the
Andrew Geissler09036742021-06-25 14:25:14 -05007090 specified subdirectory of :term:`WORKDIR` when the local (``file://``)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007091 fetcher is used.
7092
7093 - ``localdir`` - Places the file (or extracts its contents) into
Andrew Geissler09036742021-06-25 14:25:14 -05007094 the specified subdirectory of :term:`WORKDIR` when the CVS fetcher is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007095 used.
7096
7097 - ``subpath`` - Limits the checkout to a specific subpath of the
7098 tree when using the Git fetcher is used.
7099
7100 - ``name`` - Specifies a name to be used for association with
Andrew Geissler09036742021-06-25 14:25:14 -05007101 :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one
7102 file or git repository specified in :term:`SRC_URI`. For example::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007103
7104 SRC_URI = "git://example.com/foo.git;name=first \
7105 git://example.com/bar.git;name=second \
7106 http://example.com/file.tar.gz;name=third"
7107
7108 SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
7109 SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f"
7110 SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"
7111
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007112
7113 - ``downloadfilename`` - Specifies the filename used when storing
7114 the downloaded file.
7115
Andrew Geisslerf0343792020-11-18 10:42:21 -06007116 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007117 By default, the OpenEmbedded build system automatically detects
Andrew Geissler5f350902021-07-23 13:09:54 -04007118 whether :term:`SRC_URI` contains files that are machine-specific. If so,
Andrew Geissler09036742021-06-25 14:25:14 -05007119 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007120 variable to "0" disables this behavior.
7121
Andrew Geisslerf0343792020-11-18 10:42:21 -06007122 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007123 The date of the source code used to build the package. This variable
7124 applies only if the source was fetched from a Source Code Manager
7125 (SCM).
7126
Andrew Geisslerf0343792020-11-18 10:42:21 -06007127 :term:`SRCPV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007128 Returns the version string of the current package. This string is
7129 used to help define the value of :term:`PV`.
7130
Andrew Geissler09036742021-06-25 14:25:14 -05007131 The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007132 configuration file in the :term:`Source Directory` as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007133 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007134
7135 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7136
Andrew Geissler09036742021-06-25 14:25:14 -05007137 Recipes that need to define :term:`PV` do so with the help of the
7138 :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007139 located in ``meta/recipes-connectivity`` in the Source Directory
Andrew Geissler09036742021-06-25 14:25:14 -05007140 defines :term:`PV` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007141
7142 PV = "0.12-git${SRCPV}"
7143
Andrew Geisslerf0343792020-11-18 10:42:21 -06007144 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007145 The revision of the source code used to build the package. This
7146 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
7147 that if you want to build a fixed revision and you want to avoid
7148 performing a query on the remote repository every time BitBake parses
Andrew Geissler09036742021-06-25 14:25:14 -05007149 your recipe, you should specify a :term:`SRCREV` that is a full revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007150 identifier and not just a tag.
7151
7152 .. note::
7153
7154 For information on limitations when inheriting the latest revision
Andrew Geissler09036742021-06-25 14:25:14 -05007155 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007156 description and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007157 ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007158 section, which is in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007159
Andrew Geissler09036742021-06-25 14:25:14 -05007160 :term:`SRCTREECOVEREDTASKS`
7161 A list of tasks that are typically not relevant (and therefore skipped)
7162 when building using the :ref:`externalsrc <ref-classes-externalsrc>`
7163 class. The default value as set in that class file is the set of tasks
7164 that are rarely needed when using external source::
7165
7166 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
7167
7168 The notable exception is when processing external kernel source as
7169 defined in the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
7170 class file (formatted for aesthetics)::
7171
7172 SRCTREECOVEREDTASKS += "\
7173 do_validate_branches \
7174 do_kernel_configcheck \
7175 do_kernel_checkout \
7176 do_fetch \
7177 do_unpack \
7178 do_patch \
7179 "
7180
7181 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD`
7182 variables for more information.
7183
Andrew Geisslerf0343792020-11-18 10:42:21 -06007184 :term:`SSTATE_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007185 The directory for the shared state cache.
7186
Andrew Geisslerf0343792020-11-18 10:42:21 -06007187 :term:`SSTATE_MIRROR_ALLOW_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007188 If set to "1", allows fetches from mirrors that are specified in
7189 :term:`SSTATE_MIRRORS` to work even when
Andrew Geissler09036742021-06-25 14:25:14 -05007190 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to
7191 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if
7192 you have set :term:`SSTATE_MIRRORS` to point to an internal server for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007193 your shared state cache, but you want to disable any other fetching
7194 from the network.
7195
Andrew Geisslerf0343792020-11-18 10:42:21 -06007196 :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007197 Configures the OpenEmbedded build system to search other mirror
7198 locations for prebuilt cache data objects before building out the
7199 data. This variable works like fetcher :term:`MIRRORS`
7200 and :term:`PREMIRRORS` and points to the cache
7201 locations to check for the shared state (sstate) objects.
7202
7203 You can specify a filesystem directory or a remote URL such as HTTP
7204 or FTP. The locations you specify need to contain the shared state
7205 cache (sstate-cache) results from previous builds. The sstate-cache
7206 you point to can also be from builds on other machines.
7207
7208 When pointing to sstate build artifacts on another machine that uses
7209 a different GCC version for native builds, you must configure
Andrew Geissler09036742021-06-25 14:25:14 -05007210 :term:`SSTATE_MIRRORS` with a regular expression that maps local search
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007211 paths to server paths. The paths need to take into account
7212 :term:`NATIVELSBSTRING` set by the
7213 :ref:`uninative <ref-classes-uninative>` class. For example, the
7214 following maps the local search path ``universal-4.9`` to the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007215 server-provided path server_url_sstate_path::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007216
7217 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n"
7218
7219 If a mirror uses the same structure as
7220 :term:`SSTATE_DIR`, you need to add "PATH" at the
7221 end as shown in the examples below. The build system substitutes the
7222 correct path within the directory structure.
7223 ::
7224
7225 SSTATE_MIRRORS ?= "\
7226 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
7227 file://.* file:///some-local-dir/sstate/PATH"
7228
Andrew Geisslerf0343792020-11-18 10:42:21 -06007229 :term:`SSTATE_SCAN_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007230 Controls the list of files the OpenEmbedded build system scans for
7231 hardcoded installation paths. The variable uses a space-separated
7232 list of filenames (not paths) with standard wildcard characters
7233 allowed.
7234
7235 During a build, the OpenEmbedded build system creates a shared state
7236 (sstate) object during the first stage of preparing the sysroots.
7237 That object is scanned for hardcoded paths for original installation
7238 locations. The list of files that are scanned for paths is controlled
Andrew Geissler09036742021-06-25 14:25:14 -05007239 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files
7240 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007241 than the variable being comprehensively set. The
7242 :ref:`sstate <ref-classes-sstate>` class specifies the default list
7243 of files.
7244
7245 For details on the process, see the
7246 :ref:`staging <ref-classes-staging>` class.
7247
Andrew Geisslerf0343792020-11-18 10:42:21 -06007248 :term:`STAGING_BASE_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007249 Specifies the path to the ``/lib`` subdirectory of the sysroot
7250 directory for the build host.
7251
Andrew Geisslerf0343792020-11-18 10:42:21 -06007252 :term:`STAGING_BASELIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007253 Specifies the path to the ``/lib`` subdirectory of the sysroot
7254 directory for the target for which the current recipe is being built
7255 (:term:`STAGING_DIR_HOST`).
7256
Andrew Geisslerf0343792020-11-18 10:42:21 -06007257 :term:`STAGING_BINDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007258 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
7259 directory for the target for which the current recipe is being built
7260 (:term:`STAGING_DIR_HOST`).
7261
Andrew Geisslerf0343792020-11-18 10:42:21 -06007262 :term:`STAGING_BINDIR_CROSS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007263 Specifies the path to the directory containing binary configuration
7264 scripts. These scripts provide configuration information for other
7265 software that wants to make use of libraries or include files
7266 provided by the software associated with the script.
7267
7268 .. note::
7269
7270 This style of build configuration has been largely replaced by
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007271 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the
7272 library to which you are linking, it is recommended you use
7273 ``pkg-config`` instead of a provided configuration script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007274
Andrew Geisslerf0343792020-11-18 10:42:21 -06007275 :term:`STAGING_BINDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007276 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
7277 directory for the build host.
7278
Andrew Geisslerf0343792020-11-18 10:42:21 -06007279 :term:`STAGING_DATADIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007280 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
7281 directory for the target for which the current recipe is being built
7282 (:term:`STAGING_DIR_HOST`).
7283
Andrew Geisslerf0343792020-11-18 10:42:21 -06007284 :term:`STAGING_DATADIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007285 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
7286 directory for the build host.
7287
Andrew Geisslerf0343792020-11-18 10:42:21 -06007288 :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007289 Helps construct the ``recipe-sysroots`` directory, which is used
7290 during packaging.
7291
7292 For information on how staging for recipe-specific sysroots occurs,
7293 see the :ref:`ref-tasks-populate_sysroot`
Andrew Geissler09209ee2020-12-13 08:44:15 -06007294 task, the ":ref:`sdk-manual/extensible:sharing files between recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007295 section in the Yocto Project Development Tasks Manual, the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007296 ":ref:`overview-manual/concepts:configuration, compilation, and staging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007297 section in the Yocto Project Overview and Concepts Manual, and the
7298 :term:`SYSROOT_DIRS` variable.
7299
7300 .. note::
7301
Andrew Geissler09036742021-06-25 14:25:14 -05007302 Recipes should never write files directly under the :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007303 directory because the OpenEmbedded build system manages the
7304 directory automatically. Instead, files should be installed to
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007305 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007306 task and then the OpenEmbedded build system will stage a subset of
7307 those files into the sysroot.
7308
Andrew Geisslerf0343792020-11-18 10:42:21 -06007309 :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007310 Specifies the path to the sysroot directory for the system on which
7311 the component is built to run (the system that hosts the component).
7312 For most recipes, this sysroot is the one in which that recipe's
7313 :ref:`ref-tasks-populate_sysroot` task copies
7314 files. Exceptions include ``-native`` recipes, where the
7315 ``do_populate_sysroot`` task instead uses
7316 :term:`STAGING_DIR_NATIVE`. Depending on
Andrew Geissler09036742021-06-25 14:25:14 -05007317 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007318 have the following values:
7319
7320 - For recipes building for the target machine, the value is
7321 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
7322
7323 - For native recipes building for the build host, the value is empty
7324 given the assumption that when building for the build host, the
7325 build host's own directories should be used.
7326
7327 .. note::
7328
7329 ``-native`` recipes are not installed into host paths like such
7330 as ``/usr``. Rather, these recipes are installed into
Andrew Geissler5f350902021-07-23 13:09:54 -04007331 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007332 standard build environment variables such as
7333 :term:`CPPFLAGS` and
7334 :term:`CFLAGS` are set up so that both host paths
Andrew Geissler09036742021-06-25 14:25:14 -05007335 and :term:`STAGING_DIR_NATIVE` are searched for libraries and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007336 headers using, for example, GCC's ``-isystem`` option.
7337
7338 Thus, the emphasis is that the ``STAGING_DIR*`` variables
7339 should be viewed as input variables by tasks such as
7340 :ref:`ref-tasks-configure`,
7341 :ref:`ref-tasks-compile`, and
7342 :ref:`ref-tasks-install`. Having the real system
Andrew Geissler09036742021-06-25 14:25:14 -05007343 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007344 for ``-native`` recipes, as they make use of host headers and
7345 libraries.
7346
Andrew Geisslerf0343792020-11-18 10:42:21 -06007347 :term:`STAGING_DIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007348 Specifies the path to the sysroot directory used when building
7349 components that run on the build host itself.
7350
Andrew Geisslerf0343792020-11-18 10:42:21 -06007351 :term:`STAGING_DIR_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007352 Specifies the path to the sysroot used for the system for which the
7353 component generates code. For components that do not generate code,
Andrew Geissler09036742021-06-25 14:25:14 -05007354 which is the majority, :term:`STAGING_DIR_TARGET` is set to match
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007355 :term:`STAGING_DIR_HOST`.
7356
7357 Some recipes build binaries that can run on the target system but
7358 those binaries in turn generate code for another different system
7359 (e.g. cross-canadian recipes). Using terminology from GNU, the
7360 primary system is referred to as the "HOST" and the secondary, or
7361 different, system is referred to as the "TARGET". Thus, the binaries
7362 run on the "HOST" system and generate binaries for the "TARGET"
Andrew Geissler09036742021-06-25 14:25:14 -05007363 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used
7364 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007365 sysroot used for the "TARGET" system.
7366
Andrew Geisslerf0343792020-11-18 10:42:21 -06007367 :term:`STAGING_ETCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007368 Specifies the path to the ``/etc`` subdirectory of the sysroot
7369 directory for the build host.
7370
Andrew Geisslerf0343792020-11-18 10:42:21 -06007371 :term:`STAGING_EXECPREFIXDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007372 Specifies the path to the ``/usr`` subdirectory of the sysroot
7373 directory for the target for which the current recipe is being built
7374 (:term:`STAGING_DIR_HOST`).
7375
Andrew Geisslerf0343792020-11-18 10:42:21 -06007376 :term:`STAGING_INCDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007377 Specifies the path to the ``/usr/include`` subdirectory of the
7378 sysroot directory for the target for which the current recipe being
7379 built (:term:`STAGING_DIR_HOST`).
7380
Andrew Geisslerf0343792020-11-18 10:42:21 -06007381 :term:`STAGING_INCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007382 Specifies the path to the ``/usr/include`` subdirectory of the
7383 sysroot directory for the build host.
7384
Andrew Geisslerf0343792020-11-18 10:42:21 -06007385 :term:`STAGING_KERNEL_BUILDDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007386 Points to the directory containing the kernel build artifacts.
7387 Recipes building software that needs to access kernel build artifacts
7388 (e.g. ``systemtap-uprobes``) can look in the directory specified with
Andrew Geissler09036742021-06-25 14:25:14 -05007389 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007390 after the kernel has been built.
7391
Andrew Geisslerf0343792020-11-18 10:42:21 -06007392 :term:`STAGING_KERNEL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007393 The directory with kernel headers that are required to build
7394 out-of-tree modules.
7395
Andrew Geisslerf0343792020-11-18 10:42:21 -06007396 :term:`STAGING_LIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007397 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
7398 directory for the target for which the current recipe is being built
7399 (:term:`STAGING_DIR_HOST`).
7400
Andrew Geisslerf0343792020-11-18 10:42:21 -06007401 :term:`STAGING_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007402 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
7403 directory for the build host.
7404
Andrew Geisslerf0343792020-11-18 10:42:21 -06007405 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007406 Specifies the base path used to create recipe stamp files. The path
7407 to an actual stamp file is constructed by evaluating this string and
7408 then appending additional information. Currently, the default
Andrew Geissler09036742021-06-25 14:25:14 -05007409 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05007410 file is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007411
7412 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7413
7414 For information on how BitBake uses stamp files to determine if a
7415 task should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007416 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007417 section in the Yocto Project Overview and Concepts Manual.
7418
7419 See :term:`STAMPS_DIR`,
7420 :term:`MULTIMACH_TARGET_SYS`,
7421 :term:`PN`, :term:`EXTENDPE`,
7422 :term:`PV`, and :term:`PR` for related variable
7423 information.
7424
Andrew Geisslerf0343792020-11-18 10:42:21 -06007425 :term:`STAMPS_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007426 Specifies the base directory in which the OpenEmbedded build system
7427 places stamps. The default directory is ``${TMPDIR}/stamps``.
7428
Andrew Geisslerf0343792020-11-18 10:42:21 -06007429 :term:`STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007430 The minimal command and arguments to run ``strip``, which is used to
7431 strip symbols.
7432
Andrew Geisslerf0343792020-11-18 10:42:21 -06007433 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007434 The short (72 characters or less) summary of the binary package for
7435 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05007436 :term:`SUMMARY` is used to define the
7437 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007438 not set in the recipe.
7439
Andrew Geisslerf0343792020-11-18 10:42:21 -06007440 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007441 The directory in which files checked out of a Subversion system are
7442 stored.
7443
Andrew Geisslerf0343792020-11-18 10:42:21 -06007444 :term:`SYSLINUX_DEFAULT_CONSOLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007445 Specifies the kernel boot default console. If you want to use a
7446 console other than the default, set this variable in your recipe as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007447 follows where "X" is the console number you want to use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007448
7449 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7450
7451 The :ref:`syslinux <ref-classes-syslinux>` class initially sets
7452 this variable to null but then checks for a value later.
7453
Andrew Geisslerf0343792020-11-18 10:42:21 -06007454 :term:`SYSLINUX_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007455 Lists additional options to add to the syslinux file. You need to set
7456 this variable in your recipe. If you want to list multiple options,
7457 separate the options with a semicolon character (``;``).
7458
7459 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable
7460 to create a set of options.
7461
Andrew Geisslerf0343792020-11-18 10:42:21 -06007462 :term:`SYSLINUX_SERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007463 Specifies the alternate serial port or turns it off. To turn off
7464 serial, set this variable to an empty string in your recipe. The
7465 variable's default value is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007466 :ref:`syslinux <ref-classes-syslinux>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007467
7468 SYSLINUX_SERIAL ?= "0 115200"
7469
7470 The class checks for and uses the variable as needed.
7471
Andrew Geisslerf0343792020-11-18 10:42:21 -06007472 :term:`SYSLINUX_SERIAL_TTY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007473 Specifies the alternate console=tty... kernel boot argument. The
7474 variable's default value is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007475 :ref:`syslinux <ref-classes-syslinux>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007476
7477 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7478
7479 The class checks for and uses the variable as needed.
7480
Andrew Geisslerf0343792020-11-18 10:42:21 -06007481 :term:`SYSLINUX_SPLASH`
7482 An ``.LSS`` file used as the background for the VGA boot menu when
7483 you use the boot menu. You need to set this variable in your recipe.
7484
7485 The :ref:`syslinux <ref-classes-syslinux>` class checks for this
7486 variable and if found, the OpenEmbedded build system installs the
7487 splash screen.
7488
7489 :term:`SYSROOT_DESTDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007490 Points to the temporary directory under the work directory (default
7491 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
7492 where the files populated into the sysroot are assembled during the
7493 :ref:`ref-tasks-populate_sysroot` task.
7494
Andrew Geisslerf0343792020-11-18 10:42:21 -06007495 :term:`SYSROOT_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007496 Directories that are staged into the sysroot by the
7497 :ref:`ref-tasks-populate_sysroot` task. By
Andrew Geisslerc926e172021-05-07 16:11:35 -05007498 default, the following directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007499
7500 SYSROOT_DIRS = " \
7501 ${includedir} \
7502 ${libdir} \
7503 ${base_libdir} \
7504 ${nonarch_base_libdir} \
7505 ${datadir} \
7506 "
7507
Andrew Geisslerf0343792020-11-18 10:42:21 -06007508 :term:`SYSROOT_DIRS_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007509 Directories that are not staged into the sysroot by the
7510 :ref:`ref-tasks-populate_sysroot` task. You
7511 can use this variable to exclude certain subdirectories of
7512 directories listed in :term:`SYSROOT_DIRS` from
Andrew Geisslerc926e172021-05-07 16:11:35 -05007513 staging. By default, the following directories are not staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007514
7515 SYSROOT_DIRS_BLACKLIST = " \
7516 ${mandir} \
7517 ${docdir} \
7518 ${infodir} \
7519 ${datadir}/locale \
7520 ${datadir}/applications \
7521 ${datadir}/fonts \
7522 ${datadir}/pixmaps \
7523 "
7524
Andrew Geisslerf0343792020-11-18 10:42:21 -06007525 :term:`SYSROOT_DIRS_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007526 Extra directories staged into the sysroot by the
7527 :ref:`ref-tasks-populate_sysroot` task for
7528 ``-native`` recipes, in addition to those specified in
7529 :term:`SYSROOT_DIRS`. By default, the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05007530 extra directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007531
7532 SYSROOT_DIRS_NATIVE = " \
7533 ${bindir} \
7534 ${sbindir} \
7535 ${base_bindir} \
7536 ${base_sbindir} \
7537 ${libexecdir} \
7538 ${sysconfdir} \
7539 ${localstatedir} \
7540 "
7541
7542 .. note::
7543
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007544 Programs built by ``-native`` recipes run directly from the sysroot
7545 (:term:`STAGING_DIR_NATIVE`), which is why additional directories
7546 containing program executables and supporting files need to be staged.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007547
Andrew Geisslerf0343792020-11-18 10:42:21 -06007548 :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007549 A list of functions to execute after files are staged into the
7550 sysroot. These functions are usually used to apply additional
7551 processing on the staged files, or to stage additional files.
7552
Andrew Geisslerf0343792020-11-18 10:42:21 -06007553 :term:`SYSTEMD_AUTO_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007554 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7555 this variable specifies whether the specified service in
7556 :term:`SYSTEMD_SERVICE` should start
7557 automatically or not. By default, the service is enabled to
7558 automatically start at boot time. The default setting is in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007559 :ref:`systemd <ref-classes-systemd>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007560
7561 SYSTEMD_AUTO_ENABLE ??= "enable"
7562
7563 You can disable the service by setting the variable to "disable".
7564
Andrew Geisslerf0343792020-11-18 10:42:21 -06007565 :term:`SYSTEMD_BOOT_CFG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007566 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007567 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007568 configuration file that should be used. By default, the
7569 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007570 :term:`SYSTEMD_BOOT_CFG` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007571
7572 SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf"
7573
7574 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007575 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007576
Andrew Geisslerf0343792020-11-18 10:42:21 -06007577 :term:`SYSTEMD_BOOT_ENTRIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007578 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007579 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007580 list of entry files (``*.conf``) to install that contain one boot
7581 entry per file. By default, the
7582 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007583 :term:`SYSTEMD_BOOT_ENTRIES` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007584
7585 SYSTEMD_BOOT_ENTRIES ?= ""
7586
7587 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007588 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007589
Andrew Geisslerf0343792020-11-18 10:42:21 -06007590 :term:`SYSTEMD_BOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007591 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007592 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007593 boot menu timeout in seconds. By default, the
7594 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007595 :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007596
7597 SYSTEMD_BOOT_TIMEOUT ?= "10"
7598
7599 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007600 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007601
Andrew Geisslerf0343792020-11-18 10:42:21 -06007602 :term:`SYSTEMD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007603 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7604 this variable locates the systemd unit files when they are not found
Andrew Geissler09036742021-06-25 14:25:14 -05007605 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007606 variable is set such that the systemd unit files are assumed to
Andrew Geisslerc926e172021-05-07 16:11:35 -05007607 reside in the recipes main package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007608
7609 SYSTEMD_PACKAGES ?= "${PN}"
7610
7611 If these unit files are not in this recipe's main package, you need
Andrew Geissler09036742021-06-25 14:25:14 -05007612 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007613 the build system can find the systemd unit files.
7614
Andrew Geisslerf0343792020-11-18 10:42:21 -06007615 :term:`SYSTEMD_SERVICE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007616 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7617 this variable specifies the systemd service name for a package.
7618
7619 When you specify this file in your recipe, use a package name
7620 override to indicate the package to which the value applies. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05007621 an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007622
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007623 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007624
Andrew Geisslerf0343792020-11-18 10:42:21 -06007625 :term:`SYSVINIT_ENABLED_GETTYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007626 When using
Andrew Geissler09209ee2020-12-13 08:44:15 -06007627 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007628 specifies a space-separated list of the virtual terminals that should
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007629 run a `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007630 (allowing login), assuming :term:`USE_VT` is not set to
7631 "0".
7632
Andrew Geissler09036742021-06-25 14:25:14 -05007633 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007634 run a getty on the first virtual terminal).
7635
Andrew Geisslerf0343792020-11-18 10:42:21 -06007636 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007637 This variable points to a directory were BitBake places temporary
7638 files, which consist mostly of task logs and scripts, when building a
Andrew Geisslerc926e172021-05-07 16:11:35 -05007639 particular recipe. The variable is typically set as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007640
7641 T = "${WORKDIR}/temp"
7642
7643 The :term:`WORKDIR` is the directory into which
7644 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
7645 file sets this variable.
7646
Andrew Geissler09036742021-06-25 14:25:14 -05007647 The :term:`T` variable is not to be confused with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007648 :term:`TMPDIR` variable, which points to the root of
7649 the directory tree where BitBake places the output of an entire
7650 build.
7651
Andrew Geisslerf0343792020-11-18 10:42:21 -06007652 :term:`TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007653 The target machine's architecture. The OpenEmbedded build system
7654 supports many architectures. Here is an example list of architectures
7655 supported. This list is by no means complete as the architecture is
7656 configurable:
7657
7658 - arm
7659 - i586
7660 - x86_64
7661 - powerpc
7662 - powerpc64
7663 - mips
7664 - mipsel
7665
7666 For additional information on machine architectures, see the
7667 :term:`TUNE_ARCH` variable.
7668
Andrew Geisslerf0343792020-11-18 10:42:21 -06007669 :term:`TARGET_AS_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007670 Specifies architecture-specific assembler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05007671 system. :term:`TARGET_AS_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007672 :term:`TUNE_ASARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05007673 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007674
7675 TARGET_AS_ARCH = "${TUNE_ASARGS}"
7676
Andrew Geisslerf0343792020-11-18 10:42:21 -06007677 :term:`TARGET_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007678 Specifies architecture-specific C compiler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05007679 system. :term:`TARGET_CC_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007680 :term:`TUNE_CCARGS` by default.
7681
7682 .. note::
7683
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007684 It is a common workaround to append :term:`LDFLAGS` to
Andrew Geissler09036742021-06-25 14:25:14 -05007685 :term:`TARGET_CC_ARCH` in recipes that build software for the target that
7686 would not otherwise respect the exported :term:`LDFLAGS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007687
Andrew Geisslerf0343792020-11-18 10:42:21 -06007688 :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007689 This is a specific kernel compiler flag for a CPU or Application
7690 Binary Interface (ABI) tune. The flag is used rarely and only for
7691 cases where a userspace :term:`TUNE_CCARGS` is not
Andrew Geissler09036742021-06-25 14:25:14 -05007692 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007693 variable allows the kernel (and associated modules) to use a
7694 different configuration. See the
7695 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
7696 :term:`Source Directory` for an example.
7697
Andrew Geisslerf0343792020-11-18 10:42:21 -06007698 :term:`TARGET_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007699 Specifies the flags to pass to the C compiler when building for the
7700 target. When building in the target context,
7701 :term:`CFLAGS` is set to the value of this variable by
7702 default.
7703
Andrew Geissler09036742021-06-25 14:25:14 -05007704 Additionally, the SDK's environment setup script sets the :term:`CFLAGS`
7705 variable in the environment to the :term:`TARGET_CFLAGS` value so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007706 executables built using the SDK also have the flags applied.
7707
Andrew Geisslerf0343792020-11-18 10:42:21 -06007708 :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007709 Specifies the flags to pass to the C pre-processor (i.e. to both the
7710 C and the C++ compilers) when building for the target. When building
7711 in the target context, :term:`CPPFLAGS` is set to the
7712 value of this variable by default.
7713
7714 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007715 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007716 value so that executables built using the SDK also have the flags
7717 applied.
7718
Andrew Geisslerf0343792020-11-18 10:42:21 -06007719 :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007720 Specifies the flags to pass to the C++ compiler when building for the
7721 target. When building in the target context,
7722 :term:`CXXFLAGS` is set to the value of this variable
7723 by default.
7724
7725 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007726 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007727 value so that executables built using the SDK also have the flags
7728 applied.
7729
Andrew Geisslerf0343792020-11-18 10:42:21 -06007730 :term:`TARGET_FPU`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007731 Specifies the method for handling FPU code. For FPU-less targets,
7732 which include most ARM CPUs, the variable must be set to "soft". If
7733 not, the kernel emulation gets used, which results in a performance
7734 penalty.
7735
Andrew Geisslerf0343792020-11-18 10:42:21 -06007736 :term:`TARGET_LD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007737 Specifies architecture-specific linker flags for the target system.
Andrew Geissler09036742021-06-25 14:25:14 -05007738 :term:`TARGET_LD_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007739 :term:`TUNE_LDARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05007740 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007741
7742 TARGET_LD_ARCH = "${TUNE_LDARGS}"
7743
Andrew Geisslerf0343792020-11-18 10:42:21 -06007744 :term:`TARGET_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007745 Specifies the flags to pass to the linker when building for the
7746 target. When building in the target context,
7747 :term:`LDFLAGS` is set to the value of this variable
7748 by default.
7749
7750 Additionally, the SDK's environment setup script sets the
7751 :term:`LDFLAGS` variable in the environment to the
Andrew Geissler09036742021-06-25 14:25:14 -05007752 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007753 have the flags applied.
7754
Andrew Geisslerf0343792020-11-18 10:42:21 -06007755 :term:`TARGET_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007756 Specifies the target's operating system. The variable can be set to
7757 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007758 for musl libc. For ARM/EABI targets, the possible values are
7759 "linux-gnueabi" and "linux-musleabi".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007760
Andrew Geisslerf0343792020-11-18 10:42:21 -06007761 :term:`TARGET_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007762 Specifies the prefix used for the toolchain binary target tools.
7763
7764 Depending on the type of recipe and the build target,
Andrew Geissler5f350902021-07-23 13:09:54 -04007765 :term:`TARGET_PREFIX` is set as follows:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007766
7767 - For recipes building for the target machine, the value is
7768 "${:term:`TARGET_SYS`}-".
7769
7770 - For native recipes, the build system sets the variable to the
Andrew Geissler5f350902021-07-23 13:09:54 -04007771 value of :term:`BUILD_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007772
7773 - For native SDK recipes (``nativesdk``), the build system sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007774 variable to the value of :term:`SDK_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007775
Andrew Geisslerf0343792020-11-18 10:42:21 -06007776 :term:`TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007777 Specifies the system, including the architecture and the operating
7778 system, for which the build is occurring in the context of the
7779 current recipe.
7780
7781 The OpenEmbedded build system automatically sets this variable based
7782 on :term:`TARGET_ARCH`,
7783 :term:`TARGET_VENDOR`, and
7784 :term:`TARGET_OS` variables.
7785
7786 .. note::
7787
Andrew Geissler09036742021-06-25 14:25:14 -05007788 You do not need to set the :term:`TARGET_SYS` variable yourself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007789
7790 Consider these two examples:
7791
7792 - Given a native recipe on a 32-bit, x86 machine running Linux, the
7793 value is "i686-linux".
7794
7795 - Given a recipe being built for a little-endian, MIPS target
7796 running Linux, the value might be "mipsel-linux".
7797
Andrew Geisslerf0343792020-11-18 10:42:21 -06007798 :term:`TARGET_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007799 Specifies the name of the target vendor.
7800
Andrew Geisslerf0343792020-11-18 10:42:21 -06007801 :term:`TCLIBC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007802 Specifies the GNU standard C library (``libc``) variant to use during
7803 the build process. This variable replaces ``POKYLIBC``, which is no
7804 longer supported.
7805
7806 You can select "glibc", "musl", "newlib", or "baremetal"
7807
Andrew Geisslerf0343792020-11-18 10:42:21 -06007808 :term:`TCLIBCAPPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007809 Specifies a suffix to be appended onto the
7810 :term:`TMPDIR` value. The suffix identifies the
7811 ``libc`` variant for building. When you are building for multiple
7812 variants with the same :term:`Build Directory`, this
7813 mechanism ensures that output for different ``libc`` variants is kept
7814 separate to avoid potential conflicts.
7815
7816 In the ``defaultsetup.conf`` file, the default value of
Andrew Geissler5f350902021-07-23 13:09:54 -04007817 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007818 which normally only support one ``libc`` variant, set
Andrew Geissler09036742021-06-25 14:25:14 -05007819 :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007820 in no suffix being applied.
7821
Andrew Geisslerf0343792020-11-18 10:42:21 -06007822 :term:`TCMODE`
Andrew Geissler09036742021-06-25 14:25:14 -05007823 Specifies the toolchain selector. :term:`TCMODE` controls the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007824 characteristics of the generated packages and images by telling the
7825 OpenEmbedded build system which toolchain profile to use. By default,
7826 the OpenEmbedded build system builds its own internal toolchain. The
7827 variable's default value is "default", which uses that internal
7828 toolchain.
7829
7830 .. note::
7831
Andrew Geissler09036742021-06-25 14:25:14 -05007832 If :term:`TCMODE` is set to a value other than "default", then it is your
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007833 responsibility to ensure that the toolchain is compatible with the
7834 default toolchain. Using older or newer versions of these
7835 components might cause build problems. See the Release Notes for
7836 the Yocto Project release for the specific components with which
7837 the toolchain must be compatible. To access the Release Notes, go
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007838 to the :yocto_home:`Downloads </software-overview/downloads>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007839 page on the Yocto Project website and click on the "RELEASE
7840 INFORMATION" link for the appropriate release.
7841
Andrew Geissler09036742021-06-25 14:25:14 -05007842 The :term:`TCMODE` variable is similar to :term:`TCLIBC`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007843 which controls the variant of the GNU standard C library (``libc``)
7844 used during the build process: ``glibc`` or ``musl``.
7845
7846 With additional layers, it is possible to use a pre-compiled external
7847 toolchain. One example is the Sourcery G++ Toolchain. The support for
7848 this toolchain resides in the separate Mentor Graphics
7849 ``meta-sourcery`` layer at
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007850 https://github.com/MentorEmbedded/meta-sourcery/.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007851
7852 The layer's ``README`` file contains information on how to use the
7853 Sourcery G++ Toolchain as an external toolchain. In summary, you must
7854 be sure to add the layer to your ``bblayers.conf`` file in front of
7855 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable
7856 in your ``local.conf`` file to the location in which you installed
7857 the toolchain.
7858
7859 The fundamentals used for this example apply to any external
7860 toolchain. You can use ``meta-sourcery`` as a template for adding
7861 support for other external toolchains.
7862
Andrew Geisslerf0343792020-11-18 10:42:21 -06007863 :term:`TEST_EXPORT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007864 The location the OpenEmbedded build system uses to export tests when
7865 the :term:`TEST_EXPORT_ONLY` variable is set
7866 to "1".
7867
Andrew Geissler09036742021-06-25 14:25:14 -05007868 The :term:`TEST_EXPORT_DIR` variable defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007869 ``"${TMPDIR}/testimage/${PN}"``.
7870
Andrew Geisslerf0343792020-11-18 10:42:21 -06007871 :term:`TEST_EXPORT_ONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007872 Specifies to export the tests only. Set this variable to "1" if you
7873 do not want to run the tests but you want them to be exported in a
7874 manner that you to run them outside of the build system.
7875
Andrew Geisslerf0343792020-11-18 10:42:21 -06007876 :term:`TEST_LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007877 Holds the SSH log and the boot log for QEMU machines. The
Andrew Geissler09036742021-06-25 14:25:14 -05007878 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007879
7880 .. note::
7881
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007882 Actual test results reside in the task log (``log.do_testimage``),
7883 which is in the ``${WORKDIR}/temp/`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007884
Andrew Geisslerf0343792020-11-18 10:42:21 -06007885 :term:`TEST_POWERCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007886 For automated hardware testing, specifies the command to use to
7887 control the power of the target machine under test. Typically, this
7888 command would point to a script that performs the appropriate action
7889 (e.g. interacting with a web-enabled power strip). The specified
7890 command should expect to receive as the last argument "off", "on" or
7891 "cycle" specifying to power off, on, or cycle (power off and then
7892 power on) the device, respectively.
7893
Andrew Geisslerf0343792020-11-18 10:42:21 -06007894 :term:`TEST_POWERCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007895 For automated hardware testing, specifies additional arguments to
7896 pass through to the command specified in
7897 :term:`TEST_POWERCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05007898 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007899 wish, for example, to separate the machine-specific and
7900 non-machine-specific parts of the arguments.
7901
Andrew Geisslerf0343792020-11-18 10:42:21 -06007902 :term:`TEST_QEMUBOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007903 The time in seconds allowed for an image to boot before automated
7904 runtime tests begin to run against an image. The default timeout
7905 period to allow the boot process to reach the login prompt is 500
7906 seconds. You can specify a different value in the ``local.conf``
7907 file.
7908
7909 For more information on testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007910 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007911 section in the Yocto Project Development Tasks Manual.
7912
Andrew Geisslerf0343792020-11-18 10:42:21 -06007913 :term:`TEST_SERIALCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007914 For automated hardware testing, specifies the command to use to
7915 connect to the serial console of the target machine under test. This
7916 command simply needs to connect to the serial console and forward
7917 that connection to standard input and output as any normal terminal
7918 program does.
7919
7920 For example, to use the Picocom terminal program on serial device
Andrew Geisslerc926e172021-05-07 16:11:35 -05007921 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007922
7923 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
7924
Andrew Geisslerf0343792020-11-18 10:42:21 -06007925 :term:`TEST_SERIALCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007926 For automated hardware testing, specifies additional arguments to
7927 pass through to the command specified in
7928 :term:`TEST_SERIALCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05007929 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007930 wish, for example, to separate the machine-specific and
7931 non-machine-specific parts of the command.
7932
Andrew Geisslerf0343792020-11-18 10:42:21 -06007933 :term:`TEST_SERVER_IP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007934 The IP address of the build machine (host machine). This IP address
7935 is usually automatically detected. However, if detection fails, this
7936 variable needs to be set to the IP address of the build machine (i.e.
7937 where the build is taking place).
7938
7939 .. note::
7940
Andrew Geissler09036742021-06-25 14:25:14 -05007941 The :term:`TEST_SERVER_IP` variable is only used for a small number of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007942 tests such as the "dnf" test suite, which needs to download packages
7943 from ``WORKDIR/oe-rootfs-repo``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007944
Andrew Geisslerf0343792020-11-18 10:42:21 -06007945 :term:`TEST_SUITES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007946 An ordered list of tests (modules) to run against an image when
7947 performing automated runtime testing.
7948
7949 The OpenEmbedded build system provides a core set of tests that can
7950 be used against images.
7951
7952 .. note::
7953
7954 Currently, there is only support for running these tests under
7955 QEMU.
7956
7957 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
Andrew Geissler09036742021-06-25 14:25:14 -05007958 your own tests to the list of tests by appending :term:`TEST_SUITES` as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007959 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007960
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007961 TEST_SUITES:append = " mytest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007962
7963 Alternatively, you can
7964 provide the "auto" option to have all applicable tests run against
7965 the image.
7966 ::
7967
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007968 TEST_SUITES:append = " auto"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007969
7970 Using this option causes the
7971 build system to automatically run tests that are applicable to the
7972 image. Tests that are not applicable are skipped.
7973
7974 The order in which tests are run is important. Tests that depend on
7975 another test must appear later in the list than the test on which
7976 they depend. For example, if you append the list of tests with two
7977 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
Andrew Geisslerc926e172021-05-07 16:11:35 -05007978 ``test_A``, then you must order the tests as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007979
7980 TEST_SUITES = "test_A test_B"
7981
7982 For more information on testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007983 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007984 section in the Yocto Project Development Tasks Manual.
7985
Andrew Geisslerf0343792020-11-18 10:42:21 -06007986 :term:`TEST_TARGET`
7987 Specifies the target controller to use when running tests against a
Andrew Geisslerc926e172021-05-07 16:11:35 -05007988 test image. The default controller to use is "qemu"::
Andrew Geisslerf0343792020-11-18 10:42:21 -06007989
7990 TEST_TARGET = "qemu"
7991
7992 A target controller is a class that defines how an image gets
7993 deployed on a target and how a target is started. A layer can extend
7994 the controllers by adding a module in the layer's
7995 ``/lib/oeqa/controllers`` directory and by inheriting the
7996 ``BaseTarget`` class, which is an abstract class that cannot be used
Andrew Geissler09036742021-06-25 14:25:14 -05007997 as a value of :term:`TEST_TARGET`.
Andrew Geisslerf0343792020-11-18 10:42:21 -06007998
Andrew Geissler5f350902021-07-23 13:09:54 -04007999 You can provide the following arguments with :term:`TEST_TARGET`:
Andrew Geisslerf0343792020-11-18 10:42:21 -06008000
8001 - *"qemu":* Boots a QEMU image and runs the tests. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008002 ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section
Andrew Geisslerf0343792020-11-18 10:42:21 -06008003 in the Yocto Project Development Tasks Manual for more
8004 information.
8005
8006 - *"simpleremote":* Runs the tests on target hardware that is
8007 already up and running. The hardware can be on the network or it
8008 can be a device running an image on QEMU. You must also set
8009 :term:`TEST_TARGET_IP` when you use
8010 "simpleremote".
8011
8012 .. note::
8013
8014 This argument is defined in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008015 ``meta/lib/oeqa/controllers/simpleremote.py``.
Andrew Geisslerf0343792020-11-18 10:42:21 -06008016
8017 For information on running tests on hardware, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008018 ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008019 section in the Yocto Project Development Tasks Manual.
8020
8021 :term:`TEST_TARGET_IP`
Andrew Geissler09036742021-06-25 14:25:14 -05008022 The IP address of your hardware under test. The :term:`TEST_TARGET_IP`
Andrew Geisslerf0343792020-11-18 10:42:21 -06008023 variable has no effect when :term:`TEST_TARGET` is
8024 set to "qemu".
8025
8026 When you specify the IP address, you can also include a port. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05008027 an example::
Andrew Geisslerf0343792020-11-18 10:42:21 -06008028
8029 TEST_TARGET_IP = "192.168.1.4:2201"
8030
8031 Specifying a port is
8032 useful when SSH is started on a non-standard port or in cases when
8033 your hardware under test is behind a firewall or network that is not
8034 directly accessible from your host and you need to do port address
8035 translation.
8036
8037 :term:`TESTIMAGE_AUTO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008038 Automatically runs the series of automated tests for images when an
Andrew Geissler09036742021-06-25 14:25:14 -05008039 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008040 any image that successfully builds to automatically boot under QEMU.
8041 Using the variable also adds in dependencies so that any SDK for
8042 which testing is requested is automatically built first.
8043
8044 These tests are written in Python making use of the ``unittest``
8045 module, and the majority of them run commands on the target system
8046 over ``ssh``. You can set this variable to "1" in your ``local.conf``
8047 file in the :term:`Build Directory` to have the
8048 OpenEmbedded build system automatically run these tests after an
8049 image successfully builds:
8050
8051 TESTIMAGE_AUTO = "1"
8052
8053 For more information
8054 on enabling, running, and writing these tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008055 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008056 section in the Yocto Project Development Tasks Manual and the
8057 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section.
8058
Andrew Geisslerf0343792020-11-18 10:42:21 -06008059 :term:`THISDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008060 The directory in which the file BitBake is currently parsing is
8061 located. Do not manually set this variable.
8062
Andrew Geisslerf0343792020-11-18 10:42:21 -06008063 :term:`TIME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008064 The time the build was started. Times appear using the hour, minute,
8065 and second (HMS) format (e.g. "140159" for one minute and fifty-nine
8066 seconds past 1400 hours).
8067
Andrew Geisslerf0343792020-11-18 10:42:21 -06008068 :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008069 This variable is the base directory the OpenEmbedded build system
8070 uses for all build output and intermediate files (other than the
Andrew Geissler09036742021-06-25 14:25:14 -05008071 shared state cache). By default, the :term:`TMPDIR` variable points to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008072 ``tmp`` within the :term:`Build Directory`.
8073
8074 If you want to establish this directory in a location other than the
8075 default, you can uncomment and edit the following statement in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008076 ``conf/local.conf`` file in the :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008077
8078 #TMPDIR = "${TOPDIR}/tmp"
8079
Andrew Geissler09036742021-06-25 14:25:14 -05008080 An example use for this scenario is to set :term:`TMPDIR` to a local disk,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008081 which does not use NFS, while having the Build Directory use NFS.
8082
Andrew Geissler09036742021-06-25 14:25:14 -05008083 The filesystem used by :term:`TMPDIR` must have standard filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008084 semantics (i.e. mixed-case files are unique, POSIX file locking, and
8085 persistent inodes). Due to various issues with NFS and bugs in some
8086 implementations, NFS does not meet this minimum requirement.
Andrew Geissler09036742021-06-25 14:25:14 -05008087 Consequently, :term:`TMPDIR` cannot be on NFS.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008088
Andrew Geisslerf0343792020-11-18 10:42:21 -06008089 :term:`TOOLCHAIN_HOST_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008090 This variable lists packages the OpenEmbedded build system uses when
8091 building an SDK, which contains a cross-development environment. The
8092 packages specified by this variable are part of the toolchain set
8093 that runs on the :term:`SDKMACHINE`, and each
8094 package should usually have the prefix ``nativesdk-``. For example,
Andrew Geisslerc926e172021-05-07 16:11:35 -05008095 consider the following command when building an SDK::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008096
8097 $ bitbake -c populate_sdk imagename
8098
8099 In this case, a default list of packages is
8100 set in this variable, but you can add additional packages to the
8101 list. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008102 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008103 in the Yocto Project Application Development and the Extensible
8104 Software Development Kit (eSDK) manual for more information.
8105
8106 For background information on cross-development toolchains in the
8107 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008108 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008109 section in the Yocto Project Overview and Concepts Manual. For
8110 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008111 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008112
Andrew Geisslerf0343792020-11-18 10:42:21 -06008113 :term:`TOOLCHAIN_OUTPUTNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008114 This variable defines the name used for the toolchain output. The
8115 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
Andrew Geissler09036742021-06-25 14:25:14 -05008116 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008117
8118 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
8119
8120 See
8121 the :term:`SDK_NAME` and
8122 :term:`SDK_VERSION` variables for additional
8123 information.
8124
Andrew Geisslerf0343792020-11-18 10:42:21 -06008125 :term:`TOOLCHAIN_TARGET_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008126 This variable lists packages the OpenEmbedded build system uses when
8127 it creates the target part of an SDK (i.e. the part built for the
8128 target hardware), which includes libraries and headers. Use this
8129 variable to add individual packages to the part of the SDK that runs
8130 on the target. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008131 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008132 in the Yocto Project Application Development and the Extensible
8133 Software Development Kit (eSDK) manual for more information.
8134
8135 For background information on cross-development toolchains in the
8136 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008137 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008138 section in the Yocto Project Overview and Concepts Manual. For
8139 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008140 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008141
Andrew Geisslerf0343792020-11-18 10:42:21 -06008142 :term:`TOPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008143 The top-level :term:`Build Directory`. BitBake
8144 automatically sets this variable when you initialize your build
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008145 environment using :ref:`structure-core-script`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008146
Andrew Geisslerf0343792020-11-18 10:42:21 -06008147 :term:`TRANSLATED_TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008148 A sanitized version of :term:`TARGET_ARCH`. This
8149 variable is used where the architecture is needed in a value where
8150 underscores are not allowed, for example within package filenames. In
8151 this case, dash characters replace any underscore characters used in
Andrew Geissler09036742021-06-25 14:25:14 -05008152 :term:`TARGET_ARCH`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008153
8154 Do not edit this variable.
8155
Andrew Geisslerf0343792020-11-18 10:42:21 -06008156 :term:`TUNE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008157 The GNU canonical architecture for a specific architecture (i.e.
8158 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
8159 this value to setup configuration.
8160
Andrew Geissler09036742021-06-25 14:25:14 -05008161 :term:`TUNE_ARCH` definitions are specific to a given architecture. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008162 definitions can be a single static definition, or can be dynamically
8163 adjusted. You can see details for a given CPU family by looking at
8164 the architecture's ``README`` file. For example, the
8165 ``meta/conf/machine/include/mips/README`` file in the
8166 :term:`Source Directory` provides information for
Andrew Geissler09036742021-06-25 14:25:14 -05008167 :term:`TUNE_ARCH` specific to the ``mips`` architecture.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008168
Andrew Geissler09036742021-06-25 14:25:14 -05008169 :term:`TUNE_ARCH` is tied closely to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008170 :term:`TARGET_ARCH`, which defines the target
8171 machine's architecture. The BitBake configuration file
Andrew Geissler09036742021-06-25 14:25:14 -05008172 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008173
8174 TARGET_ARCH = "${TUNE_ARCH}"
8175
8176 The following list, which is by no means complete since architectures
8177 are configurable, shows supported machine architectures:
8178
8179 - arm
8180 - i586
8181 - x86_64
8182 - powerpc
8183 - powerpc64
8184 - mips
8185 - mipsel
8186
Andrew Geisslerf0343792020-11-18 10:42:21 -06008187 :term:`TUNE_ASARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008188 Specifies architecture-specific assembler flags for the target
8189 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008190 :term:`TUNE_ASARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008191 typically under ``meta/conf/machine/include/`` and are influenced
8192 through :term:`TUNE_FEATURES`. For example, the
8193 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05008194 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008195
8196 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
8197
8198 .. note::
8199
8200 Board Support Packages (BSPs) select the tune. The selected tune,
8201 in turn, affects the tune variables themselves (i.e. the tune can
8202 supply its own set of flags).
8203
Andrew Geisslerf0343792020-11-18 10:42:21 -06008204 :term:`TUNE_CCARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008205 Specifies architecture-specific C compiler flags for the target
8206 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008207 :term:`TUNE_CCARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008208 typically under ``meta/conf/machine/include/`` and are influenced
8209 through :term:`TUNE_FEATURES`.
8210
8211 .. note::
8212
8213 Board Support Packages (BSPs) select the tune. The selected tune,
8214 in turn, affects the tune variables themselves (i.e. the tune can
8215 supply its own set of flags).
8216
Andrew Geisslerf0343792020-11-18 10:42:21 -06008217 :term:`TUNE_FEATURES`
8218 Features used to "tune" a compiler for optimal use given a specific
8219 processor. The features are defined within the tune files and allow
8220 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
8221 the features.
8222
8223 The OpenEmbedded build system verifies the features to be sure they
8224 are not conflicting and that they are supported.
8225
8226 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
Andrew Geissler09036742021-06-25 14:25:14 -05008227 :term:`TUNE_FEATURES` as follows::
Andrew Geisslerf0343792020-11-18 10:42:21 -06008228
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008229 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008230
8231 See the :term:`DEFAULTTUNE` variable for more information.
8232
8233 :term:`TUNE_LDARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008234 Specifies architecture-specific linker flags for the target system.
8235 The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008236 :term:`TUNE_LDARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008237 typically under ``meta/conf/machine/include/`` and are influenced
8238 through :term:`TUNE_FEATURES`. For example, the
8239 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05008240 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008241
8242 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
8243
8244 .. note::
8245
8246 Board Support Packages (BSPs) select the tune. The selected tune,
8247 in turn, affects the tune variables themselves (i.e. the tune can
8248 supply its own set of flags).
8249
Andrew Geisslerf0343792020-11-18 10:42:21 -06008250 :term:`TUNE_PKGARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008251 The package architecture understood by the packaging system to define
8252 the architecture, ABI, and tuning of output packages. The specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05008253 tune is defined using the "_tune" override as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008254
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008255 TUNE_PKGARCH:tune-tune = "tune"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008256
8257 These tune-specific package architectures are defined in the machine
8258 include files. Here is an example of the "core2-32" tuning as used in
Andrew Geisslerd159c7f2021-09-02 21:05:58 -05008259 the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008260
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008261 TUNE_PKGARCH:tune-core2-32 = "core2-32"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008262
Andrew Geisslerf0343792020-11-18 10:42:21 -06008263 :term:`TUNEABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008264 An underlying Application Binary Interface (ABI) used by a particular
8265 tuning in a given toolchain layer. Providers that use prebuilt
Andrew Geissler09036742021-06-25 14:25:14 -05008266 libraries can use the :term:`TUNEABI`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008267 :term:`TUNEABI_OVERRIDE`, and
8268 :term:`TUNEABI_WHITELIST` variables to check
8269 compatibility of tunings against their selection of libraries.
8270
Andrew Geissler09036742021-06-25 14:25:14 -05008271 If :term:`TUNEABI` is undefined, then every tuning is allowed. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008272 :ref:`sanity <ref-classes-sanity>` class to see how the variable is
8273 used.
8274
Andrew Geisslerf0343792020-11-18 10:42:21 -06008275 :term:`TUNEABI_OVERRIDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008276 If set, the OpenEmbedded system ignores the
8277 :term:`TUNEABI_WHITELIST` variable.
8278 Providers that use prebuilt libraries can use the
Andrew Geissler09036742021-06-25 14:25:14 -05008279 :term:`TUNEABI_OVERRIDE`, :term:`TUNEABI_WHITELIST`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008280 :term:`TUNEABI` variables to check compatibility of a
8281 tuning against their selection of libraries.
8282
8283 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8284 variable is used.
8285
Andrew Geisslerf0343792020-11-18 10:42:21 -06008286 :term:`TUNEABI_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008287 A whitelist of permissible :term:`TUNEABI` values. If
Andrew Geissler09036742021-06-25 14:25:14 -05008288 :term:`TUNEABI_WHITELIST` is not set, all tunes are allowed. Providers
8289 that use prebuilt libraries can use the :term:`TUNEABI_WHITELIST`,
8290 :term:`TUNEABI_OVERRIDE`, and :term:`TUNEABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008291 variables to check compatibility of a tuning against their selection
8292 of libraries.
8293
8294 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8295 variable is used.
8296
Andrew Geisslerf0343792020-11-18 10:42:21 -06008297 :term:`TUNECONFLICTS[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008298 Specifies CPU or Application Binary Interface (ABI) tuning features
8299 that conflict with feature.
8300
8301 Known tuning conflicts are specified in the machine include files in
8302 the :term:`Source Directory`. Here is an example from
8303 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
8304 that lists the "o32" and "n64" features as conflicting with the "n32"
Andrew Geisslerc926e172021-05-07 16:11:35 -05008305 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008306
8307 TUNECONFLICTS[n32] = "o32 n64"
8308
Andrew Geisslerf0343792020-11-18 10:42:21 -06008309 :term:`TUNEVALID[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008310 Specifies a valid CPU or Application Binary Interface (ABI) tuning
8311 feature. The specified feature is stored as a flag. Valid features
8312 are specified in the machine include files (e.g.
8313 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
Andrew Geisslerc926e172021-05-07 16:11:35 -05008314 from that file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008315
8316 TUNEVALID[bigendian] = "Enable big-endian mode."
8317
8318 See the machine include files in the :term:`Source Directory`
8319 for these features.
8320
Andrew Geisslerf0343792020-11-18 10:42:21 -06008321 :term:`UBOOT_CONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008322 Configures the :term:`UBOOT_MACHINE` and can
8323 also define :term:`IMAGE_FSTYPES` for individual
8324 cases.
8325
8326 Following is an example from the ``meta-fsl-arm`` layer. ::
8327
8328 UBOOT_CONFIG ??= "sd"
8329 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
8330 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
8331 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
8332 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
8333
8334 In this example, "sd" is selected as the configuration of the possible four for the
Andrew Geissler09036742021-06-25 14:25:14 -05008335 :term:`UBOOT_MACHINE`. The "sd" configuration defines
8336 "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the
Andrew Geissler5f350902021-07-23 13:09:54 -04008337 "sdcard" specifies the :term:`IMAGE_FSTYPES` to use for the U-Boot image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008338
Andrew Geissler09036742021-06-25 14:25:14 -05008339 For more information on how the :term:`UBOOT_CONFIG` is handled, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008340 :ref:`uboot-config <ref-classes-uboot-config>`
8341 class.
8342
Andrew Geisslerf0343792020-11-18 10:42:21 -06008343 :term:`UBOOT_DTB_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008344 Specifies the load address for the dtb image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05008345 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008346 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify
8347 the load address to be used in
8348 creating the dtb sections of Image Tree Source for the FIT image.
8349
Andrew Geisslerf0343792020-11-18 10:42:21 -06008350 :term:`UBOOT_DTBO_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008351 Specifies the load address for the dtbo image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05008352 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008353 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in
8354 creating the dtbo sections of Image Tree Source for the FIT image.
8355
Andrew Geisslerf0343792020-11-18 10:42:21 -06008356 :term:`UBOOT_ENTRYPOINT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008357 Specifies the entry point for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05008358 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008359 command-line parameter to the ``uboot-mkimage`` utility.
8360
Andrew Geisslerf0343792020-11-18 10:42:21 -06008361 :term:`UBOOT_LOADADDRESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008362 Specifies the load address for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05008363 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008364 command-line parameter to the ``uboot-mkimage`` utility.
8365
Andrew Geisslerf0343792020-11-18 10:42:21 -06008366 :term:`UBOOT_LOCALVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008367 Appends a string to the name of the local version of the U-Boot
8368 image. For example, assuming the version of the U-Boot image built
8369 was "2013.10", the full version string reported by U-Boot would be
Andrew Geisslerc926e172021-05-07 16:11:35 -05008370 "2013.10-yocto" given the following statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008371
8372 UBOOT_LOCALVERSION = "-yocto"
8373
Andrew Geisslerf0343792020-11-18 10:42:21 -06008374 :term:`UBOOT_MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008375 Specifies the value passed on the ``make`` command line when building
8376 a U-Boot image. The value indicates the target platform
8377 configuration. You typically set this variable from the machine
8378 configuration file (i.e. ``conf/machine/machine_name.conf``).
8379
8380 Please see the "Selection of Processor Architecture and Board Type"
8381 section in the U-Boot README for valid values for this variable.
8382
Andrew Geisslerf0343792020-11-18 10:42:21 -06008383 :term:`UBOOT_MAKE_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008384 Specifies the target called in the ``Makefile``. The default target
8385 is "all".
8386
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008387 :term:`UBOOT_MKIMAGE`
8388 Specifies the name of the mkimage command as used by the
8389 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble
8390 the FIT image. This can be used to substitute an alternative command, wrapper
8391 script or function if desired. The default is "uboot-mkimage".
8392
Andrew Geisslerf0343792020-11-18 10:42:21 -06008393 :term:`UBOOT_MKIMAGE_DTCOPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008394 Options for the device tree compiler passed to mkimage '-D'
8395 feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class.
Andrew Geissler5f350902021-07-23 13:09:54 -04008396 If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then kernel-fitimage will not
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008397 pass the ``-D`` option to mkimage.
8398
8399 :term:`UBOOT_MKIMAGE_SIGN`
8400 Specifies the name of the mkimage command as used by the
8401 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign
8402 the FIT image after it has been assembled (if enabled). This can be used
8403 to substitute an alternative command, wrapper script or function if
8404 desired. The default is "${:term:`UBOOT_MKIMAGE`}".
8405
8406 :term:`UBOOT_MKIMAGE_SIGN_ARGS`
8407 Optionally specifies additional arguments for the
8408 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the
8409 mkimage command when signing the FIT image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008410
Andrew Geisslerf0343792020-11-18 10:42:21 -06008411 :term:`UBOOT_RD_ENTRYPOINT`
Andrew Geissler4873add2020-11-02 18:44:49 -06008412 Specifies the entrypoint for the RAM disk image.
8413 During FIT image creation, the
Andrew Geissler09036742021-06-25 14:25:14 -05008414 :term:`UBOOT_RD_ENTRYPOINT` variable is used
Andrew Geissler4873add2020-11-02 18:44:49 -06008415 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
8416 entrypoint to be used in creating the Image Tree Source for
8417 the FIT image.
8418
Andrew Geisslerf0343792020-11-18 10:42:21 -06008419 :term:`UBOOT_RD_LOADADDRESS`
8420 Specifies the load address for the RAM disk image.
8421 During FIT image creation, the
Andrew Geissler09036742021-06-25 14:25:14 -05008422 :term:`UBOOT_RD_LOADADDRESS` variable is used
Andrew Geisslerf0343792020-11-18 10:42:21 -06008423 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
8424 load address to be used in creating the Image Tree Source for
8425 the FIT image.
8426
8427 :term:`UBOOT_SIGN_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008428 Enable signing of FIT image. The default value is "0".
8429
Andrew Geisslerf0343792020-11-18 10:42:21 -06008430 :term:`UBOOT_SIGN_KEYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008431 Location of the directory containing the RSA key and
8432 certificate used for signing FIT image.
8433
Andrew Geisslerf0343792020-11-18 10:42:21 -06008434 :term:`UBOOT_SIGN_KEYNAME`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008435 The name of keys used for signing U-Boot FIT image stored in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008436 :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt
8437 certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have
8438 :term:`UBOOT_SIGN_KEYNAME` set to "dev".
8439
Andrew Geisslerf0343792020-11-18 10:42:21 -06008440 :term:`UBOOT_SUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008441 Points to the generated U-Boot extension. For example, ``u-boot.sb``
8442 has a ``.sb`` extension.
8443
8444 The default U-Boot extension is ``.bin``
8445
Andrew Geisslerf0343792020-11-18 10:42:21 -06008446 :term:`UBOOT_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008447 Specifies the target used for building U-Boot. The target is passed
8448 directly as part of the "make" command (e.g. SPL and AIS). If you do
8449 not specifically set this variable, the OpenEmbedded build process
8450 passes and uses "all" for the target during the U-Boot building
8451 process.
8452
Andrew Geisslerf0343792020-11-18 10:42:21 -06008453 :term:`UNKNOWN_CONFIGURE_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008454 Specifies a list of options that, if reported by the configure script
8455 as being invalid, should not generate a warning during the
8456 :ref:`ref-tasks-configure` task. Normally, invalid
8457 configure options are simply not passed to the configure script (e.g.
8458 should be removed from :term:`EXTRA_OECONF` or
8459 :term:`PACKAGECONFIG_CONFARGS`).
William A. Kennington IIIac69b482021-06-02 12:28:27 -07008460 However, there are common options that are passed to all
8461 configure scripts at a class level, but might not be valid for some
8462 configure scripts. Therefore warnings about these options are useless.
Andrew Geissler09036742021-06-25 14:25:14 -05008463 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_WHITELIST`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008464
8465 The configure arguments check that uses
Andrew Geissler09036742021-06-25 14:25:14 -05008466 :term:`UNKNOWN_CONFIGURE_WHITELIST` is part of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008467 :ref:`insane <ref-classes-insane>` class and is only enabled if the
8468 recipe inherits the :ref:`autotools <ref-classes-autotools>` class.
8469
Andrew Geisslerf0343792020-11-18 10:42:21 -06008470 :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008471 For recipes inheriting the
Andrew Geissler09036742021-06-25 14:25:14 -05008472 :ref:`update-rc.d <ref-classes-update-rc.d>` class, :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008473 specifies the package that contains the initscript that is enabled.
8474
8475 The default value is "${PN}". Given that almost all recipes that
8476 install initscripts package them in the main package for the recipe,
8477 you rarely need to set this variable in individual recipes.
8478
Andrew Geisslerf0343792020-11-18 10:42:21 -06008479 :term:`UPSTREAM_CHECK_GITTAGREGEX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008480 You can perform a per-recipe check for what the latest upstream
8481 source code version is by calling ``bitbake -c checkpkg`` recipe. If
8482 the recipe source code is provided from Git repositories, the
8483 OpenEmbedded build system determines the latest upstream version by
8484 picking the latest tag from the list of all repository tags.
8485
Andrew Geissler09036742021-06-25 14:25:14 -05008486 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008487 regular expression to filter only the relevant tags should the
8488 default filter not work correctly.
8489 ::
8490
8491 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
8492
Andrew Geisslerf0343792020-11-18 10:42:21 -06008493 :term:`UPSTREAM_CHECK_REGEX`
Andrew Geissler09036742021-06-25 14:25:14 -05008494 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008495 regular expression instead of the default one when the package
8496 checking system is parsing the page found using
8497 :term:`UPSTREAM_CHECK_URI`.
8498 ::
8499
8500 UPSTREAM_CHECK_REGEX = "package_regex"
8501
Andrew Geisslerf0343792020-11-18 10:42:21 -06008502 :term:`UPSTREAM_CHECK_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008503 You can perform a per-recipe check for what the latest upstream
8504 source code version is by calling ``bitbake -c checkpkg`` recipe. If
8505 the source code is provided from tarballs, the latest version is
8506 determined by fetching the directory listing where the tarball is and
8507 attempting to find a later tarball. When this approach does not work,
Andrew Geissler09036742021-06-25 14:25:14 -05008508 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008509 contains the link to the latest tarball.
8510 ::
8511
8512 UPSTREAM_CHECK_URI = "recipe_url"
8513
Andrew Geisslerf0343792020-11-18 10:42:21 -06008514 :term:`USE_DEVFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008515 Determines if ``devtmpfs`` is used for ``/dev`` population. The
Andrew Geissler09036742021-06-25 14:25:14 -05008516 default value used for :term:`USE_DEVFS` is "1" when no value is
8517 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008518 statically populated ``/dev`` directory.
8519
Andrew Geissler09209ee2020-12-13 08:44:15 -06008520 See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008521 the Yocto Project Development Tasks Manual for information on how to
8522 use this variable.
8523
Andrew Geisslerf0343792020-11-18 10:42:21 -06008524 :term:`USE_VT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008525 When using
Andrew Geissler09209ee2020-12-13 08:44:15 -06008526 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008527 determines whether or not to run a
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008528 `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008529 virtual terminals in order to enable logging in through those
8530 terminals.
8531
Andrew Geissler09036742021-06-25 14:25:14 -05008532 The default value used for :term:`USE_VT` is "1" when no default value is
8533 specifically set. Typically, you would set :term:`USE_VT` to "0" in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008534 machine configuration file for machines that do not have a graphical
8535 display attached and therefore do not need virtual terminal
8536 functionality.
8537
Andrew Geisslerf0343792020-11-18 10:42:21 -06008538 :term:`USER_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008539 A list of classes to globally inherit. These classes are used by the
8540 OpenEmbedded build system to enable extra features (e.g.
Andrew Geissler5f350902021-07-23 13:09:54 -04008541 ``buildstats``, ``image-prelink``, and so forth).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008542
Andrew Geisslerc926e172021-05-07 16:11:35 -05008543 The default list is set in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008544
Andrew Geissler5f350902021-07-23 13:09:54 -04008545 USER_CLASSES ?= "buildstats image-prelink"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008546
8547 For more information, see
8548 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`.
8549
Andrew Geisslerf0343792020-11-18 10:42:21 -06008550 :term:`USERADD_ERROR_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008551 If set to ``error``, forces the OpenEmbedded build system to produce
8552 an error if the user identification (``uid``) and group
8553 identification (``gid``) values are not defined in any of the files
8554 listed in :term:`USERADD_UID_TABLES` and
8555 :term:`USERADD_GID_TABLES`. If set to
8556 ``warn``, a warning will be issued instead.
8557
8558 The default behavior for the build system is to dynamically apply
8559 ``uid`` and ``gid`` values. Consequently, the
Andrew Geissler09036742021-06-25 14:25:14 -05008560 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008561 on using statically assigned ``gid`` and ``uid`` values, you should
Andrew Geissler09036742021-06-25 14:25:14 -05008562 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05008563 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008564
8565 USERADD_ERROR_DYNAMIC = "error"
8566
8567 Overriding the
8568 default behavior implies you are going to also take steps to set
8569 static ``uid`` and ``gid`` values through use of the
8570 :term:`USERADDEXTENSION`,
8571 :term:`USERADD_UID_TABLES`, and
8572 :term:`USERADD_GID_TABLES` variables.
8573
8574 .. note::
8575
8576 There is a difference in behavior between setting
Andrew Geissler09036742021-06-25 14:25:14 -05008577 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008578 When it is set to ``warn``, the build system will report a warning for
8579 every undefined ``uid`` and ``gid`` in any recipe. But when it is set
8580 to ``error``, it will only report errors for recipes that are actually
8581 built.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008582 This saves you from having to add static IDs for recipes that you
8583 know will never be built.
8584
Andrew Geisslerf0343792020-11-18 10:42:21 -06008585 :term:`USERADD_GID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008586 Specifies a password file to use for obtaining static group
8587 identification (``gid``) values when the OpenEmbedded build system
8588 adds a group to the system during package installation.
8589
8590 When applying static group identification (``gid``) values, the
8591 OpenEmbedded build system looks in :term:`BBPATH` for a
8592 ``files/group`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008593 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008594
8595
8596 USERADD_GID_TABLES = "files/group"
8597
8598 .. note::
8599
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008600 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
8601 causes the build system to use static ``gid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008602
Andrew Geisslerf0343792020-11-18 10:42:21 -06008603 :term:`USERADD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008604 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
8605 this variable specifies the individual packages within the recipe
8606 that require users and/or groups to be added.
8607
8608 You must set this variable if the recipe inherits the class. For
8609 example, the following enables adding a user for the main package in
Andrew Geisslerc926e172021-05-07 16:11:35 -05008610 a recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008611
8612 USERADD_PACKAGES = "${PN}"
8613
8614 .. note::
8615
Andrew Geissler09036742021-06-25 14:25:14 -05008616 It follows that if you are going to use the :term:`USERADD_PACKAGES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008617 variable, you need to set one or more of the :term:`USERADD_PARAM`,
8618 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008619
Andrew Geisslerf0343792020-11-18 10:42:21 -06008620 :term:`USERADD_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008621 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
8622 this variable specifies for a package what parameters should pass to
8623 the ``useradd`` command if you add a user to the system when the
8624 package is installed.
8625
Andrew Geisslerc926e172021-05-07 16:11:35 -05008626 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008627
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008628 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008629 --no-create-home --shell /bin/false \
8630 --user-group messagebus"
8631
8632 For information on the
8633 standard Linux shell command ``useradd``, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008634 https://linux.die.net/man/8/useradd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008635
Andrew Geisslerf0343792020-11-18 10:42:21 -06008636 :term:`USERADD_UID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008637 Specifies a password file to use for obtaining static user
8638 identification (``uid``) values when the OpenEmbedded build system
8639 adds a user to the system during package installation.
8640
8641 When applying static user identification (``uid``) values, the
8642 OpenEmbedded build system looks in :term:`BBPATH` for a
8643 ``files/passwd`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008644 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008645
8646 USERADD_UID_TABLES = "files/passwd"
8647
8648 .. note::
8649
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008650 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
8651 causes the build system to use static ``uid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008652
Andrew Geisslerf0343792020-11-18 10:42:21 -06008653 :term:`USERADDEXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008654 When set to "useradd-staticids", causes the OpenEmbedded build system
8655 to base all user and group additions on a static ``passwd`` and
8656 ``group`` files found in :term:`BBPATH`.
8657
8658 To use static user identification (``uid``) and group identification
8659 (``gid``) values, set the variable as follows in your ``local.conf``
8660 file: USERADDEXTENSION = "useradd-staticids"
8661
8662 .. note::
8663
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008664 Setting this variable to use static ``uid`` and ``gid``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008665 values causes the OpenEmbedded build system to employ the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008666 :ref:`ref-classes-useradd` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008667
8668 If you use static ``uid`` and ``gid`` information, you must also
8669 specify the ``files/passwd`` and ``files/group`` files by setting the
8670 :term:`USERADD_UID_TABLES` and
8671 :term:`USERADD_GID_TABLES` variables.
8672 Additionally, you should also set the
8673 :term:`USERADD_ERROR_DYNAMIC` variable.
8674
Andrew Geisslerf0343792020-11-18 10:42:21 -06008675 :term:`VOLATILE_LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008676 Specifies the persistence of the target's ``/var/log`` directory,
8677 which is used to house postinstall target log files.
8678
Andrew Geissler09036742021-06-25 14:25:14 -05008679 By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008680 file is not persistent. You can override this setting by setting the
8681 variable to "no" to make the log directory persistent.
8682
Andrew Geisslerf0343792020-11-18 10:42:21 -06008683 :term:`WARN_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008684 Specifies the quality assurance checks whose failures are reported as
8685 warnings by the OpenEmbedded build system. You set this variable in
8686 your distribution configuration file. For a list of the checks you
8687 can control with this variable, see the
8688 ":ref:`insane.bbclass <ref-classes-insane>`" section.
8689
Andrew Geisslerf0343792020-11-18 10:42:21 -06008690 :term:`WKS_FILE`
8691 Specifies the location of the Wic kickstart file that is used by the
8692 OpenEmbedded build system to create a partitioned image
8693 (image\ ``.wic``). For information on how to create a partitioned
8694 image, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008695 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008696 section in the Yocto Project Development Tasks Manual. For details on
Andrew Geissler09209ee2020-12-13 08:44:15 -06008697 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter.
Andrew Geisslerf0343792020-11-18 10:42:21 -06008698
8699 :term:`WKS_FILE_DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008700 When placed in the recipe that builds your image, this variable lists
Andrew Geissler09036742021-06-25 14:25:14 -05008701 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008702 applicable when Wic images are active (i.e. when
8703 :term:`IMAGE_FSTYPES` contains entries related
8704 to Wic). If your recipe does not create Wic images, the variable has
8705 no effect.
8706
Andrew Geissler09036742021-06-25 14:25:14 -05008707 The :term:`WKS_FILE_DEPENDS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008708 :term:`DEPENDS` variable. When you use the variable in
8709 your recipe that builds the Wic image, dependencies you list in the
Andrew Geissler09036742021-06-25 14:25:14 -05008710 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008711
Andrew Geissler09036742021-06-25 14:25:14 -05008712 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008713 specify a list of additional dependencies (e.g. native tools,
8714 bootloaders, and so forth), that are required to build Wic images.
Andrew Geisslerc926e172021-05-07 16:11:35 -05008715 Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008716
8717 WKS_FILE_DEPENDS = "some-native-tool"
8718
8719 In the
8720 previous example, some-native-tool would be replaced with an actual
8721 native tool on which the build would depend.
8722
Andrew Geisslerf0343792020-11-18 10:42:21 -06008723 :term:`WORKDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008724 The pathname of the work directory in which the OpenEmbedded build
8725 system builds a recipe. This directory is located within the
8726 :term:`TMPDIR` directory structure and is specific to
8727 the recipe being built and the system for which it is being built.
8728
Andrew Geissler09036742021-06-25 14:25:14 -05008729 The :term:`WORKDIR` directory is defined as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008730
8731 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8732
8733 The actual directory depends on several things:
8734
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008735 - :term:`TMPDIR`: The top-level build output directory
8736 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier
8737 - :term:`PN`: The recipe name
8738 - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which
8739 is usually the case for most recipes, then `EXTENDPE` is blank)
8740 - :term:`PV`: The recipe version
8741 - :term:`PR`: The recipe revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008742
8743 As an example, assume a Source Directory top-level folder name
8744 ``poky``, a default Build Directory at ``poky/build``, and a
8745 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
8746 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
8747 directory the build system uses to build the package would be as
Andrew Geisslerc926e172021-05-07 16:11:35 -05008748 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008749
8750 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8751
Andrew Geisslerf0343792020-11-18 10:42:21 -06008752 :term:`XSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008753 Specifies the packages that should be installed to provide an X
8754 server and drivers for the current machine, assuming your image
8755 directly includes ``packagegroup-core-x11-xserver`` or, perhaps
8756 indirectly, includes "x11-base" in
8757 :term:`IMAGE_FEATURES`.
8758
Andrew Geissler09036742021-06-25 14:25:14 -05008759 The default value of :term:`XSERVER`, if not specified in the machine
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008760 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
8761