blob: b9e97719b9e79953636fe2ad4a2c89b6331f3fed [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.
Andrew Geisslereff27472021-10-29 15:35:00 -0500733 ``build_directory/conf/multiconfig/configA.conf``).
Andrew Geisslerc9f78652020-09-18 14:11:35 -0500734
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 Geisslereff27472021-10-29 15:35:00 -05001585 :term:`DEBUG_PREFIX_MAP`
1586 Allows to set C compiler options, such as ``-fdebug-prefix-map``,
1587 ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to
1588 replace build-time paths by install-time ones in the debugging sections
1589 of binaries. This makes compiler output files location independent,
1590 at the cost of having to pass an extra command to tell the debugger
1591 where source files are.
1592
1593 This is used by the Yocto Project to guarantee
1594 :doc:`/test-manual/reproducible-builds` even when the source code of
1595 a package uses the ``__FILE__`` or ``assert()`` macros. See the
1596 `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__
1597 website for details.
1598
1599 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1600 not intended to be user-configurable.
1601
Andrew Geisslerf0343792020-11-18 10:42:21 -06001602 :term:`DEFAULTTUNE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001603 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1604 the "tune") used by the OpenEmbedded build system. The
Andrew Geissler09036742021-06-25 14:25:14 -05001605 :term:`DEFAULTTUNE` helps define
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001606 :term:`TUNE_FEATURES`.
1607
1608 The default tune is either implicitly or explicitly set by the
1609 machine (:term:`MACHINE`). However, you can override
1610 the setting using available tunes as defined with
1611 :term:`AVAILTUNES`.
1612
Andrew Geisslerf0343792020-11-18 10:42:21 -06001613 :term:`DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001614 Lists a recipe's build-time dependencies. These are dependencies on
1615 other recipes whose contents (e.g. headers and shared libraries) are
1616 needed by the recipe at build time.
1617
1618 As an example, consider a recipe ``foo`` that contains the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05001619 assignment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001620
1621 DEPENDS = "bar"
1622
1623 The practical effect of the previous
1624 assignment is that all files installed by bar will be available in
1625 the appropriate staging sysroot, given by the
1626 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the
1627 :ref:`ref-tasks-configure` task for ``foo`` runs.
1628 This mechanism is implemented by having ``do_configure`` depend on
1629 the :ref:`ref-tasks-populate_sysroot` task of
Andrew Geissler09036742021-06-25 14:25:14 -05001630 each recipe listed in :term:`DEPENDS`, through a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001631 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1632 declaration in the :ref:`base <ref-classes-base>` class.
1633
1634 .. note::
1635
Andrew Geissler09036742021-06-25 14:25:14 -05001636 It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001637 explicitly. The standard classes and build-related variables are
1638 configured to automatically use the appropriate staging sysroots.
1639
Andrew Geissler09036742021-06-25 14:25:14 -05001640 As another example, :term:`DEPENDS` can also be used to add utilities
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001641 that run on the build machine during the build. For example, a recipe
1642 that makes use of a code generator built by the recipe ``codegen``
Andrew Geisslerc926e172021-05-07 16:11:35 -05001643 might have the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001644
1645 DEPENDS = "codegen-native"
1646
1647 For more
1648 information, see the :ref:`native <ref-classes-native>` class and
1649 the :term:`EXTRANATIVEPATH` variable.
1650
1651 .. note::
1652
Andrew Geissler09036742021-06-25 14:25:14 -05001653 - :term:`DEPENDS` is a list of recipe names. Or, to be more precise,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001654 it is a list of :term:`PROVIDES` names, which
1655 usually match recipe names. Putting a package name such as
Andrew Geissler09036742021-06-25 14:25:14 -05001656 "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001657 instead, as this will put files from all the packages that make
1658 up ``foo``, which includes those from ``foo-dev``, into the
1659 sysroot.
1660
Andrew Geissler09036742021-06-25 14:25:14 -05001661 - One recipe having another recipe in :term:`DEPENDS` does not by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001662 itself add any runtime dependencies between the packages
1663 produced by the two recipes. However, as explained in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001664 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001665 section in the Yocto Project Overview and Concepts Manual,
1666 runtime dependencies will often be added automatically, meaning
Andrew Geissler5f350902021-07-23 13:09:54 -04001667 :term:`DEPENDS` alone is sufficient for most recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001668
Andrew Geissler09036742021-06-25 14:25:14 -05001669 - Counterintuitively, :term:`DEPENDS` is often necessary even for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001670 recipes that install precompiled components. For example, if
1671 ``libfoo`` is a precompiled library that links against
1672 ``libbar``, then linking against ``libfoo`` requires both
1673 ``libfoo`` and ``libbar`` to be available in the sysroot.
Andrew Geissler09036742021-06-25 14:25:14 -05001674 Without a :term:`DEPENDS` from the recipe that installs ``libfoo``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001675 to the recipe that installs ``libbar``, other recipes might
1676 fail to link against ``libfoo``.
1677
1678 For information on runtime dependencies, see the
1679 :term:`RDEPENDS` variable. You can also see the
Patrick Williams213cb262021-08-07 19:21:33 -05001680 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
1681 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001682 BitBake User Manual for additional information on tasks and
1683 dependencies.
1684
Andrew Geisslerf0343792020-11-18 10:42:21 -06001685 :term:`DEPLOY_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001686 Points to the general area that the OpenEmbedded build system uses to
1687 place images, packages, SDKs, and other output files that are ready
1688 to be used outside of the build system. By default, this directory
1689 resides within the :term:`Build Directory` as
1690 ``${TMPDIR}/deploy``.
1691
1692 For more information on the structure of the Build Directory, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06001693 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001694 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001695 ":ref:`overview-manual/concepts:images`",
1696 ":ref:`overview-manual/concepts:package feeds`", and
1697 ":ref:`overview-manual/concepts:application development sdk`" sections all in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001698 Yocto Project Overview and Concepts Manual.
1699
Andrew Geisslerf0343792020-11-18 10:42:21 -06001700 :term:`DEPLOY_DIR_DEB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001701 Points to the area that the OpenEmbedded build system uses to place
1702 Debian packages that are ready to be used outside of the build
1703 system. This variable applies only when
1704 :term:`PACKAGE_CLASSES` contains
1705 "package_deb".
1706
1707 The BitBake configuration file initially defines the
Andrew Geissler5f350902021-07-23 13:09:54 -04001708 :term:`DEPLOY_DIR_DEB` variable as a sub-folder of
Andrew Geisslerc926e172021-05-07 16:11:35 -05001709 :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001710
1711 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
1712
1713 The :ref:`package_deb <ref-classes-package_deb>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001714 :term:`DEPLOY_DIR_DEB` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001715 :ref:`ref-tasks-package_write_deb` task
1716 writes Debian packages into the appropriate folder. For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06001717 information on how packaging works, see the
1718 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001719 in the Yocto Project Overview and Concepts Manual.
1720
Andrew Geisslerf0343792020-11-18 10:42:21 -06001721 :term:`DEPLOY_DIR_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001722 Points to the area that the OpenEmbedded build system uses to place
1723 images and other associated output files that are ready to be
1724 deployed onto the target machine. The directory is machine-specific
1725 as it contains the ``${MACHINE}`` name. By default, this directory
1726 resides within the :term:`Build Directory` as
1727 ``${DEPLOY_DIR}/images/${MACHINE}/``.
1728
Andrew Geissler09036742021-06-25 14:25:14 -05001729 It must not be used directly in recipes when deploying files. Instead,
1730 it's only useful when a recipe needs to "read" a file already deployed
1731 by a dependency. So, it should be filled with the contents of
1732 :term:`DEPLOYDIR` by the :ref:`deploy <ref-classes-deploy>` class or
1733 with the contents of :term:`IMGDEPLOYDIR` by the :ref:`image
1734 <ref-classes-image>` class.
1735
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001736 For more information on the structure of the Build Directory, see
Andrew Geissler09209ee2020-12-13 08:44:15 -06001737 ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001738 For more detail on the contents of the ``deploy`` directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06001739 ":ref:`overview-manual/concepts:images`" and
1740 ":ref:`overview-manual/concepts:application development sdk`" sections both in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001741 the Yocto Project Overview and Concepts Manual.
1742
Andrew Geisslerf0343792020-11-18 10:42:21 -06001743 :term:`DEPLOY_DIR_IPK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001744 Points to the area that the OpenEmbedded build system uses to place
1745 IPK packages that are ready to be used outside of the build system.
1746 This variable applies only when
1747 :term:`PACKAGE_CLASSES` contains
1748 "package_ipk".
1749
1750 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001751 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001752
1753 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
1754
1755 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001756 :term:`DEPLOY_DIR_IPK` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001757 :ref:`ref-tasks-package_write_ipk` task
1758 writes IPK packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001759 on how packaging works, see the
1760 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001761 in the Yocto Project Overview and Concepts Manual.
1762
Andrew Geisslerf0343792020-11-18 10:42:21 -06001763 :term:`DEPLOY_DIR_RPM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001764 Points to the area that the OpenEmbedded build system uses to place
1765 RPM packages that are ready to be used outside of the build system.
1766 This variable applies only when
1767 :term:`PACKAGE_CLASSES` contains
1768 "package_rpm".
1769
1770 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001771 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001772
1773 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
1774
1775 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001776 :term:`DEPLOY_DIR_RPM` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001777 :ref:`ref-tasks-package_write_rpm` task
1778 writes RPM packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001779 on how packaging works, see the
1780 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001781 in the Yocto Project Overview and Concepts Manual.
1782
Andrew Geisslerf0343792020-11-18 10:42:21 -06001783 :term:`DEPLOY_DIR_TAR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001784 Points to the area that the OpenEmbedded build system uses to place
1785 tarballs that are ready to be used outside of the build system. This
1786 variable applies only when
1787 :term:`PACKAGE_CLASSES` contains
1788 "package_tar".
1789
1790 The BitBake configuration file initially defines this variable as a
Andrew Geisslerc926e172021-05-07 16:11:35 -05001791 sub-folder of :term:`DEPLOY_DIR`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001792
1793 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
1794
1795 The :ref:`package_tar <ref-classes-package_tar>` class uses the
Andrew Geissler09036742021-06-25 14:25:14 -05001796 :term:`DEPLOY_DIR_TAR` variable to make sure the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001797 :ref:`ref-tasks-package_write_tar` task
1798 writes TAR packages into the appropriate folder. For more information
Andrew Geissler09209ee2020-12-13 08:44:15 -06001799 on how packaging works, see the
1800 ":ref:`overview-manual/concepts:package feeds`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001801 in the Yocto Project Overview and Concepts Manual.
1802
Andrew Geisslerf0343792020-11-18 10:42:21 -06001803 :term:`DEPLOYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001804 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the
Andrew Geissler09036742021-06-25 14:25:14 -05001805 :term:`DEPLOYDIR` points to a temporary work area for deployed files that
Andrew Geisslerc926e172021-05-07 16:11:35 -05001806 is set in the ``deploy`` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001807
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001808 DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001809
1810 Recipes inheriting the ``deploy`` class should copy files to be
Andrew Geissler09036742021-06-25 14:25:14 -05001811 deployed into :term:`DEPLOYDIR`, and the class will take care of copying
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001812 them into :term:`DEPLOY_DIR_IMAGE`
1813 afterwards.
1814
Andrew Geisslerf0343792020-11-18 10:42:21 -06001815 :term:`DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001816 The package description used by package managers. If not set,
Andrew Geissler09036742021-06-25 14:25:14 -05001817 :term:`DESCRIPTION` takes the value of the :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001818 variable.
1819
Andrew Geisslerf0343792020-11-18 10:42:21 -06001820 :term:`DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001821 The short name of the distribution. For information on the long name
1822 of the distribution, see the :term:`DISTRO_NAME`
1823 variable.
1824
Andrew Geissler09036742021-06-25 14:25:14 -05001825 The :term:`DISTRO` variable corresponds to a distribution configuration
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001826 file whose root name is the same as the variable's argument and whose
1827 filename extension is ``.conf``. For example, the distribution
1828 configuration file for the Poky distribution is named ``poky.conf``
1829 and resides in the ``meta-poky/conf/distro`` directory of the
1830 :term:`Source Directory`.
1831
Andrew Geissler09036742021-06-25 14:25:14 -05001832 Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05001833 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001834
1835 DISTRO = "poky"
1836
1837 Distribution configuration files are located in a ``conf/distro``
1838 directory within the :term:`Metadata` that contains the
Andrew Geissler09036742021-06-25 14:25:14 -05001839 distribution configuration. The value for :term:`DISTRO` must not contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001840 spaces, and is typically all lower-case.
1841
1842 .. note::
1843
Andrew Geissler09036742021-06-25 14:25:14 -05001844 If the :term:`DISTRO` variable is blank, a set of default configurations
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001845 are used, which are specified within
1846 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001847
Andrew Geisslerf0343792020-11-18 10:42:21 -06001848 :term:`DISTRO_CODENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001849 Specifies a codename for the distribution being built.
1850
Andrew Geisslerf0343792020-11-18 10:42:21 -06001851 :term:`DISTRO_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001852 Specifies a list of distro-specific packages to add to all images.
1853 This variable takes affect through ``packagegroup-base`` so the
1854 variable only really applies to the more full-featured images that
1855 include ``packagegroup-base``. You can use this variable to keep
1856 distro policy out of generic images. As with all other distro
1857 variables, you set this variable in the distro ``.conf`` file.
1858
Andrew Geisslerf0343792020-11-18 10:42:21 -06001859 :term:`DISTRO_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001860 Specifies a list of distro-specific packages to add to all images if
1861 the packages exist. The packages might not exist or be empty (e.g.
1862 kernel modules). The list of packages are automatically installed but
1863 you can remove them.
1864
Andrew Geisslerf0343792020-11-18 10:42:21 -06001865 :term:`DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001866 The software support you want in your distribution for various
1867 features. You define your distribution features in the distribution
1868 configuration file.
1869
1870 In most cases, the presence or absence of a feature in
Andrew Geissler09036742021-06-25 14:25:14 -05001871 :term:`DISTRO_FEATURES` is translated to the appropriate option supplied
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001872 to the configure script during the
1873 :ref:`ref-tasks-configure` task for recipes that
1874 optionally support the feature. For example, specifying "x11" in
Andrew Geissler09036742021-06-25 14:25:14 -05001875 :term:`DISTRO_FEATURES`, causes every piece of software built for the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001876 target that can optionally support X11 to have its X11 support
1877 enabled.
1878
1879 Two more examples are Bluetooth and NFS support. For a more complete
1880 list of features that ships with the Yocto Project and that you can
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001881 provide with this variable, see the ":ref:`ref-features-distro`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001882
Andrew Geisslerf0343792020-11-18 10:42:21 -06001883 :term:`DISTRO_FEATURES_BACKFILL`
Andrew Geissler09036742021-06-25 14:25:14 -05001884 Features to be added to :term:`DISTRO_FEATURES` if not also present in
1885 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001886
1887 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1888 not intended to be user-configurable. It is best to just reference
1889 the variable to see which distro features are being backfilled for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001890 all distro configurations. See the ":ref:`ref-features-backfill`" section
1891 for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001892
Andrew Geisslerf0343792020-11-18 10:42:21 -06001893 :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`
Andrew Geissler09036742021-06-25 14:25:14 -05001894 Features from :term:`DISTRO_FEATURES_BACKFILL` that should not be
1895 backfilled (i.e. added to :term:`DISTRO_FEATURES`) during the build. See
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001896 the ":ref:`ref-features-backfill`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001897
Andrew Geisslerf0343792020-11-18 10:42:21 -06001898 :term:`DISTRO_FEATURES_DEFAULT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001899 A convenience variable that gives you the default list of distro
1900 features with the exception of any features specific to the C library
1901 (``libc``).
1902
1903 When creating a custom distribution, you might find it useful to be
1904 able to reuse the default
1905 :term:`DISTRO_FEATURES` options without the
1906 need to write out the full set. Here is an example that uses
Andrew Geissler09036742021-06-25 14:25:14 -05001907 :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001908
1909 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
1910
Andrew Geisslerf0343792020-11-18 10:42:21 -06001911 :term:`DISTRO_FEATURES_FILTER_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001912 Specifies a list of features that if present in the target
1913 :term:`DISTRO_FEATURES` value should be
Andrew Geissler09036742021-06-25 14:25:14 -05001914 included in :term:`DISTRO_FEATURES` when building native recipes. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001915 variable is used in addition to the features filtered using the
1916 :term:`DISTRO_FEATURES_NATIVE`
1917 variable.
1918
Andrew Geisslerf0343792020-11-18 10:42:21 -06001919 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001920 Specifies a list of features that if present in the target
1921 :term:`DISTRO_FEATURES` value should be
Andrew Geissler09036742021-06-25 14:25:14 -05001922 included in :term:`DISTRO_FEATURES` when building nativesdk recipes. This
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001923 variable is used in addition to the features filtered using the
1924 :term:`DISTRO_FEATURES_NATIVESDK`
1925 variable.
1926
Andrew Geisslerf0343792020-11-18 10:42:21 -06001927 :term:`DISTRO_FEATURES_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001928 Specifies a list of features that should be included in
1929 :term:`DISTRO_FEATURES` when building native
1930 recipes. This variable is used in addition to the features filtered
1931 using the
1932 :term:`DISTRO_FEATURES_FILTER_NATIVE`
1933 variable.
1934
Andrew Geisslerf0343792020-11-18 10:42:21 -06001935 :term:`DISTRO_FEATURES_NATIVESDK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001936 Specifies a list of features that should be included in
1937 :term:`DISTRO_FEATURES` when building
1938 nativesdk recipes. This variable is used in addition to the features
1939 filtered using the
1940 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
1941 variable.
1942
Andrew Geisslerf0343792020-11-18 10:42:21 -06001943 :term:`DISTRO_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001944 The long name of the distribution. For information on the short name
1945 of the distribution, see the :term:`DISTRO` variable.
1946
Andrew Geissler09036742021-06-25 14:25:14 -05001947 The :term:`DISTRO_NAME` variable corresponds to a distribution
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001948 configuration file whose root name is the same as the variable's
1949 argument and whose filename extension is ``.conf``. For example, the
1950 distribution configuration file for the Poky distribution is named
1951 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
1952 of the :term:`Source Directory`.
1953
Andrew Geissler09036742021-06-25 14:25:14 -05001954 Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set
Andrew Geisslerc926e172021-05-07 16:11:35 -05001955 as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001956
1957 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
1958
1959 Distribution configuration files are located in a ``conf/distro``
1960 directory within the :term:`Metadata` that contains the
1961 distribution configuration.
1962
1963 .. note::
1964
Andrew Geissler09036742021-06-25 14:25:14 -05001965 If the :term:`DISTRO_NAME` variable is blank, a set of default
Andrew Geissler4c19ea12020-10-27 13:52:24 -05001966 configurations are used, which are specified within
1967 ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001968
Andrew Geisslerf0343792020-11-18 10:42:21 -06001969 :term:`DISTRO_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001970 The version of the distribution.
1971
Andrew Geisslerf0343792020-11-18 10:42:21 -06001972 :term:`DISTROOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001973 A colon-separated list of overrides specific to the current
1974 distribution. By default, this list includes the value of
1975 :term:`DISTRO`.
1976
Andrew Geissler09036742021-06-25 14:25:14 -05001977 You can extend :term:`DISTROOVERRIDES` to add extra overrides that should
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001978 apply to the distribution.
1979
Andrew Geissler09036742021-06-25 14:25:14 -05001980 The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001981 is included in the default value of
1982 :term:`OVERRIDES`.
1983
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05001984 :term:`DISTUTILS_SETUP_PATH`
1985 When used by recipes that inherit the
1986 :ref:`distutils3 <ref-classes-distutils3>` or
1987 :ref:`setuptools3 <ref-classes-setuptools3>` class, this variable should
1988 be used to specify the directory in which the ``setup.py`` file is
1989 located if it is not at the root of the source tree (as specified by
1990 :term:`S`). For example, in a recipe where the sources are fetched from
1991 a Git repository and ``setup.py`` is in a ``python/pythonmodule``
1992 subdirectory, you would have this::
1993
1994 S = "${WORKDIR}/git"
1995 DISTUTILS_SETUP_PATH = "${S}/python/pythonmodule"
1996
Andrew Geisslerf0343792020-11-18 10:42:21 -06001997 :term:`DL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05001998 The central download directory used by the build process to store
Andrew Geissler09036742021-06-25 14:25:14 -05001999 downloads. By default, :term:`DL_DIR` gets files suitable for mirroring
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002000 for everything except Git repositories. If you want tarballs of Git
2001 repositories, use the
2002 :term:`BB_GENERATE_MIRROR_TARBALLS`
2003 variable.
2004
Andrew Geissler09036742021-06-25 14:25:14 -05002005 You can set this directory by defining the :term:`DL_DIR` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002006 ``conf/local.conf`` file. This directory is self-maintaining and you
2007 should not have to touch it. By default, the directory is
2008 ``downloads`` in the :term:`Build Directory`.
2009 ::
2010
2011 #DL_DIR ?= "${TOPDIR}/downloads"
2012
2013 To specify a different download directory,
2014 simply remove the comment from the line and provide your directory.
2015
2016 During a first build, the system downloads many different source code
2017 tarballs from various upstream projects. Downloading can take a
2018 while, particularly if your network connection is slow. Tarballs are
Andrew Geissler09036742021-06-25 14:25:14 -05002019 all stored in the directory defined by :term:`DL_DIR` and the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002020 system looks there first to find source tarballs.
2021
2022 .. note::
2023
2024 When wiping and rebuilding, you can preserve this directory to
2025 speed up this part of subsequent builds.
2026
2027 You can safely share this directory between multiple builds on the
2028 same development machine. For additional information on how the build
2029 process gets source files when working behind a firewall or proxy
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002030 server, see this specific question in the ":doc:`faq`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002031 chapter. You can also refer to the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002032 ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002033 Wiki page.
2034
Andrew Geisslerf0343792020-11-18 10:42:21 -06002035 :term:`DOC_COMPRESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002036 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>`
2037 class, this variable sets the compression policy used when the
2038 OpenEmbedded build system compresses man pages and info pages. By
2039 default, the compression method used is gz (gzip). Other policies
2040 available are xz and bz2.
2041
2042 For information on policies and on how to use this variable, see the
2043 comments in the ``meta/classes/compress_doc.bbclass`` file.
2044
Andrew Geisslerf0343792020-11-18 10:42:21 -06002045 :term:`EFI_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002046 When building bootable images (i.e. where ``hddimg``, ``iso``, or
2047 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
Andrew Geissler09036742021-06-25 14:25:14 -05002048 :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002049 default is "grub-efi", but "systemd-boot" can be used instead.
2050
2051 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and
2052 :ref:`image-live <ref-classes-image-live>` classes for more
2053 information.
2054
Andrew Geisslerf0343792020-11-18 10:42:21 -06002055 :term:`ENABLE_BINARY_LOCALE_GENERATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002056 Variable that controls which locales for ``glibc`` are generated
2057 during the build (useful if the target device has 64Mbytes of RAM or
2058 less).
2059
Andrew Geisslerf0343792020-11-18 10:42:21 -06002060 :term:`ERR_REPORT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002061 When used with the :ref:`report-error <ref-classes-report-error>`
2062 class, specifies the path used for storing the debug files created by
2063 the :ref:`error reporting
Andrew Geissler09209ee2020-12-13 08:44:15 -06002064 tool <dev-manual/common-tasks:using the error reporting tool>`, which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002065 allows you to submit build errors you encounter to a central
2066 database. By default, the value of this variable is
2067 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2068
Andrew Geissler09036742021-06-25 14:25:14 -05002069 You can set :term:`ERR_REPORT_DIR` to the path you want the error
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002070 reporting tool to store the debug files as follows in your
Andrew Geisslerc926e172021-05-07 16:11:35 -05002071 ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002072
2073 ERR_REPORT_DIR = "path"
2074
Andrew Geisslerf0343792020-11-18 10:42:21 -06002075 :term:`ERROR_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002076 Specifies the quality assurance checks whose failures are reported as
2077 errors by the OpenEmbedded build system. You set this variable in
2078 your distribution configuration file. For a list of the checks you
2079 can control with this variable, see the
2080 ":ref:`insane.bbclass <ref-classes-insane>`" section.
2081
Andrew Geisslerf0343792020-11-18 10:42:21 -06002082 :term:`EXCLUDE_FROM_SHLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002083 Triggers the OpenEmbedded build system's shared libraries resolver to
2084 exclude an entire package when scanning for shared libraries.
2085
2086 .. note::
2087
2088 The shared libraries resolver's functionality results in part from
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002089 the internal function ``package_do_shlibs``, which is part of the
2090 :ref:`ref-tasks-package` task. You should be aware that the shared
2091 libraries resolver might implicitly define some dependencies between
2092 packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002093
Andrew Geissler09036742021-06-25 14:25:14 -05002094 The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002095 :term:`PRIVATE_LIBS` variable, which excludes a
2096 package's particular libraries only and not the whole package.
2097
Andrew Geissler09036742021-06-25 14:25:14 -05002098 Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a
Andrew Geisslerc926e172021-05-07 16:11:35 -05002099 particular package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002100
2101 EXCLUDE_FROM_SHLIBS = "1"
2102
Andrew Geisslerf0343792020-11-18 10:42:21 -06002103 :term:`EXCLUDE_FROM_WORLD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002104 Directs BitBake to exclude a recipe from world builds (i.e.
2105 ``bitbake world``). During world builds, BitBake locates, parses and
2106 builds all recipes found in every layer exposed in the
2107 ``bblayers.conf`` configuration file.
2108
2109 To exclude a recipe from a world build using this variable, set the
2110 variable to "1" in the recipe.
2111
2112 .. note::
2113
Andrew Geissler09036742021-06-25 14:25:14 -05002114 Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002115 world build in order to satisfy dependencies of other recipes. Adding
Andrew Geissler09036742021-06-25 14:25:14 -05002116 a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002117 explicitly added to the list of build targets in a world build.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002118
Andrew Geisslerf0343792020-11-18 10:42:21 -06002119 :term:`EXTENDPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002120 Used with file and pathnames to create a prefix for a recipe's
Andrew Geissler09036742021-06-25 14:25:14 -05002121 version based on the recipe's :term:`PE` value. If :term:`PE`
2122 is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that
2123 value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1").
2124 If a recipe's :term:`PE` is not set (the default) or is equal to zero,
2125 :term:`EXTENDPE` becomes "".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002126
2127 See the :term:`STAMP` variable for an example.
2128
Andrew Geisslerf0343792020-11-18 10:42:21 -06002129 :term:`EXTENDPKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002130 The full package version specification as it appears on the final
2131 packages produced by a recipe. The variable's value is normally used
2132 to fix a runtime dependency to the exact same version of another
Andrew Geisslerc926e172021-05-07 16:11:35 -05002133 package in the same recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002134
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002135 RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002136
2137 The dependency relationships are intended to force the package
2138 manager to upgrade these types of packages in lock-step.
2139
Andrew Geisslerf0343792020-11-18 10:42:21 -06002140 :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geissler09036742021-06-25 14:25:14 -05002141 When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002142 tools are not in the source tree.
2143
2144 When kernel tools are available in the tree, they are preferred over
Andrew Geissler09036742021-06-25 14:25:14 -05002145 any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002146 variable tells the OpenEmbedded build system to prefer the installed
2147 external tools. See the
2148 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in
2149 ``meta/classes`` to see how the variable is used.
2150
Andrew Geisslerf0343792020-11-18 10:42:21 -06002151 :term:`EXTERNALSRC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002152 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
2153 class, this variable points to the source tree, which is outside of
2154 the OpenEmbedded build system. When set, this variable sets the
2155 :term:`S` variable, which is what the OpenEmbedded build
2156 system uses to locate unpacked recipe source code.
2157
2158 For more information on ``externalsrc.bbclass``, see the
2159 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2160 can also find information on how to use this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002161 ":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002162 section in the Yocto Project Development Tasks Manual.
2163
Andrew Geisslerf0343792020-11-18 10:42:21 -06002164 :term:`EXTERNALSRC_BUILD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002165 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
2166 class, this variable points to the directory in which the recipe's
2167 source code is built, which is outside of the OpenEmbedded build
2168 system. When set, this variable sets the :term:`B` variable,
2169 which is what the OpenEmbedded build system uses to locate the Build
2170 Directory.
2171
2172 For more information on ``externalsrc.bbclass``, see the
2173 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2174 can also find information on how to use this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002175 ":ref:`dev-manual/common-tasks:building software from an external source`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002176 section in the Yocto Project Development Tasks Manual.
2177
Andrew Geisslerf0343792020-11-18 10:42:21 -06002178 :term:`EXTRA_AUTORECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002179 For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
Andrew Geissler09036742021-06-25 14:25:14 -05002180 class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002181 pass to the ``autoreconf`` command that is executed during the
2182 :ref:`ref-tasks-configure` task.
2183
2184 The default value is "--exclude=autopoint".
2185
Andrew Geisslerf0343792020-11-18 10:42:21 -06002186 :term:`EXTRA_IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002187 A list of additional features to include in an image. When listing
2188 more than one feature, separate them with a space.
2189
2190 Typically, you configure this variable in your ``local.conf`` file,
2191 which is found in the :term:`Build Directory`.
2192 Although you can use this variable from within a recipe, best
2193 practices dictate that you do not.
2194
2195 .. note::
2196
2197 To enable primary features from within the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002198 :term:`IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002199
2200 Here are some examples of features you can add:
2201
2202 - "dbg-pkgs" - Adds -dbg packages for all installed packages including
2203 symbol information for debugging and profiling.
2204
2205 - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and
2206 enables post-installation logging. See the 'allow-empty-password' and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002207 'post-install-logging' features in the ":ref:`ref-features-image`"
2208 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002209 - "dev-pkgs" - Adds -dev packages for all installed packages. This is
2210 useful if you want to develop against the libraries in the image.
2211 - "read-only-rootfs" - Creates an image whose root filesystem is
2212 read-only. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002213 ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002214 section in the Yocto Project Development Tasks Manual for more
2215 information
2216 - "tools-debug" - Adds debugging tools such as gdb and strace.
2217 - "tools-sdk" - Adds development tools such as gcc, make,
2218 pkgconfig and so forth.
2219 - "tools-testapps" - Adds useful testing tools
2220 such as ts_print, aplay, arecord and so forth.
2221
2222 For a complete list of image features that ships with the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002223 Project, see the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002224
2225 For an example that shows how to customize your image by using this
Andrew Geissler09209ee2020-12-13 08:44:15 -06002226 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 -05002227 section in the Yocto Project Development Tasks Manual.
2228
Andrew Geisslerf0343792020-11-18 10:42:21 -06002229 :term:`EXTRA_IMAGECMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002230 Specifies additional options for the image creation command that has
2231 been specified in :term:`IMAGE_CMD`. When setting
2232 this variable, use an override for the associated image type. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002233 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002234
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002235 EXTRA_IMAGECMD:ext3 ?= "-i 4096"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002236
Andrew Geisslerf0343792020-11-18 10:42:21 -06002237 :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002238 A list of recipes to build that do not provide packages for
2239 installing into the root filesystem.
2240
2241 Sometimes a recipe is required to build the final image but is not
Andrew Geissler09036742021-06-25 14:25:14 -05002242 needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002243 variable to list these recipes and thus specify the dependencies. A
2244 typical example is a required bootloader in a machine configuration.
2245
2246 .. note::
2247
2248 To add packages to the root filesystem, see the various
Andrew Geissler95ac1b82021-03-31 14:34:31 -05002249 :term:`RDEPENDS` and :term:`RRECOMMENDS` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002250
Andrew Geisslerf0343792020-11-18 10:42:21 -06002251 :term:`EXTRANATIVEPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002252 A list of subdirectories of
2253 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2254 added to the beginning of the environment variable ``PATH``. As an
2255 example, the following prepends
2256 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
Andrew Geisslerc926e172021-05-07 16:11:35 -05002257 ``PATH``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002258
2259 EXTRANATIVEPATH = "foo bar"
2260
Andrew Geisslerf0343792020-11-18 10:42:21 -06002261 :term:`EXTRA_OECMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002262 Additional `CMake <https://cmake.org/overview/>`__ options. See the
2263 :ref:`cmake <ref-classes-cmake>` class for additional information.
2264
Andrew Geisslerf0343792020-11-18 10:42:21 -06002265 :term:`EXTRA_OECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002266 Additional ``configure`` script options. See
2267 :term:`PACKAGECONFIG_CONFARGS` for
2268 additional information on passing configure script options.
2269
Andrew Geisslerf0343792020-11-18 10:42:21 -06002270 :term:`EXTRA_OEMAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002271 Additional GNU ``make`` options.
2272
Andrew Geissler09036742021-06-25 14:25:14 -05002273 Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002274 variable to specify any required GNU options.
2275
2276 :term:`PARALLEL_MAKE` and
2277 :term:`PARALLEL_MAKEINST` also make use of
Andrew Geissler09036742021-06-25 14:25:14 -05002278 :term:`EXTRA_OEMAKE` to pass the required flags.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002279
Andrew Geisslerf0343792020-11-18 10:42:21 -06002280 :term:`EXTRA_OESCONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002281 When inheriting the :ref:`scons <ref-classes-scons>` class, this
2282 variable specifies additional configuration options you want to pass
2283 to the ``scons`` command line.
2284
Andrew Geisslerf0343792020-11-18 10:42:21 -06002285 :term:`EXTRA_USERS_PARAMS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002286 When inheriting the :ref:`extrausers <ref-classes-extrausers>`
2287 class, this variable provides image level user and group operations.
2288 This is a more global method of providing user and group
2289 configuration as compared to using the
2290 :ref:`useradd <ref-classes-useradd>` class, which ties user and
2291 group configurations to a specific recipe.
2292
2293 The set list of commands you can configure using the
Andrew Geissler09036742021-06-25 14:25:14 -05002294 :term:`EXTRA_USERS_PARAMS` is shown in the ``extrausers`` class. These
Andrew Geisslerc926e172021-05-07 16:11:35 -05002295 commands map to the normal Unix commands of the same names::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002296
2297 # EXTRA_USERS_PARAMS = "\
2298 # useradd -p '' tester; \
2299 # groupadd developers; \
2300 # userdel nobody; \
2301 # groupdel -g video; \
2302 # groupmod -g 1020 developers; \
2303 # usermod -s /bin/sh tester; \
2304 # "
2305
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002306 Additionally there is a special ``passwd-expire`` command that will
2307 cause the password for a user to be expired and thus force changing it
2308 on first login, for example::
2309
2310 EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;"
2311
2312 .. note::
2313
2314 At present, ``passwd-expire`` may only work for remote logins when
2315 using OpenSSH and not dropbear as an SSH server.
2316
Andrew Geisslerf0343792020-11-18 10:42:21 -06002317 :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002318 Defines one or more packages to include in an image when a specific
2319 item is included in :term:`IMAGE_FEATURES`.
Andrew Geissler09036742021-06-25 14:25:14 -05002320 When setting the value, :term:`FEATURE_PACKAGES` should have the name of
Andrew Geisslerc926e172021-05-07 16:11:35 -05002321 the feature item as an override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002322
2323 FEATURE_PACKAGES_widget = "package1 package2"
2324
Andrew Geissler09036742021-06-25 14:25:14 -05002325 In this example, if "widget" were added to :term:`IMAGE_FEATURES`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002326 package1 and package2 would be included in the image.
2327
2328 .. note::
2329
Andrew Geissler09036742021-06-25 14:25:14 -05002330 Packages installed by features defined through :term:`FEATURE_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002331 are often package groups. While similarly named, you should not
Andrew Geissler09036742021-06-25 14:25:14 -05002332 confuse the :term:`FEATURE_PACKAGES` variable with package groups, which
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002333 are discussed elsewhere in the documentation.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002334
Andrew Geisslerf0343792020-11-18 10:42:21 -06002335 :term:`FEED_DEPLOYDIR_BASE_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002336 Points to the base URL of the server and location within the
2337 document-root that provides the metadata and packages required by
2338 OPKG to support runtime package management of IPK packages. You set
2339 this variable in your ``local.conf`` file.
2340
Andrew Geisslerc926e172021-05-07 16:11:35 -05002341 Consider the following example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002342
2343 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2344
2345 This example assumes you are serving
2346 your packages over HTTP and your databases are located in a directory
2347 named ``BOARD-dir``, which is underneath your HTTP server's
2348 document-root. In this case, the OpenEmbedded build system generates
2349 a set of configuration files for you in your target that work with
2350 the feed.
2351
Andrew Geisslerf0343792020-11-18 10:42:21 -06002352 :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002353 The list of files and directories that are placed in a package. The
2354 :term:`PACKAGES` variable lists the packages
2355 generated by a recipe.
2356
Andrew Geissler09036742021-06-25 14:25:14 -05002357 To use the :term:`FILES` variable, provide a package name override that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002358 identifies the resulting package. Then, provide a space-separated
2359 list of files or paths that identify the files you want included as
Andrew Geisslerc926e172021-05-07 16:11:35 -05002360 part of the resulting package. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002361
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002362 FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002363
2364 .. note::
2365
2366 - When specifying files or paths, you can pattern match using
2367 Python's
2368 `glob <https://docs.python.org/3/library/glob.html>`_
2369 syntax. For details on the syntax, see the documentation by
2370 following the previous link.
2371
Andrew Geissler09036742021-06-25 14:25:14 -05002372 - When specifying paths as part of the :term:`FILES` variable, it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002373 good practice to use appropriate path variables. For example,
2374 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2375 rather than ``/usr/bin``. You can find a list of these
2376 variables at the top of the ``meta/conf/bitbake.conf`` file in
2377 the :term:`Source Directory`. You will also
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002378 find the default values of the various ``FILES:*`` variables in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002379 this file.
2380
Andrew Geissler09036742021-06-25 14:25:14 -05002381 If some of the files you provide with the :term:`FILES` variable are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002382 editable and you know they should not be overwritten during the
2383 package update process by the Package Management System (PMS), you
2384 can identify these files so that the PMS will not overwrite them. See
2385 the :term:`CONFFILES` variable for information on
2386 how to identify these files to the PMS.
2387
Andrew Geisslerf0343792020-11-18 10:42:21 -06002388 :term:`FILES_SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002389 Defines the file specification to match
2390 :term:`SOLIBSDEV`. In other words,
Andrew Geissler09036742021-06-25 14:25:14 -05002391 :term:`FILES_SOLIBSDEV` defines the full path name of the development
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002392 symbolic link (symlink) for shared libraries on the target platform.
2393
2394 The following statement from the ``bitbake.conf`` shows how it is
Andrew Geisslerc926e172021-05-07 16:11:35 -05002395 set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002396
2397 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2398
Andrew Geisslerf0343792020-11-18 10:42:21 -06002399 :term:`FILESEXTRAPATHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002400 Extends the search path the OpenEmbedded build system uses when
2401 looking for files and patches as it processes recipes and append
2402 files. The default directories BitBake uses when it processes recipes
2403 are initially defined by the :term:`FILESPATH`
Andrew Geissler09036742021-06-25 14:25:14 -05002404 variable. You can extend :term:`FILESPATH` variable by using
2405 :term:`FILESEXTRAPATHS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002406
2407 Best practices dictate that you accomplish this by using
Andrew Geissler09036742021-06-25 14:25:14 -05002408 :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you
Andrew Geisslerc926e172021-05-07 16:11:35 -05002409 prepend paths as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002410
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002411 FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002412
2413 In the above example, the build system first
2414 looks for files in a directory that has the same name as the
2415 corresponding append file.
2416
2417 .. note::
2418
Andrew Geissler09036742021-06-25 14:25:14 -05002419 When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002420 expansion (``:=``) operator. Immediate expansion makes sure that
2421 BitBake evaluates :term:`THISDIR` at the time the
2422 directive is encountered rather than at some later time when
2423 expansion might result in a directory that does not contain the
2424 files you need.
2425
2426 Also, include the trailing separating colon character if you are
2427 prepending. The trailing colon character is necessary because you
2428 are directing BitBake to extend the path by prepending directories
2429 to the search path.
2430
Andrew Geisslerc926e172021-05-07 16:11:35 -05002431 Here is another common use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002432
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002433 FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002434
2435 In this example, the build system extends the
Andrew Geissler09036742021-06-25 14:25:14 -05002436 :term:`FILESPATH` variable to include a directory named ``files`` that is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002437 in the same directory as the corresponding append file.
2438
Andrew Geisslerc926e172021-05-07 16:11:35 -05002439 This next example specifically adds three paths::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002440
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002441 FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002442
2443 A final example shows how you can extend the search path and include
2444 a :term:`MACHINE`-specific override, which is useful
Andrew Geisslerc926e172021-05-07 16:11:35 -05002445 in a BSP layer::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002446
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002447 FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002448
2449 The previous statement appears in the
2450 ``linux-yocto-dev.bbappend`` file, which is found in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002451 :ref:`overview-manual/development-environment:yocto project source repositories` in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002452 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2453 override is a special :term:`PACKAGE_ARCH`
2454 definition for multiple ``meta-intel`` machines.
2455
2456 .. note::
2457
2458 For a layer that supports a single BSP, the override could just be
Andrew Geissler09036742021-06-25 14:25:14 -05002459 the value of :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002460
2461 By prepending paths in ``.bbappend`` files, you allow multiple append
2462 files that reside in different layers but are used for the same
2463 recipe to correctly extend the path.
2464
Andrew Geisslerf0343792020-11-18 10:42:21 -06002465 :term:`FILESOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002466 A subset of :term:`OVERRIDES` used by the
2467 OpenEmbedded build system for creating
Andrew Geissler09036742021-06-25 14:25:14 -05002468 :term:`FILESPATH`. The :term:`FILESOVERRIDES` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002469 uses overrides to automatically extend the
2470 :term:`FILESPATH` variable. For an example of how
2471 that works, see the :term:`FILESPATH` variable
2472 description. Additionally, you find more information on how overrides
2473 are handled in the
2474 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2475 section of the BitBake User Manual.
2476
Andrew Geissler09036742021-06-25 14:25:14 -05002477 By default, the :term:`FILESOVERRIDES` variable is defined as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002478
2479 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2480
2481 .. note::
2482
Andrew Geissler09036742021-06-25 14:25:14 -05002483 Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002484 with expected overrides and are used in an expected manner by the
2485 build system.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002486
Andrew Geisslerf0343792020-11-18 10:42:21 -06002487 :term:`FILESPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002488 The default set of directories the OpenEmbedded build system uses
2489 when searching for patches and files.
2490
2491 During the build process, BitBake searches each directory in
Andrew Geissler09036742021-06-25 14:25:14 -05002492 :term:`FILESPATH` in the specified order when looking for files and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002493 patches specified by each ``file://`` URI in a recipe's
2494 :term:`SRC_URI` statements.
2495
Andrew Geissler09036742021-06-25 14:25:14 -05002496 The default value for the :term:`FILESPATH` variable is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002497 ``base.bbclass`` class found in ``meta/classes`` in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002498 :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002499
2500 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2501 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2502
2503 The
Andrew Geissler09036742021-06-25 14:25:14 -05002504 :term:`FILESPATH` variable is automatically extended using the overrides
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002505 from the :term:`FILESOVERRIDES` variable.
2506
2507 .. note::
2508
Andrew Geissler09036742021-06-25 14:25:14 -05002509 - Do not hand-edit the :term:`FILESPATH` variable. If you want the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002510 build system to look in directories other than the defaults,
Andrew Geissler09036742021-06-25 14:25:14 -05002511 extend the :term:`FILESPATH` variable by using the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002512 :term:`FILESEXTRAPATHS` variable.
2513
Andrew Geissler09036742021-06-25 14:25:14 -05002514 - Be aware that the default :term:`FILESPATH` directories do not map
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002515 to directories in custom layers where append files
2516 (``.bbappend``) are used. If you want the build system to find
2517 patches or files that reside with your append files, you need
Andrew Geissler09036742021-06-25 14:25:14 -05002518 to extend the :term:`FILESPATH` variable by using the
2519 :term:`FILESEXTRAPATHS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002520
2521 You can take advantage of this searching behavior in useful ways. For
William A. Kennington IIIac69b482021-06-02 12:28:27 -07002522 example, consider a case where there is the following directory structure
2523 for general and machine-specific configurations::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002524
2525 files/defconfig
2526 files/MACHINEA/defconfig
2527 files/MACHINEB/defconfig
2528
Andrew Geissler09036742021-06-25 14:25:14 -05002529 Also in the example, the :term:`SRC_URI` statement contains
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002530 "file://defconfig". Given this scenario, you can set
2531 :term:`MACHINE` to "MACHINEA" and cause the build
Andrew Geissler09036742021-06-25 14:25:14 -05002532 system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002533 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2534 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2535 build system uses files from ``files/defconfig``.
2536
2537 You can find out more about the patching process in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002538 ":ref:`overview-manual/concepts:patching`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002539 in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002540 ":ref:`dev-manual/common-tasks:patching code`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002541 the Yocto Project Development Tasks Manual. See the
2542 :ref:`ref-tasks-patch` task as well.
2543
Andrew Geisslerf0343792020-11-18 10:42:21 -06002544 :term:`FILESYSTEM_PERMS_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002545 Allows you to define your own file permissions settings table as part
2546 of your configuration for the packaging process. For example, suppose
2547 you need a consistent set of custom permissions for a set of groups
2548 and users across an entire work project. It is best to do this in the
2549 packages themselves but this is not always possible.
2550
2551 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2552 which is located in the ``meta/files`` folder in the :term:`Source Directory`.
2553 If you create your own file
2554 permissions setting table, you should place it in your layer or the
2555 distro's layer.
2556
Andrew Geissler09036742021-06-25 14:25:14 -05002557 You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002558 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2559 to point to your custom
2560 ``fs-perms.txt``. You can specify more than a single file permissions
2561 setting table. The paths you specify to these files must be defined
2562 within the :term:`BBPATH` variable.
2563
2564 For guidance on how to create your own file permissions settings
2565 table file, examine the existing ``fs-perms.txt``.
2566
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002567 :term:`FIT_DESC`
2568 Specifies the description string encoded into a fitImage. The default
2569 value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
2570 class as follows::
2571
2572 FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}"
2573
Andrew Geisslerf0343792020-11-18 10:42:21 -06002574 :term:`FIT_GENERATE_KEYS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002575 Decides whether to generate the keys for signing fitImage if they
Andrew Geissler09036742021-06-25 14:25:14 -05002576 don't already exist. The keys are created in :term:`UBOOT_SIGN_KEYDIR`.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002577 The default value is 0.
2578
Andrew Geisslerf0343792020-11-18 10:42:21 -06002579 :term:`FIT_HASH_ALG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002580 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
2581
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002582 :term:`FIT_KERNEL_COMP_ALG`
2583 Compression algorithm to use for the kernel image inside the FIT Image.
2584 At present, the only supported values are "gzip" (default) or "none"
2585 If you set this variable to anything other than "none" you may also need
2586 to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`.
2587
2588 :term:`FIT_KERNEL_COMP_ALG_EXTENSION`
2589 File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default
2590 value is ".gz".
2591
Andrew Geisslerf0343792020-11-18 10:42:21 -06002592 :term:`FIT_KEY_GENRSA_ARGS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002593 Arguments to openssl genrsa for generating RSA private key for signing
2594 fitImage. The default value is "-F4". i.e. the public exponent 65537 to
2595 use.
2596
Andrew Geisslerf0343792020-11-18 10:42:21 -06002597 :term:`FIT_KEY_REQ_ARGS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002598 Arguments to openssl req for generating certificate for signing fitImage.
2599 The default value is "-batch -new". batch for non interactive mode
2600 and new for generating new keys.
2601
Andrew Geisslerf0343792020-11-18 10:42:21 -06002602 :term:`FIT_KEY_SIGN_PKCS`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05002603 Format for public key certificate used in signing fitImage.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002604 The default value is "x509".
2605
Andrew Geisslerf0343792020-11-18 10:42:21 -06002606 :term:`FIT_SIGN_ALG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002607 Specifies the signature algorithm used in creating the FIT Image.
2608 For e.g. rsa2048.
2609
Andrew Geisslerf0343792020-11-18 10:42:21 -06002610 :term:`FIT_SIGN_NUMBITS`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002611 Size of private key in number of bits used in fitImage. The default
2612 value is "2048".
2613
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002614 :term:`FIT_SIGN_INDIVIDUAL`
2615 If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>`
2616 class will sign the kernel, dtb and ramdisk images individually in addition
2617 to signing the fitImage itself. This could be useful if you are
2618 intending to verify signatures in another context than booting via
2619 U-Boot.
2620
Andrew Geisslerf0343792020-11-18 10:42:21 -06002621 :term:`FONT_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002622 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2623 this variable specifies the runtime dependencies for font packages.
Andrew Geissler5f350902021-07-23 13:09:54 -04002624 By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002625
Andrew Geisslerf0343792020-11-18 10:42:21 -06002626 :term:`FONT_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002627 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2628 this variable identifies packages containing font files that need to
2629 be cached by Fontconfig. By default, the ``fontcache`` class assumes
2630 that fonts are in the recipe's main package (i.e.
2631 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
2632 need are in a package other than that main package.
2633
Andrew Geisslerf0343792020-11-18 10:42:21 -06002634 :term:`FORCE_RO_REMOVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002635 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
2636 during the generation of the root filesystem.
2637
2638 Set the variable to "1" to force the removal of these packages.
2639
Andrew Geisslerf0343792020-11-18 10:42:21 -06002640 :term:`FULL_OPTIMIZATION`
William A. Kennington IIIac69b482021-06-02 12:28:27 -07002641 The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002642 compiling an optimized system. This variable defaults to "-O2 -pipe
2643 ${DEBUG_FLAGS}".
2644
Andrew Geisslerf0343792020-11-18 10:42:21 -06002645 :term:`GCCPIE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002646 Enables Position Independent Executables (PIE) within the GNU C
2647 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
2648 Programming (ROP) attacks much more difficult to execute.
2649
2650 By default the ``security_flags.inc`` file enables PIE by setting the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002651 variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002652
2653 GCCPIE ?= "--enable-default-pie"
2654
Andrew Geisslerf0343792020-11-18 10:42:21 -06002655 :term:`GCCVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002656 Specifies the default version of the GNU C Compiler (GCC) used for
Andrew Geissler09036742021-06-25 14:25:14 -05002657 compilation. By default, :term:`GCCVERSION` is set to "8.x" in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002658 ``meta/conf/distro/include/tcmode-default.inc`` include file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002659
2660 GCCVERSION ?= "8.%"
2661
2662 You can override this value by setting it in a
2663 configuration file such as the ``local.conf``.
2664
Andrew Geisslerf0343792020-11-18 10:42:21 -06002665 :term:`GDB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002666 The minimal command and arguments to run the GNU Debugger.
2667
Andrew Geisslerf0343792020-11-18 10:42:21 -06002668 :term:`GITDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002669 The directory in which a local copy of a Git repository is stored
2670 when it is cloned.
2671
Andrew Geisslerf0343792020-11-18 10:42:21 -06002672 :term:`GLIBC_GENERATE_LOCALES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002673 Specifies the list of GLIBC locales to generate should you not wish
2674 to generate all LIBC locals, which can be time consuming.
2675
2676 .. note::
2677
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002678 If you specifically remove the locale ``en_US.UTF-8``, you must set
2679 :term:`IMAGE_LINGUAS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002680
Andrew Geissler09036742021-06-25 14:25:14 -05002681 You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002682 By default, all locales are generated.
2683 ::
2684
2685 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
2686
Andrew Geisslerf0343792020-11-18 10:42:21 -06002687 :term:`GROUPADD_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002688 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2689 this variable specifies for a package what parameters should be
2690 passed to the ``groupadd`` command if you wish to add a group to the
2691 system when the package is installed.
2692
Andrew Geisslerc926e172021-05-07 16:11:35 -05002693 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002694
Patrick Williams0ca19cc2021-08-16 14:03:13 -05002695 GROUPADD_PARAM:${PN} = "-r netdev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002696
2697 For information on the standard Linux shell command
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002698 ``groupadd``, see https://linux.die.net/man/8/groupadd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002699
Andrew Geisslerf0343792020-11-18 10:42:21 -06002700 :term:`GROUPMEMS_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002701 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2702 this variable specifies for a package what parameters should be
2703 passed to the ``groupmems`` command if you wish to modify the members
2704 of a group when the package is installed.
2705
2706 For information on the standard Linux shell command ``groupmems``,
Andrew Geisslerd1e89492021-02-12 15:35:20 -06002707 see https://linux.die.net/man/8/groupmems.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002708
Andrew Geisslerf0343792020-11-18 10:42:21 -06002709 :term:`GRUB_GFXSERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002710 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
2711 and serial in the boot menu. Set this variable to "1" in your
2712 ``local.conf`` or distribution configuration file to enable graphics
2713 and serial in the menu.
2714
2715 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
2716 information on how this variable is used.
2717
Andrew Geisslerf0343792020-11-18 10:42:21 -06002718 :term:`GRUB_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002719 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
2720 configuration. Use a semi-colon character (``;``) to separate
2721 multiple options.
2722
Andrew Geissler09036742021-06-25 14:25:14 -05002723 The :term:`GRUB_OPTS` variable is optional. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002724 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2725 on how this variable is used.
2726
Andrew Geisslerf0343792020-11-18 10:42:21 -06002727 :term:`GRUB_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002728 Specifies the timeout before executing the default ``LABEL`` in the
2729 GNU GRand Unified Bootloader (GRUB).
2730
Andrew Geissler09036742021-06-25 14:25:14 -05002731 The :term:`GRUB_TIMEOUT` variable is optional. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002732 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2733 on how this variable is used.
2734
Andrew Geisslerf0343792020-11-18 10:42:21 -06002735 :term:`GTKIMMODULES_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002736 When inheriting the
2737 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
2738 this variable specifies the packages that contain the GTK+ input
2739 method modules being installed when the modules are in packages other
2740 than the main package.
2741
Andrew Geisslerf0343792020-11-18 10:42:21 -06002742 :term:`HOMEPAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002743 Website where more information about the software the recipe is
2744 building can be found.
2745
Andrew Geisslerf0343792020-11-18 10:42:21 -06002746 :term:`HOST_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002747 The name of the target architecture, which is normally the same as
2748 :term:`TARGET_ARCH`. The OpenEmbedded build system
2749 supports many architectures. Here is an example list of architectures
2750 supported. This list is by no means complete as the architecture is
2751 configurable:
2752
2753 - arm
2754 - i586
2755 - x86_64
2756 - powerpc
2757 - powerpc64
2758 - mips
2759 - mipsel
2760
Andrew Geisslerf0343792020-11-18 10:42:21 -06002761 :term:`HOST_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002762 Specifies architecture-specific compiler flags that are passed to the
2763 C compiler.
2764
Andrew Geissler09036742021-06-25 14:25:14 -05002765 Default initialization for :term:`HOST_CC_ARCH` varies depending on what
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002766 is being built:
2767
2768 - :term:`TARGET_CC_ARCH` when building for the
2769 target
2770
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002771 - :term:`BUILD_CC_ARCH` when building for the build host (i.e.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002772 ``-native``)
2773
2774 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
2775 ``nativesdk-``)
2776
Andrew Geisslerf0343792020-11-18 10:42:21 -06002777 :term:`HOST_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002778 Specifies the name of the target operating system, which is normally
2779 the same as the :term:`TARGET_OS`. The variable can
2780 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
2781 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
2782 "linux-musleabi" values possible.
2783
Andrew Geisslerf0343792020-11-18 10:42:21 -06002784 :term:`HOST_PREFIX`
Andrew Geissler09036742021-06-25 14:25:14 -05002785 Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002786 is normally the same as :term:`TARGET_PREFIX`.
2787
Andrew Geisslerf0343792020-11-18 10:42:21 -06002788 :term:`HOST_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002789 Specifies the system, including the architecture and the operating
2790 system, for which the build is occurring in the context of the
2791 current recipe.
2792
2793 The OpenEmbedded build system automatically sets this variable based
2794 on :term:`HOST_ARCH`,
2795 :term:`HOST_VENDOR`, and
2796 :term:`HOST_OS` variables.
2797
2798 .. note::
2799
2800 You do not need to set the variable yourself.
2801
2802 Consider these two examples:
2803
2804 - Given a native recipe on a 32-bit x86 machine running Linux, the
2805 value is "i686-linux".
2806
2807 - Given a recipe being built for a little-endian MIPS target running
2808 Linux, the value might be "mipsel-linux".
2809
Andrew Geisslerf0343792020-11-18 10:42:21 -06002810 :term:`HOSTTOOLS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002811 A space-separated list (filter) of tools on the build host that
2812 should be allowed to be called from within build tasks. Using this
2813 filter helps reduce the possibility of host contamination. If a tool
Andrew Geissler09036742021-06-25 14:25:14 -05002814 specified in the value of :term:`HOSTTOOLS` is not found on the build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002815 host, the OpenEmbedded build system produces an error and the build
2816 is not started.
2817
2818 For additional information, see
2819 :term:`HOSTTOOLS_NONFATAL`.
2820
Andrew Geisslerf0343792020-11-18 10:42:21 -06002821 :term:`HOSTTOOLS_NONFATAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002822 A space-separated list (filter) of tools on the build host that
2823 should be allowed to be called from within build tasks. Using this
2824 filter helps reduce the possibility of host contamination. Unlike
2825 :term:`HOSTTOOLS`, the OpenEmbedded build system
2826 does not produce an error if a tool specified in the value of
Andrew Geissler09036742021-06-25 14:25:14 -05002827 :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can
2828 use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002829
Andrew Geisslerf0343792020-11-18 10:42:21 -06002830 :term:`HOST_VENDOR`
Andrew Geissler09036742021-06-25 14:25:14 -05002831 Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002832 same as :term:`TARGET_VENDOR`.
2833
Andrew Geisslerf0343792020-11-18 10:42:21 -06002834 :term:`ICECC_DISABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002835 Disables or enables the ``icecc`` (Icecream) function. For more
2836 information on this function and best practices for using this
2837 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`"
2838 section.
2839
2840 Setting this variable to "1" in your ``local.conf`` disables the
Andrew Geisslerc926e172021-05-07 16:11:35 -05002841 function::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002842
2843 ICECC_DISABLED ??= "1"
2844
Andrew Geisslerc926e172021-05-07 16:11:35 -05002845 To enable the function, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002846
2847 ICECC_DISABLED = ""
2848
Andrew Geisslerf0343792020-11-18 10:42:21 -06002849 :term:`ICECC_ENV_EXEC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002850 Points to the ``icecc-create-env`` script that you provide. This
2851 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You
2852 set this variable in your ``local.conf`` file.
2853
2854 If you do not point to a script that you provide, the OpenEmbedded
2855 build system uses the default script provided by the
2856 ``icecc-create-env.bb`` recipe, which is a modified version and not
2857 the one that comes with ``icecc``.
2858
Andrew Geisslerf0343792020-11-18 10:42:21 -06002859 :term:`ICECC_PARALLEL_MAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002860 Extra options passed to the ``make`` command during the
2861 :ref:`ref-tasks-compile` task that specify parallel
2862 compilation. This variable usually takes the form of "-j x", where x
2863 represents the maximum number of parallel threads ``make`` can run.
2864
2865 .. note::
2866
2867 The options passed affect builds on all enabled machines on the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05002868 network, which are machines running the ``iceccd`` daemon.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002869
2870 If your enabled machines support multiple cores, coming up with the
2871 maximum number of parallel threads that gives you the best
2872 performance could take some experimentation since machine speed,
2873 network lag, available memory, and existing machine loads can all
2874 affect build time. Consequently, unlike the
2875 :term:`PARALLEL_MAKE` variable, there is no
Andrew Geissler09036742021-06-25 14:25:14 -05002876 rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002877 performance.
2878
Andrew Geissler09036742021-06-25 14:25:14 -05002879 If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002880 use it (i.e. the system does not detect and assign the number of
Andrew Geissler09036742021-06-25 14:25:14 -05002881 cores as is done with :term:`PARALLEL_MAKE`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002882
Andrew Geisslerf0343792020-11-18 10:42:21 -06002883 :term:`ICECC_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002884 The location of the ``icecc`` binary. You can set this variable in
2885 your ``local.conf`` file. If your ``local.conf`` file does not define
2886 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts
2887 to define it by locating ``icecc`` using ``which``.
2888
Andrew Geisslerf0343792020-11-18 10:42:21 -06002889 :term:`ICECC_USER_CLASS_BL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002890 Identifies user classes that you do not want the Icecream distributed
2891 compile support to consider. This variable is used by the
2892 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2893 your ``local.conf`` file.
2894
2895 When you list classes using this variable, you are "blacklisting"
2896 them from distributed compilation across remote hosts. Any classes
2897 you list will be distributed and compiled locally.
2898
Andrew Geisslerf0343792020-11-18 10:42:21 -06002899 :term:`ICECC_USER_PACKAGE_BL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002900 Identifies user recipes that you do not want the Icecream distributed
2901 compile support to consider. This variable is used by the
2902 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2903 your ``local.conf`` file.
2904
2905 When you list packages using this variable, you are "blacklisting"
2906 them from distributed compilation across remote hosts. Any packages
2907 you list will be distributed and compiled locally.
2908
Andrew Geisslerf0343792020-11-18 10:42:21 -06002909 :term:`ICECC_USER_PACKAGE_WL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002910 Identifies user recipes that use an empty
2911 :term:`PARALLEL_MAKE` variable that you want to
2912 force remote distributed compilation on using the Icecream
2913 distributed compile support. This variable is used by the
2914 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2915 your ``local.conf`` file.
2916
Andrew Geisslerf0343792020-11-18 10:42:21 -06002917 :term:`IMAGE_BASENAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002918 The base name of image output files. This variable defaults to the
2919 recipe name (``${``\ :term:`PN`\ ``}``).
2920
Andrew Geisslerf0343792020-11-18 10:42:21 -06002921 :term:`IMAGE_EFI_BOOT_FILES`
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002922 A space-separated list of files installed into the boot partition
2923 when preparing an image using the Wic tool with the
2924 ``bootimg-efi`` source plugin. By default,
2925 the files are
2926 installed under the same name as the source files. To change the
2927 installed name, separate it from the original name with a semi-colon
2928 (;). Source files need to be located in
2929 :term:`DEPLOY_DIR_IMAGE`. Here are two
Andrew Geisslerc926e172021-05-07 16:11:35 -05002930 examples::
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002931
2932 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2"
2933 IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio"
2934
2935 Alternatively, source files can be picked up using a glob pattern. In
2936 this case, the destination file must have the same name as the base
2937 name of the source file path. To install files into a directory
2938 within the target location, pass its name after a semi-colon (;).
Andrew Geisslerc926e172021-05-07 16:11:35 -05002939 Here are two examples::
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002940
2941 IMAGE_EFI_BOOT_FILES = "boot/loader/*"
2942 IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/"
2943
2944 The first example
2945 installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/``
2946 into the root of the target partition. The second example installs
2947 the same files into a ``boot`` directory within the target partition.
2948
2949 You can find information on how to use the Wic tool in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002950 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002951 section of the Yocto Project Development Tasks Manual. Reference
2952 material for Wic is located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002953 ":doc:`/ref-manual/kickstart`" chapter.
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002954
Andrew Geisslerf0343792020-11-18 10:42:21 -06002955 :term:`IMAGE_BOOT_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002956 A space-separated list of files installed into the boot partition
2957 when preparing an image using the Wic tool with the
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05002958 ``bootimg-partition`` source plugin. By default,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002959 the files are
2960 installed under the same name as the source files. To change the
2961 installed name, separate it from the original name with a semi-colon
2962 (;). Source files need to be located in
2963 :term:`DEPLOY_DIR_IMAGE`. Here are two
Andrew Geisslerc926e172021-05-07 16:11:35 -05002964 examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002965
2966 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2967 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
2968
2969 Alternatively, source files can be picked up using a glob pattern. In
2970 this case, the destination file must have the same name as the base
2971 name of the source file path. To install files into a directory
2972 within the target location, pass its name after a semi-colon (;).
Andrew Geisslerc926e172021-05-07 16:11:35 -05002973 Here are two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002974
2975 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2976 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
2977
2978 The first example
2979 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
2980 into the root of the target partition. The second example installs
2981 the same files into a ``boot`` directory within the target partition.
2982
2983 You can find information on how to use the Wic tool in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002984 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002985 section of the Yocto Project Development Tasks Manual. Reference
2986 material for Wic is located in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06002987 ":doc:`/ref-manual/kickstart`" chapter.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002988
Andrew Geisslerf0343792020-11-18 10:42:21 -06002989 :term:`IMAGE_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002990 A list of classes that all images should inherit. You typically use
2991 this variable to specify the list of classes that register the
2992 different types of images the OpenEmbedded build system creates.
2993
Andrew Geissler09036742021-06-25 14:25:14 -05002994 The default value for :term:`IMAGE_CLASSES` is ``image_types``. You can
Andrew Geisslerc9f78652020-09-18 14:11:35 -05002995 set this variable in your ``local.conf`` or in a distribution
2996 configuration file.
2997
2998 For more information, see ``meta/classes/image_types.bbclass`` in the
2999 :term:`Source Directory`.
3000
Andrew Geisslerf0343792020-11-18 10:42:21 -06003001 :term:`IMAGE_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003002 Specifies the command to create the image file for a specific image
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003003 type, which corresponds to the value set in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003004 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
3005 ``btrfs``, and so forth). When setting this variable, you should use
Andrew Geisslerc926e172021-05-07 16:11:35 -05003006 an override for the associated type. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003007
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003008 IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \
Andrew Geissler09036742021-06-25 14:25:14 -05003009 --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003010 ${EXTRA_IMAGECMD}"
3011
3012 You typically do not need to set this variable unless you are adding
3013 support for a new image type. For more examples on how to set this
3014 variable, see the :ref:`image_types <ref-classes-image_types>`
3015 class file, which is ``meta/classes/image_types.bbclass``.
3016
Andrew Geisslerf0343792020-11-18 10:42:21 -06003017 :term:`IMAGE_DEVICE_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003018 Specifies one or more files that contain custom device tables that
3019 are passed to the ``makedevs`` command as part of creating an image.
3020 These files list basic device nodes that should be created under
Andrew Geissler09036742021-06-25 14:25:14 -05003021 ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003022 ``files/device_table-minimal.txt`` is used, which is located by
3023 :term:`BBPATH`. For details on how you should write
3024 device table files, see ``meta/files/device_table-minimal.txt`` as an
3025 example.
3026
Andrew Geisslerf0343792020-11-18 10:42:21 -06003027 :term:`IMAGE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003028 The primary list of features to include in an image. Typically, you
3029 configure this variable in an image recipe. Although you can use this
3030 variable from your ``local.conf`` file, which is found in the
3031 :term:`Build Directory`, best practices dictate that you do
3032 not.
3033
3034 .. note::
3035
3036 To enable extra features from outside the image recipe, use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003037 :term:`EXTRA_IMAGE_FEATURES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003038
3039 For a list of image features that ships with the Yocto Project, see
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003040 the ":ref:`ref-features-image`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003041
3042 For an example that shows how to customize your image by using this
Andrew Geissler09209ee2020-12-13 08:44:15 -06003043 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 -05003044 section in the Yocto Project Development Tasks Manual.
3045
Andrew Geisslerf0343792020-11-18 10:42:21 -06003046 :term:`IMAGE_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003047 Specifies the formats the OpenEmbedded build system uses during the
3048 build when creating the root filesystem. For example, setting
Andrew Geissler09036742021-06-25 14:25:14 -05003049 :term:`IMAGE_FSTYPES` as follows causes the build system to create root
Andrew Geisslerc926e172021-05-07 16:11:35 -05003050 filesystems using two formats: ``.ext3`` and ``.tar.bz2``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003051
3052 IMAGE_FSTYPES = "ext3 tar.bz2"
3053
3054 For the complete list of supported image formats from which you can
3055 choose, see :term:`IMAGE_TYPES`.
3056
3057 .. note::
3058
3059 - If an image recipe uses the "inherit image" line and you are
Andrew Geissler09036742021-06-25 14:25:14 -05003060 setting :term:`IMAGE_FSTYPES` inside the recipe, you must set
Andrew Geissler5f350902021-07-23 13:09:54 -04003061 :term:`IMAGE_FSTYPES` prior to using the "inherit image" line.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003062
3063 - Due to the way the OpenEmbedded build system processes this
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003064 variable, you cannot update its contents by using ``:append``
3065 or ``:prepend``. You must use the ``+=`` operator to add one or
Andrew Geissler09036742021-06-25 14:25:14 -05003066 more options to the :term:`IMAGE_FSTYPES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003067
Andrew Geisslerf0343792020-11-18 10:42:21 -06003068 :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003069 Used by recipes to specify the packages to install into an image
3070 through the :ref:`image <ref-classes-image>` class. Use the
Andrew Geissler09036742021-06-25 14:25:14 -05003071 :term:`IMAGE_INSTALL` variable with care to avoid ordering issues.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003072
Andrew Geissler09036742021-06-25 14:25:14 -05003073 Image recipes set :term:`IMAGE_INSTALL` to specify the packages to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003074 install into an image through ``image.bbclass``. Additionally,
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003075 there are "helper" classes such as the
3076 :ref:`core-image <ref-classes-core-image>` class which can
Andrew Geissler09036742021-06-25 14:25:14 -05003077 take lists used with :term:`IMAGE_FEATURES` and turn them into
3078 auto-generated entries in :term:`IMAGE_INSTALL` in addition to its
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003079 default contents.
3080
Andrew Geisslerc926e172021-05-07 16:11:35 -05003081 When you use this variable, it is best to use it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003082
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003083 IMAGE_INSTALL:append = " package-name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003084
3085 Be sure to include the space
3086 between the quotation character and the start of the package name or
3087 names.
3088
3089 .. note::
3090
3091 - When working with a
Andrew Geissler09209ee2020-12-13 08:44:15 -06003092 :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Andrew Geissler09036742021-06-25 14:25:14 -05003093 image, do not use the :term:`IMAGE_INSTALL` variable to specify
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003094 packages for installation. Instead, use the
3095 :term:`PACKAGE_INSTALL` variable, which
3096 allows the initial RAM filesystem (initramfs) recipe to use a
Andrew Geissler09036742021-06-25 14:25:14 -05003097 fixed set of packages and not be affected by :term:`IMAGE_INSTALL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003098 For information on creating an initramfs, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003099 ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003100 section in the Yocto Project Development Tasks Manual.
3101
Andrew Geissler09036742021-06-25 14:25:14 -05003102 - Using :term:`IMAGE_INSTALL` with the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003103 :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003104 BitBake operator within the ``/conf/local.conf`` file or from
3105 within an image recipe is not recommended. Use of this operator
3106 in these ways can cause ordering issues. Since
Andrew Geissler09036742021-06-25 14:25:14 -05003107 ``core-image.bbclass`` sets :term:`IMAGE_INSTALL` to a default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003108 value using the
3109 :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
Andrew Geissler09036742021-06-25 14:25:14 -05003110 operator, using a ``+=`` operation against :term:`IMAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003111 results in unexpected behavior when used within
3112 ``conf/local.conf``. Furthermore, the same operation from
3113 within an image recipe may or may not succeed depending on the
3114 specific situation. In both these cases, the behavior is
3115 contrary to how most users expect the ``+=`` operator to work.
3116
Andrew Geisslerf0343792020-11-18 10:42:21 -06003117 :term:`IMAGE_LINGUAS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003118 Specifies the list of locales to install into the image during the
3119 root filesystem construction process. The OpenEmbedded build system
3120 automatically splits locale files, which are used for localization,
Andrew Geissler09036742021-06-25 14:25:14 -05003121 into separate packages. Setting the :term:`IMAGE_LINGUAS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003122 ensures that any locale packages that correspond to packages already
3123 selected for installation into the image are also installed. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05003124 an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003125
3126 IMAGE_LINGUAS = "pt-br de-de"
3127
3128 In this example, the build system ensures any Brazilian Portuguese
3129 and German locale files that correspond to packages in the image are
3130 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
3131 ``*-locale-pt`` and ``*-locale-de``, since some software packages
3132 only provide locale files by language and not by country-specific
3133 language).
3134
3135 See the :term:`GLIBC_GENERATE_LOCALES`
3136 variable for information on generating GLIBC locales.
3137
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003138
3139 :term:`IMAGE_LINK_NAME`
3140 The name of the output image symlink (which does not include
3141 the version part as :term:`IMAGE_NAME` does). The default value
3142 is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003143 variables::
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003144
3145 IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}"
3146
3147
Andrew Geisslerf0343792020-11-18 10:42:21 -06003148 :term:`IMAGE_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003149 The manifest file for the image. This file lists all the installed
3150 packages that make up the image. The file contains package
Andrew Geisslerc926e172021-05-07 16:11:35 -05003151 information on a line-per-package basis as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003152
3153 packagename packagearch version
3154
Andrew Geissler09036742021-06-25 14:25:14 -05003155 The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest
Andrew Geisslerc926e172021-05-07 16:11:35 -05003156 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003157
Andrew Geissler09036742021-06-25 14:25:14 -05003158 IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003159
3160 The location is
Andrew Geissler09036742021-06-25 14:25:14 -05003161 derived using the :term:`IMGDEPLOYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003162 and :term:`IMAGE_NAME` variables. You can find
Andrew Geissler09209ee2020-12-13 08:44:15 -06003163 information on how the image is created in the ":ref:`overview-manual/concepts:image generation`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003164 section in the Yocto Project Overview and Concepts Manual.
3165
Andrew Geisslerf0343792020-11-18 10:42:21 -06003166 :term:`IMAGE_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003167 The name of the output image files minus the extension. This variable
3168 is derived using the :term:`IMAGE_BASENAME`,
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003169 :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003170 variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003171
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003172 IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3173
3174 :term:`IMAGE_NAME_SUFFIX`
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003175 Suffix used for the image output filename - defaults to ``".rootfs"``
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003176 to distinguish the image file from other files created during image
3177 building; however if this suffix is redundant or not desired you can
3178 clear the value of this variable (set the value to ""). For example,
3179 this is typically cleared in initramfs image recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003180
Andrew Geisslerf0343792020-11-18 10:42:21 -06003181 :term:`IMAGE_OVERHEAD_FACTOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003182 Defines a multiplier that the build system applies to the initial
3183 image size for cases when the multiplier times the returned disk
3184 usage value for the image is greater than the sum of
Andrew Geissler09036742021-06-25 14:25:14 -05003185 :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003186 the multiplier applied to the initial image size creates free disk
3187 space in the image as overhead. By default, the build process uses a
3188 multiplier of 1.3 for this variable. This default value results in
3189 30% free disk space added to the image when this method is used to
3190 determine the final generated image size. You should be aware that
3191 post install scripts and the package management system uses disk
3192 space inside this overhead area. Consequently, the multiplier does
3193 not produce an image with all the theoretical free disk space. See
Andrew Geissler09036742021-06-25 14:25:14 -05003194 :term:`IMAGE_ROOTFS_SIZE` for information on how the build system
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003195 determines the overall image size.
3196
3197 The default 30% free disk space typically gives the image enough room
3198 to boot and allows for basic post installs while still leaving a
3199 small amount of free disk space. If 30% free space is inadequate, you
3200 can increase the default value. For example, the following setting
Andrew Geisslerc926e172021-05-07 16:11:35 -05003201 gives you 50% free space added to the image::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003202
3203 IMAGE_OVERHEAD_FACTOR = "1.5"
3204
3205 Alternatively, you can ensure a specific amount of free disk space is
Andrew Geissler09036742021-06-25 14:25:14 -05003206 added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003207 variable.
3208
Andrew Geisslerf0343792020-11-18 10:42:21 -06003209 :term:`IMAGE_PKGTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003210 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
3211 OpenEmbedded build system. The variable is defined appropriately by
3212 the :ref:`package_deb <ref-classes-package_deb>`,
3213 :ref:`package_rpm <ref-classes-package_rpm>`,
3214 :ref:`package_ipk <ref-classes-package_ipk>`, or
3215 :ref:`package_tar <ref-classes-package_tar>` class.
3216
3217 .. note::
3218
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003219 The ``package_tar`` class is broken and is not supported. It is
3220 recommended that you do not use it.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003221
3222 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
Andrew Geissler09036742021-06-25 14:25:14 -05003223 :ref:`image <ref-classes-image>` classes use the :term:`IMAGE_PKGTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003224 for packaging up images and SDKs.
3225
Andrew Geissler09036742021-06-25 14:25:14 -05003226 You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003227 variable is set indirectly through the appropriate
3228 :ref:`package_* <ref-classes-package>` class using the
3229 :term:`PACKAGE_CLASSES` variable. The
3230 OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
3231 or IPK) that appears with the variable
3232
3233 .. note::
3234
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003235 Files using the ``.tar`` format are never used as a substitute
3236 packaging format for DEB, RPM, and IPK formatted files for your image
3237 or SDK.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003238
Andrew Geisslerf0343792020-11-18 10:42:21 -06003239 :term:`IMAGE_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003240 Specifies a list of functions to call once the OpenEmbedded build
3241 system creates the final image output files. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05003242 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003243
3244 IMAGE_POSTPROCESS_COMMAND += "function; ... "
3245
3246 If you need to pass the root filesystem path to a command within the
3247 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3248 directory that becomes the root filesystem image. See the
3249 :term:`IMAGE_ROOTFS` variable for more
3250 information.
3251
Andrew Geisslerf0343792020-11-18 10:42:21 -06003252 :term:`IMAGE_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003253 Specifies a list of functions to call before the OpenEmbedded build
3254 system creates the final image output files. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05003255 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003256
3257 IMAGE_PREPROCESS_COMMAND += "function; ... "
3258
3259 If you need to pass the root filesystem path to a command within the
3260 function, you can use ``${IMAGE_ROOTFS}``, which points to the
3261 directory that becomes the root filesystem image. See the
3262 :term:`IMAGE_ROOTFS` variable for more
3263 information.
3264
Andrew Geisslerf0343792020-11-18 10:42:21 -06003265 :term:`IMAGE_ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003266 The location of the root filesystem while it is under construction
3267 (i.e. during the :ref:`ref-tasks-rootfs` task). This
3268 variable is not configurable. Do not change it.
3269
Andrew Geisslerf0343792020-11-18 10:42:21 -06003270 :term:`IMAGE_ROOTFS_ALIGNMENT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003271 Specifies the alignment for the output image file in Kbytes. If the
3272 size of the image is not a multiple of this value, then the size is
3273 rounded up to the nearest multiple of the value. The default value is
3274 "1". See :term:`IMAGE_ROOTFS_SIZE` for
3275 additional information.
3276
Andrew Geisslerf0343792020-11-18 10:42:21 -06003277 :term:`IMAGE_ROOTFS_EXTRA_SPACE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003278 Defines additional free disk space created in the image in Kbytes. By
3279 default, this variable is set to "0". This free disk space is added
3280 to the image after the build system determines the image size as
Andrew Geissler09036742021-06-25 14:25:14 -05003281 described in :term:`IMAGE_ROOTFS_SIZE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003282
3283 This variable is particularly useful when you want to ensure that a
3284 specific amount of free disk space is available on a device after an
3285 image is installed and running. For example, to be sure 5 Gbytes of
Andrew Geisslerc926e172021-05-07 16:11:35 -05003286 free disk space is available, set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003287
3288 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3289
3290 For example, the Yocto Project Build Appliance specifically requests
Andrew Geisslerc926e172021-05-07 16:11:35 -05003291 40 Gbytes of extra space with the line::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003292
3293 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3294
Andrew Geisslerf0343792020-11-18 10:42:21 -06003295 :term:`IMAGE_ROOTFS_SIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003296 Defines the size in Kbytes for the generated image. The OpenEmbedded
3297 build system determines the final size for the generated image using
3298 an algorithm that takes into account the initial disk space used for
3299 the generated image, a requested size for the image, and requested
3300 additional free disk space to be added to the image. Programatically,
3301 the build system determines the final size of the generated image as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003302 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003303
3304 if (image-du * overhead) < rootfs-size:
3305 internal-rootfs-size = rootfs-size + xspace
3306 else:
3307 internal-rootfs-size = (image-du * overhead) + xspace
3308 where:
3309 image-du = Returned value of the du command on the image.
3310 overhead = IMAGE_OVERHEAD_FACTOR
3311 rootfs-size = IMAGE_ROOTFS_SIZE
3312 internal-rootfs-size = Initial root filesystem size before any modifications.
3313 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3314
3315 See the :term:`IMAGE_OVERHEAD_FACTOR`
3316 and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
3317 variables for related information.
3318
Andrew Geisslerf0343792020-11-18 10:42:21 -06003319 :term:`IMAGE_TYPEDEP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003320 Specifies a dependency from one image type on another. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05003321 example from the :ref:`image-live <ref-classes-image-live>` class::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003322
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003323 IMAGE_TYPEDEP:live = "ext3"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003324
3325 In the previous example, the variable ensures that when "live" is
3326 listed with the :term:`IMAGE_FSTYPES` variable,
3327 the OpenEmbedded build system produces an ``ext3`` image first since
3328 one of the components of the live image is an ``ext3`` formatted
3329 partition containing the root filesystem.
3330
Andrew Geisslerf0343792020-11-18 10:42:21 -06003331 :term:`IMAGE_TYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003332 Specifies the complete list of supported image types by default:
3333
3334 - btrfs
3335 - container
3336 - cpio
3337 - cpio.gz
3338 - cpio.lz4
3339 - cpio.lzma
3340 - cpio.xz
3341 - cramfs
Andrew Geissler09036742021-06-25 14:25:14 -05003342 - erofs
3343 - erofs-lz4
3344 - erofs-lz4hc
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003345 - ext2
3346 - ext2.bz2
3347 - ext2.gz
3348 - ext2.lzma
3349 - ext3
3350 - ext3.gz
3351 - ext4
3352 - ext4.gz
3353 - f2fs
3354 - hddimg
3355 - iso
3356 - jffs2
3357 - jffs2.sum
3358 - multiubi
3359 - squashfs
3360 - squashfs-lz4
3361 - squashfs-lzo
3362 - squashfs-xz
3363 - tar
3364 - tar.bz2
3365 - tar.gz
3366 - tar.lz4
3367 - tar.xz
3368 - tar.zst
3369 - ubi
3370 - ubifs
3371 - wic
3372 - wic.bz2
3373 - wic.gz
3374 - wic.lzma
3375
3376 For more information about these types of images, see
3377 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`.
3378
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003379 :term:`IMAGE_VERSION_SUFFIX`
3380 Version suffix that is part of the default :term:`IMAGE_NAME` and
3381 :term:`KERNEL_ARTIFACT_NAME` values.
3382 Defaults to ``"-${DATETIME}"``, however you could set this to a
3383 version string that comes from your external build environment if
3384 desired, and this suffix would then be used consistently across
3385 the build artifacts.
3386
Andrew Geissler09036742021-06-25 14:25:14 -05003387 :term:`IMGDEPLOYDIR`
3388 When inheriting the :ref:`image <ref-classes-image>` class directly or
3389 through the :ref:`core-image <ref-classes-core-image>` class, the
Andrew Geissler5f350902021-07-23 13:09:54 -04003390 :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files
Andrew Geissler09036742021-06-25 14:25:14 -05003391 that is set in the ``image`` class as follows::
3392
3393 IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete"
3394
3395 Recipes inheriting the ``image`` class should copy files to be
Andrew Geissler5f350902021-07-23 13:09:54 -04003396 deployed into :term:`IMGDEPLOYDIR`, and the class will take care of
Andrew Geissler09036742021-06-25 14:25:14 -05003397 copying them into :term:`DEPLOY_DIR_IMAGE` afterwards.
3398
Andrew Geisslerf0343792020-11-18 10:42:21 -06003399 :term:`INC_PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003400 Helps define the recipe revision for recipes that share a common
3401 ``include`` file. You can think of this variable as part of the
3402 recipe revision as set from within an include file.
3403
3404 Suppose, for example, you have a set of recipes that are used across
3405 several projects. And, within each of those recipes the revision (its
3406 :term:`PR` value) is set accordingly. In this case, when
3407 the revision of those recipes changes, the burden is on you to find
3408 all those recipes and be sure that they get changed to reflect the
3409 updated version of the recipe. In this scenario, it can get
3410 complicated when recipes that are used in many places and provide
3411 common functionality are upgraded to a new revision.
3412
3413 A more efficient way of dealing with this situation is to set the
Andrew Geissler09036742021-06-25 14:25:14 -05003414 :term:`INC_PR` variable inside the ``include`` files that the recipes
3415 share and then expand the :term:`INC_PR` variable within the recipes to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003416 help define the recipe revision.
3417
3418 The following provides an example that shows how to use the
Andrew Geissler09036742021-06-25 14:25:14 -05003419 :term:`INC_PR` variable given a common ``include`` file that defines the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003420 variable. Once the variable is defined in the ``include`` file, you
Andrew Geissler09036742021-06-25 14:25:14 -05003421 can use the variable to set the :term:`PR` values in each recipe. You
3422 will notice that when you set a recipe's :term:`PR` you can provide more
3423 granular revisioning by appending values to the :term:`INC_PR` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003424
3425 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3426 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3427 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3428 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3429
3430 The
3431 first line of the example establishes the baseline revision to be
3432 used for all recipes that use the ``include`` file. The remaining
3433 lines in the example are from individual recipes and show how the
Andrew Geissler09036742021-06-25 14:25:14 -05003434 :term:`PR` value is set.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003435
Andrew Geisslerf0343792020-11-18 10:42:21 -06003436 :term:`INCOMPATIBLE_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003437 Specifies a space-separated list of license names (as they would
3438 appear in :term:`LICENSE`) that should be excluded
3439 from the build. Recipes that provide no alternatives to listed
3440 incompatible licenses are not built. Packages that are individually
3441 licensed with the specified incompatible licenses will be deleted.
3442
3443 .. note::
3444
3445 This functionality is only regularly tested using the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05003446 setting::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003447
3448 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
3449
3450
3451 Although you can use other settings, you might be required to
3452 remove dependencies on or provide alternatives to components that
3453 are required to produce a functional system image.
3454
3455 .. note::
3456
3457 It is possible to define a list of licenses that are allowed to be
3458 used instead of the licenses that are excluded. To do this, define
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003459 a variable ``COMPATIBLE_LICENSES`` with the names of the licenses
Andrew Geissler09036742021-06-25 14:25:14 -05003460 that are allowed. Then define :term:`INCOMPATIBLE_LICENSE` as::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003461
3462 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
3463
3464
Andrew Geissler09036742021-06-25 14:25:14 -05003465 This will result in :term:`INCOMPATIBLE_LICENSE` containing the names of
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05003466 all licenses from :term:`AVAILABLE_LICENSES` except the ones specified
3467 in ``COMPATIBLE_LICENSES``, thus only allowing the latter licenses to
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003468 be used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003469
Andrew Geisslerf0343792020-11-18 10:42:21 -06003470 :term:`INHERIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003471 Causes the named class or classes to be inherited globally. Anonymous
3472 functions in the class or classes are not executed for the base
3473 configuration and in each individual recipe. The OpenEmbedded build
Andrew Geissler09036742021-06-25 14:25:14 -05003474 system ignores changes to :term:`INHERIT` in individual recipes.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003475
Andrew Geissler09036742021-06-25 14:25:14 -05003476 For more information on :term:`INHERIT`, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003477 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
3478 section in the Bitbake User Manual.
3479
Andrew Geisslerf0343792020-11-18 10:42:21 -06003480 :term:`INHERIT_DISTRO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003481 Lists classes that will be inherited at the distribution level. It is
3482 unlikely that you want to edit this variable.
3483
3484 The default value of the variable is set as follows in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003485 ``meta/conf/distro/defaultsetup.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003486
3487 INHERIT_DISTRO ?= "debian devshell sstate license"
3488
Andrew Geisslerf0343792020-11-18 10:42:21 -06003489 :term:`INHIBIT_DEFAULT_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003490 Prevents the default dependencies, namely the C compiler and standard
3491 C library (libc), from being added to :term:`DEPENDS`.
3492 This variable is usually used within recipes that do not require any
3493 compilation using the C compiler.
3494
3495 Set the variable to "1" to prevent the default dependencies from
3496 being added.
3497
Andrew Geisslerf0343792020-11-18 10:42:21 -06003498 :term:`INHIBIT_PACKAGE_DEBUG_SPLIT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003499 Prevents the OpenEmbedded build system from splitting out debug
3500 information during packaging. By default, the build system splits out
3501 debugging information during the
3502 :ref:`ref-tasks-package` task. For more information on
3503 how debug information is split out, see the
3504 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
3505 variable.
3506
3507 To prevent the build system from splitting out debug information
Andrew Geissler09036742021-06-25 14:25:14 -05003508 during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003509 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003510
3511 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
3512
Andrew Geisslerf0343792020-11-18 10:42:21 -06003513 :term:`INHIBIT_PACKAGE_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003514 If set to "1", causes the build to not strip binaries in resulting
3515 packages and prevents the ``-dbg`` package from containing the source
3516 files.
3517
3518 By default, the OpenEmbedded build system strips binaries and puts
3519 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
Andrew Geissler09036742021-06-25 14:25:14 -05003520 Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003521 plan to debug in general.
3522
Andrew Geisslerf0343792020-11-18 10:42:21 -06003523 :term:`INHIBIT_SYSROOT_STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003524 If set to "1", causes the build to not strip binaries in the
3525 resulting sysroot.
3526
3527 By default, the OpenEmbedded build system strips binaries in the
3528 resulting sysroot. When you specifically set the
Andrew Geissler09036742021-06-25 14:25:14 -05003529 :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003530 this stripping.
3531
3532 If you want to use this variable, include the
3533 :ref:`staging <ref-classes-staging>` class. This class uses a
3534 ``sys_strip()`` function to test for the variable and acts
3535 accordingly.
3536
3537 .. note::
3538
Andrew Geissler09036742021-06-25 14:25:14 -05003539 Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003540 special circumstances. For example, suppose you are building
3541 bare-metal firmware by using an external GCC toolchain. Furthermore,
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003542 even if the toolchain's binaries are strippable, there are other files
3543 needed for the build that are not strippable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003544
Andrew Geisslerf0343792020-11-18 10:42:21 -06003545 :term:`INITRAMFS_FSTYPES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003546 Defines the format for the output image of an initial RAM filesystem
3547 (initramfs), which is used during boot. Supported formats are the
3548 same as those supported by the
3549 :term:`IMAGE_FSTYPES` variable.
3550
3551 The default value of this variable, which is set in the
3552 ``meta/conf/bitbake.conf`` configuration file in the
3553 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
3554 initramfs mechanism, as opposed to the initial RAM filesystem
3555 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
3556 an optionally compressed cpio archive.
3557
Andrew Geisslerf0343792020-11-18 10:42:21 -06003558 :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003559 Specifies the :term:`PROVIDES` name of an image
3560 recipe that is used to build an initial RAM filesystem (initramfs)
Andrew Geissler09036742021-06-25 14:25:14 -05003561 image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003562 additional recipe to be built as a dependency to whatever root
3563 filesystem recipe you might be using (e.g. ``core-image-sato``). The
3564 initramfs image recipe you provide should set
3565 :term:`IMAGE_FSTYPES` to
3566 :term:`INITRAMFS_FSTYPES`.
3567
3568 An initramfs image provides a temporary root filesystem used for
3569 early system initialization (e.g. loading of modules needed to locate
3570 and mount the "real" root filesystem).
3571
3572 .. note::
3573
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003574 See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb``
3575 recipe in the :term:`Source Directory`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003576 for an example initramfs recipe. To select this sample recipe as
Andrew Geissler09036742021-06-25 14:25:14 -05003577 the one built to provide the initramfs image, set :term:`INITRAMFS_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003578 to "core-image-minimal-initramfs".
3579
3580 You can also find more information by referencing the
3581 ``meta-poky/conf/local.conf.sample.extended`` configuration file in
3582 the Source Directory, the :ref:`image <ref-classes-image>` class,
3583 and the :ref:`kernel <ref-classes-kernel>` class to see how to use
Andrew Geissler09036742021-06-25 14:25:14 -05003584 the :term:`INITRAMFS_IMAGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003585
Andrew Geissler09036742021-06-25 14:25:14 -05003586 If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003587 initramfs image is built.
3588
3589 For more information, you can also see the
3590 :term:`INITRAMFS_IMAGE_BUNDLE`
3591 variable, which allows the generated image to be bundled inside the
3592 kernel image. Additionally, for information on creating an initramfs
Andrew Geissler09209ee2020-12-13 08:44:15 -06003593 image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003594 in the Yocto Project Development Tasks Manual.
3595
Andrew Geisslerf0343792020-11-18 10:42:21 -06003596 :term:`INITRAMFS_IMAGE_BUNDLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003597 Controls whether or not the image recipe specified by
3598 :term:`INITRAMFS_IMAGE` is run through an
3599 extra pass
3600 (:ref:`ref-tasks-bundle_initramfs`) during
3601 kernel compilation in order to build a single binary that contains
3602 both the kernel image and the initial RAM filesystem (initramfs)
3603 image. This makes use of the
3604 :term:`CONFIG_INITRAMFS_SOURCE` kernel
3605 feature.
3606
3607 .. note::
3608
Patrick Williams93c203f2021-10-06 16:15:23 -05003609 Bundling the initramfs with the kernel conflates the code in the
3610 initramfs with the GPLv2 licensed Linux kernel binary. Thus only GPLv2
3611 compatible software may be part of a bundled initramfs.
3612
3613 .. note::
3614
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003615 Using an extra compilation pass to bundle the initramfs avoids a
3616 circular dependency between the kernel recipe and the initramfs
3617 recipe should the initramfs include kernel modules. Should that be
3618 the case, the initramfs recipe depends on the kernel for the
3619 kernel modules, and the kernel depends on the initramfs recipe
3620 since the initramfs is bundled inside the kernel image.
3621
3622 The combined binary is deposited into the ``tmp/deploy`` directory,
3623 which is part of the :term:`Build Directory`.
3624
3625 Setting the variable to "1" in a configuration file causes the
3626 OpenEmbedded build system to generate a kernel image with the
Andrew Geissler09036742021-06-25 14:25:14 -05003627 initramfs specified in :term:`INITRAMFS_IMAGE` bundled within::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003628
3629 INITRAMFS_IMAGE_BUNDLE = "1"
3630
3631 By default, the
3632 :ref:`kernel <ref-classes-kernel>` class sets this variable to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05003633 null string as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003634
3635 INITRAMFS_IMAGE_BUNDLE ?= ""
3636
3637 .. note::
3638
Andrew Geissler09036742021-06-25 14:25:14 -05003639 You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003640 configuration file. You cannot set the variable in a recipe file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003641
3642 See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003643 :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003644 file for additional information. Also, for information on creating an
Andrew Geissler09209ee2020-12-13 08:44:15 -06003645 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003646 in the Yocto Project Development Tasks Manual.
3647
Andrew Geisslerf0343792020-11-18 10:42:21 -06003648 :term:`INITRAMFS_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003649 The link name of the initial RAM filesystem image. This variable is
3650 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003651 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003652
3653 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
3654
3655 The value of the
3656 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05003657 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003658
3659 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3660
3661 See the :term:`MACHINE` variable for additional
3662 information.
3663
Andrew Geisslerf0343792020-11-18 10:42:21 -06003664 :term:`INITRAMFS_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003665 The base name of the initial RAM filesystem image. This variable is
3666 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003667 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003668
3669 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
3670
3671 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003672 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003673
3674 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3675
Andrew Geisslerf0343792020-11-18 10:42:21 -06003676 :term:`INITRD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003677 Indicates list of filesystem images to concatenate and use as an
3678 initial RAM disk (``initrd``).
3679
Andrew Geissler09036742021-06-25 14:25:14 -05003680 The :term:`INITRD` variable is an optional variable used with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003681 :ref:`image-live <ref-classes-image-live>` class.
3682
Andrew Geisslerf0343792020-11-18 10:42:21 -06003683 :term:`INITRD_IMAGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003684 When building a "live" bootable image (i.e. when
3685 :term:`IMAGE_FSTYPES` contains "live"),
Andrew Geissler09036742021-06-25 14:25:14 -05003686 :term:`INITRD_IMAGE` specifies the image recipe that should be built to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003687 provide the initial RAM disk image. The default value is
3688 "core-image-minimal-initramfs".
3689
3690 See the :ref:`image-live <ref-classes-image-live>` class for more
3691 information.
3692
Andrew Geisslerf0343792020-11-18 10:42:21 -06003693 :term:`INITSCRIPT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003694 The filename of the initialization script as installed to
3695 ``${sysconfdir}/init.d``.
3696
3697 This variable is used in recipes when using ``update-rc.d.bbclass``.
3698 The variable is mandatory.
3699
Andrew Geisslerf0343792020-11-18 10:42:21 -06003700 :term:`INITSCRIPT_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003701 A list of the packages that contain initscripts. If multiple packages
3702 are specified, you need to append the package name to the other
3703 ``INITSCRIPT_*`` as an override.
3704
3705 This variable is used in recipes when using ``update-rc.d.bbclass``.
3706 The variable is optional and defaults to the :term:`PN`
3707 variable.
3708
Andrew Geisslerf0343792020-11-18 10:42:21 -06003709 :term:`INITSCRIPT_PARAMS`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003710 Specifies the options to pass to ``update-rc.d``. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003711
3712 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3713
3714 In this example, the script has a runlevel of 99, starts the script
3715 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3716
3717 The variable's default value is "defaults", which is set in the
3718 :ref:`update-rc.d <ref-classes-update-rc.d>` class.
3719
Andrew Geissler09036742021-06-25 14:25:14 -05003720 The value in :term:`INITSCRIPT_PARAMS` is passed through to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003721 ``update-rc.d`` command. For more information on valid parameters,
3722 please see the ``update-rc.d`` manual page at
Andrew Geisslerc3d88e42020-10-02 09:45:00 -05003723 https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003724
Andrew Geisslerf0343792020-11-18 10:42:21 -06003725 :term:`INSANE_SKIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003726 Specifies the QA checks to skip for a specific package within a
3727 recipe. For example, to skip the check for symbolic link ``.so``
3728 files in the main package of a recipe, add the following to the
3729 recipe. The package name override must be used, which in this example
Andrew Geisslerc926e172021-05-07 16:11:35 -05003730 is ``${PN}``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003731
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003732 INSANE_SKIP:${PN} += "dev-so"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003733
3734 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a
3735 list of the valid QA checks you can specify using this variable.
3736
Andrew Geisslerf0343792020-11-18 10:42:21 -06003737 :term:`INSTALL_TIMEZONE_FILE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003738 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
Andrew Geissler09036742021-06-25 14:25:14 -05003739 Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003740 configuration level to disable this behavior.
3741
Andrew Geisslerf0343792020-11-18 10:42:21 -06003742 :term:`IPK_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003743 When the IPK backend is in use and package management is enabled on
3744 the target, you can use this variable to set up ``opkg`` in the
3745 target image to point to package feeds on a nominated server. Once
3746 the feed is established, you can perform installations or upgrades
3747 using the package manager at runtime.
3748
Andrew Geisslerf0343792020-11-18 10:42:21 -06003749 :term:`KARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003750 Defines the kernel architecture used when assembling the
3751 configuration. Architectures supported for this release are:
3752
3753 - powerpc
3754 - i386
3755 - x86_64
3756 - arm
3757 - qemu
3758 - mips
3759
Andrew Geissler5f350902021-07-23 13:09:54 -04003760 You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003761
Andrew Geisslerf0343792020-11-18 10:42:21 -06003762 :term:`KBRANCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003763 A regular expression used by the build process to explicitly identify
3764 the kernel branch that is validated, patched, and configured during a
3765 build. You must set this variable to ensure the exact kernel branch
3766 you want is being used by the build process.
3767
3768 Values for this variable are set in the kernel's recipe file and the
3769 kernel's append file. For example, if you are using the
3770 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
Andrew Geissler09036742021-06-25 14:25:14 -05003771 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003772 is set as follows in that kernel recipe file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003773
3774 KBRANCH ?= "standard/base"
3775
3776 This variable is also used from the kernel's append file to identify
3777 the kernel branch specific to a particular machine or target
3778 hardware. Continuing with the previous kernel example, the kernel's
3779 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the
3780 BSP layer for a given machine. For example, the append file for the
3781 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA
3782 machines (``meta-yocto-bsp``) is named
3783 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
Andrew Geisslerc926e172021-05-07 16:11:35 -05003784 Here are the related statements from that append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003785
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003786 KBRANCH:genericx86 = "standard/base"
3787 KBRANCH:genericx86-64 = "standard/base"
3788 KBRANCH:edgerouter = "standard/edgerouter"
3789 KBRANCH:beaglebone = "standard/beaglebone"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003790
Andrew Geissler09036742021-06-25 14:25:14 -05003791 The :term:`KBRANCH` statements
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003792 identify the kernel branch to use when building for each supported
3793 BSP.
3794
Andrew Geisslerf0343792020-11-18 10:42:21 -06003795 :term:`KBUILD_DEFCONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003796 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3797 class, specifies an "in-tree" kernel configuration file for use
3798 during a kernel build.
3799
3800 Typically, when using a ``defconfig`` to configure a kernel during a
3801 build, you place the file in your layer in the same manner as you
3802 would place patch files and configuration fragment files (i.e.
3803 "out-of-tree"). However, if you want to use a ``defconfig`` file that
3804 is part of the kernel tree (i.e. "in-tree"), you can use the
Andrew Geissler09036742021-06-25 14:25:14 -05003805 :term:`KBUILD_DEFCONFIG` variable and append the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003806 :term:`KMACHINE` variable to point to the
3807 ``defconfig`` file.
3808
3809 To use the variable, set it in the append file for your kernel recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05003810 using the following form::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003811
3812 KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
3813
Andrew Geissler09036742021-06-25 14:25:14 -05003814 Here is an example from a "raspberrypi2" :term:`KMACHINE` build that uses
Andrew Geisslerc926e172021-05-07 16:11:35 -05003815 a ``defconfig`` file named "bcm2709_defconfig"::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003816
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003817 KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003818
Andrew Geisslerc926e172021-05-07 16:11:35 -05003819 As an alternative, you can use the following within your append file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003820
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003821 KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003822
3823 For more
Andrew Geissler09036742021-06-25 14:25:14 -05003824 information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06003825 ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003826 section in the Yocto Project Linux Kernel Development Manual.
3827
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003828 :term:`KCONFIG_MODE`
3829 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3830 class, specifies the kernel configuration values to use for options
3831 not specified in the provided ``defconfig`` file. Valid options are::
3832
3833 KCONFIG_MODE = "alldefconfig"
3834 KCONFIG_MODE = "allnoconfig"
3835
3836 In ``alldefconfig`` mode the options not explicitly specified will be
3837 assigned their Kconfig default value. In ``allnoconfig`` mode the
3838 options not explicitly specified will be disabled in the kernel
3839 config.
3840
Andrew Geissler09036742021-06-25 14:25:14 -05003841 In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003842 the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file
3843 will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed
3844 in ``${WORKDIR}`` through a meta-layer will be handled in
3845 ``allnoconfig`` mode.
3846
3847 An "in-tree" ``defconfig`` file can be selected via the
Andrew Geissler09036742021-06-25 14:25:14 -05003848 :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003849 be explicitly set.
3850
3851 A ``defconfig`` file compatible with ``allnoconfig`` mode can be
3852 generated by copying the ``.config`` file from a working Linux kernel
3853 build, renaming it to ``defconfig`` and placing it into the Linux
Andrew Geissler09036742021-06-25 14:25:14 -05003854 kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003855 not need to be explicitly set.
3856
3857 A ``defconfig`` file compatible with ``alldefconfig`` mode can be
3858 generated using the
3859 :ref:`ref-tasks-savedefconfig`
3860 task and placed into the Linux kernel ``${WORKDIR}`` through your
Andrew Geissler09036742021-06-25 14:25:14 -05003861 meta-layer. Explicitely set :term:`KCONFIG_MODE`::
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003862
3863 KCONFIG_MODE = "alldefconfig"
3864
3865
Andrew Geisslerf0343792020-11-18 10:42:21 -06003866 :term:`KERNEL_ALT_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003867 Specifies an alternate kernel image type for creation in addition to
3868 the kernel image type specified using the
3869 :term:`KERNEL_IMAGETYPE` variable.
3870
Andrew Geisslerf0343792020-11-18 10:42:21 -06003871 :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003872 Specifies the name of all of the build artifacts. You can change the
Andrew Geissler09036742021-06-25 14:25:14 -05003873 name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003874 variable.
3875
Andrew Geissler09036742021-06-25 14:25:14 -05003876 The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003877 ``meta/classes/kernel-artifact-names.bbclass`` file, has the
Andrew Geisslerc926e172021-05-07 16:11:35 -05003878 following default value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003879
3880 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3881
Andrew Geissler6ce62a22020-11-30 19:58:47 -06003882 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`MACHINE`
3883 and :term:`IMAGE_VERSION_SUFFIX` variables for additional information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003884
Andrew Geisslerf0343792020-11-18 10:42:21 -06003885 :term:`KERNEL_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003886 A list of classes defining kernel image types that the
3887 :ref:`kernel <ref-classes-kernel>` class should inherit. You
3888 typically append this variable to enable extended image types. An
3889 example is the "kernel-fitimage", which enables fitImage support and
3890 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register
3891 custom kernel image types with the ``kernel`` class using this
3892 variable.
3893
Andrew Geisslerf0343792020-11-18 10:42:21 -06003894 :term:`KERNEL_DEVICETREE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003895 Specifies the name of the generated Linux kernel device tree (i.e.
3896 the ``.dtb``) file.
3897
3898 .. note::
3899
William A. Kennington IIIac69b482021-06-02 12:28:27 -07003900 There is legacy support for specifying the full path to the device
Andrew Geissler4c19ea12020-10-27 13:52:24 -05003901 tree. However, providing just the ``.dtb`` file is preferred.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003902
3903 In order to use this variable, the
3904 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
3905 be inherited.
3906
Andrew Geisslerf0343792020-11-18 10:42:21 -06003907 :term:`KERNEL_DTB_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003908 The link name of the kernel device tree binary (DTB). This variable
3909 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003910 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003911
3912 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3913
3914 The
3915 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05003916 the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003917
3918 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3919
3920 See the :term:`MACHINE` variable for additional
3921 information.
3922
Andrew Geisslerf0343792020-11-18 10:42:21 -06003923 :term:`KERNEL_DTB_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003924 The base name of the kernel device tree binary (DTB). This variable
3925 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
Andrew Geisslerc926e172021-05-07 16:11:35 -05003926 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003927
3928 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3929
3930 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003931 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003932
3933 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3934
Andrew Geisslerd1e89492021-02-12 15:35:20 -06003935 :term:`KERNEL_DTC_FLAGS`
3936 Specifies the ``dtc`` flags that are passed to the Linux kernel build
3937 system when generating the device trees (via ``DTC_FLAGS`` environment
3938 variable).
3939
3940 In order to use this variable, the
3941 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
3942 be inherited.
3943
Andrew Geisslerf0343792020-11-18 10:42:21 -06003944 :term:`KERNEL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003945 Specifies additional ``make`` command-line arguments the OpenEmbedded
3946 build system passes on when compiling the kernel.
3947
Andrew Geisslerf0343792020-11-18 10:42:21 -06003948 :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003949 Includes additional kernel metadata. In the OpenEmbedded build
3950 system, the default Board Support Packages (BSPs)
3951 :term:`Metadata` is provided through the
3952 :term:`KMACHINE` and :term:`KBRANCH`
Andrew Geissler09036742021-06-25 14:25:14 -05003953 variables. You can use the :term:`KERNEL_FEATURES` variable from within
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003954 the kernel recipe or kernel append file to further add metadata for
3955 all BSPs or specific BSPs.
3956
3957 The metadata you add through this variable includes config fragments
3958 and features descriptions, which usually includes patches as well as
Andrew Geissler09036742021-06-25 14:25:14 -05003959 config fragments. You typically override the :term:`KERNEL_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003960 variable for a specific machine. In this way, you can provide
3961 validated, but optional, sets of kernel configurations and features.
3962
3963 For example, the following example from the ``linux-yocto-rt_4.12``
3964 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
3965 as well as "virtio" configurations to all QEMU machines. The last two
Andrew Geisslerc926e172021-05-07 16:11:35 -05003966 statements add specific configurations to targeted machine types::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003967
3968 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05003969 KERNEL_FEATURES:append = "${KERNEL_EXTRA_FEATURES}"
3970 KERNEL_FEATURES:append:qemuall = "cfg/virtio.scc"
3971 KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
3972 KERNEL_FEATURES:append:qemux86-64 = "cfg/sound.scc"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003973
Andrew Geisslerf0343792020-11-18 10:42:21 -06003974 :term:`KERNEL_FIT_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003975 The link name of the kernel flattened image tree (FIT) image. This
3976 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05003977 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003978
3979 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3980
3981 The value of the
3982 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05003983 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003984
3985 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3986
3987 See the :term:`MACHINE` variable for additional
3988 information.
3989
Andrew Geisslerf0343792020-11-18 10:42:21 -06003990 :term:`KERNEL_FIT_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003991 The base name of the kernel flattened image tree (FIT) image. This
3992 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
Andrew Geisslerc926e172021-05-07 16:11:35 -05003993 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003994
3995 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3996
3997 The value of the :term:`KERNEL_ARTIFACT_NAME`
Andrew Geisslerc926e172021-05-07 16:11:35 -05003998 variable, which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05003999
4000 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4001
Andrew Geisslerf0343792020-11-18 10:42:21 -06004002 :term:`KERNEL_IMAGE_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004003 The link name for the kernel image. This variable is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004004 ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004005
4006 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4007
4008 The value of
4009 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
Andrew Geisslerc926e172021-05-07 16:11:35 -05004010 file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004011
4012 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4013
4014 See the :term:`MACHINE` variable for additional
4015 information.
4016
Andrew Geisslerf0343792020-11-18 10:42:21 -06004017 :term:`KERNEL_IMAGE_MAXSIZE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004018 Specifies the maximum size of the kernel image file in kilobytes. If
Andrew Geissler09036742021-06-25 14:25:14 -05004019 :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004020 checked against the set value during the
4021 :ref:`ref-tasks-sizecheck` task. The task fails if
4022 the kernel image file is larger than the setting.
4023
Andrew Geissler09036742021-06-25 14:25:14 -05004024 :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004025 limited amount of space in which the kernel image must be stored.
4026
4027 By default, this variable is not set, which means the size of the
4028 kernel image is not checked.
4029
Andrew Geisslerf0343792020-11-18 10:42:21 -06004030 :term:`KERNEL_IMAGE_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004031 The base name of the kernel image. This variable is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004032 ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004033
4034 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4035
4036 The value of the
4037 :term:`KERNEL_ARTIFACT_NAME` variable,
Andrew Geisslerc926e172021-05-07 16:11:35 -05004038 which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004039
4040 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4041
Andrew Geisslerf0343792020-11-18 10:42:21 -06004042 :term:`KERNEL_IMAGETYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004043 The type of kernel to build for a device, usually set by the machine
4044 configuration files and defaults to "zImage". This variable is used
4045 when building the kernel and is passed to ``make`` as the target to
4046 build.
4047
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004048 If you want to build an alternate kernel image type in addition to that
Andrew Geissler09036742021-06-25 14:25:14 -05004049 specified by :term:`KERNEL_IMAGETYPE`, use the :term:`KERNEL_ALT_IMAGETYPE`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004050 variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004051
Andrew Geisslerf0343792020-11-18 10:42:21 -06004052 :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004053 Lists kernel modules that need to be auto-loaded during boot.
4054
4055 .. note::
4056
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004057 This variable replaces the deprecated :term:`module_autoload`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004058 variable.
4059
Andrew Geissler09036742021-06-25 14:25:14 -05004060 You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004061 can be recognized by the kernel recipe or by an out-of-tree kernel
4062 module recipe (e.g. a machine configuration file, a distribution
4063 configuration file, an append file for the recipe, or the recipe
4064 itself).
4065
Andrew Geisslerc926e172021-05-07 16:11:35 -05004066 Specify it as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004067
4068 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
4069
Andrew Geissler09036742021-06-25 14:25:14 -05004070 Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004071 system to populate the ``/etc/modules-load.d/modname.conf`` file with
4072 the list of modules to be auto-loaded on boot. The modules appear
4073 one-per-line in the file. Here is an example of the most common use
Andrew Geisslerc926e172021-05-07 16:11:35 -05004074 case::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004075
4076 KERNEL_MODULE_AUTOLOAD += "module_name"
4077
4078 For information on how to populate the ``modname.conf`` file with
4079 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable.
4080
Andrew Geisslerf0343792020-11-18 10:42:21 -06004081 :term:`KERNEL_MODULE_PROBECONF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004082 Provides a list of modules for which the OpenEmbedded build system
4083 expects to find ``module_conf_``\ modname values that specify
4084 configuration for each of the modules. For information on how to
4085 provide those module configurations, see the
4086 :term:`module_conf_* <module_conf>` variable.
4087
Andrew Geisslerf0343792020-11-18 10:42:21 -06004088 :term:`KERNEL_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004089 The location of the kernel sources. This variable is set to the value
4090 of the :term:`STAGING_KERNEL_DIR` within
4091 the :ref:`module <ref-classes-module>` class. For information on
4092 how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004093 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004094 section in the Yocto Project Linux Kernel Development Manual.
4095
4096 To help maximize compatibility with out-of-tree drivers used to build
4097 modules, the OpenEmbedded build system also recognizes and uses the
4098 :term:`KERNEL_SRC` variable, which is identical to
Andrew Geissler09036742021-06-25 14:25:14 -05004099 the :term:`KERNEL_PATH` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004100 used by external Makefiles to point to the kernel source directory.
4101
Andrew Geisslerf0343792020-11-18 10:42:21 -06004102 :term:`KERNEL_SRC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004103 The location of the kernel sources. This variable is set to the value
4104 of the :term:`STAGING_KERNEL_DIR` within
4105 the :ref:`module <ref-classes-module>` class. For information on
4106 how this variable is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004107 ":ref:`kernel-dev/common:incorporating out-of-tree modules`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004108 section in the Yocto Project Linux Kernel Development Manual.
4109
4110 To help maximize compatibility with out-of-tree drivers used to build
4111 modules, the OpenEmbedded build system also recognizes and uses the
4112 :term:`KERNEL_PATH` variable, which is identical
Andrew Geissler09036742021-06-25 14:25:14 -05004113 to the :term:`KERNEL_SRC` variable. Both variables are common variables
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004114 used by external Makefiles to point to the kernel source directory.
4115
Andrew Geisslerf0343792020-11-18 10:42:21 -06004116 :term:`KERNEL_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004117 Specifies the version of the kernel as extracted from ``version.h``
4118 or ``utsrelease.h`` within the kernel sources. Effects of setting
4119 this variable do not take affect until the kernel has been
4120 configured. Consequently, attempting to refer to this variable in
4121 contexts prior to configuration will not work.
4122
Andrew Geisslerf0343792020-11-18 10:42:21 -06004123 :term:`KERNELDEPMODDEPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004124 Specifies whether the data referenced through
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004125 :term:`PKGDATA_DIR` is needed or not.
Andrew Geissler09036742021-06-25 14:25:14 -05004126 :term:`KERNELDEPMODDEPEND` does not control whether or not that data
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004127 exists, but simply whether or not it is used. If you do not need to
Andrew Geissler09036742021-06-25 14:25:14 -05004128 use the data, set the :term:`KERNELDEPMODDEPEND` variable in your
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004129 ``initramfs`` recipe. Setting the variable there when the data is not
4130 needed avoids a potential dependency loop.
4131
Andrew Geisslerf0343792020-11-18 10:42:21 -06004132 :term:`KFEATURE_DESCRIPTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004133 Provides a short description of a configuration fragment. You use
4134 this variable in the ``.scc`` file that describes a configuration
4135 fragment file. Here is the variable used in a file named ``smp.scc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004136 to describe SMP being enabled::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004137
4138 define KFEATURE_DESCRIPTION "Enable SMP"
4139
Andrew Geisslerf0343792020-11-18 10:42:21 -06004140 :term:`KMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004141 The machine as known by the kernel. Sometimes the machine name used
4142 by the kernel does not match the machine name used by the
4143 OpenEmbedded build system. For example, the machine name that the
4144 OpenEmbedded build system understands as ``core2-32-intel-common``
4145 goes by a different name in the Linux Yocto kernel. The kernel
4146 understands that machine as ``intel-core2-32``. For cases like these,
Andrew Geissler09036742021-06-25 14:25:14 -05004147 the :term:`KMACHINE` variable maps the kernel machine name to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004148 OpenEmbedded build system machine name.
4149
4150 These mappings between different names occur in the Yocto Linux
4151 Kernel's ``meta`` branch. As an example take a look in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004152 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004153
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004154 LINUX_VERSION:core2-32-intel-common = "3.19.0"
4155 COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}"
4156 SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
4157 SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
4158 KMACHINE:core2-32-intel-common = "intel-core2-32"
4159 KBRANCH:core2-32-intel-common = "standard/base"
4160 KERNEL_FEATURES:append:core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004161
Andrew Geissler09036742021-06-25 14:25:14 -05004162 The :term:`KMACHINE` statement says
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004163 that the kernel understands the machine name as "intel-core2-32".
4164 However, the OpenEmbedded build system understands the machine as
4165 "core2-32-intel-common".
4166
Andrew Geisslerf0343792020-11-18 10:42:21 -06004167 :term:`KTYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004168 Defines the kernel type to be used in assembling the configuration.
4169 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06004170 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004171 section in the
4172 Yocto Project Linux Kernel Development Manual for more information on
4173 kernel types.
4174
Andrew Geissler09036742021-06-25 14:25:14 -05004175 You define the :term:`KTYPE` variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004176 :ref:`kernel-dev/advanced:bsp descriptions`. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004177 value you use must match the value used for the
4178 :term:`LINUX_KERNEL_TYPE` value used by the
4179 kernel recipe.
4180
Andrew Geisslerf0343792020-11-18 10:42:21 -06004181 :term:`LABELS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004182 Provides a list of targets for automatic configuration.
4183
4184 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
4185 information on how this variable is used.
4186
Andrew Geisslerf0343792020-11-18 10:42:21 -06004187 :term:`LAYERDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004188 Lists the layers, separated by spaces, on which this recipe depends.
4189 Optionally, you can specify a specific layer version for a dependency
Andrew Geisslerc926e172021-05-07 16:11:35 -05004190 by adding it to the end of the layer name. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004191
4192 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4193
4194 In this previous example,
4195 version 3 of "anotherlayer" is compared against
4196 :term:`LAYERVERSION`\ ``_anotherlayer``.
4197
4198 An error is produced if any dependency is missing or the version
4199 numbers (if specified) do not match exactly. This variable is used in
4200 the ``conf/layer.conf`` file and must be suffixed with the name of
4201 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
4202
Andrew Geisslerf0343792020-11-18 10:42:21 -06004203 :term:`LAYERDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004204 When used inside the ``layer.conf`` configuration file, this variable
4205 provides the path of the current layer. This variable is not
4206 available outside of ``layer.conf`` and references are expanded
4207 immediately when parsing of the file completes.
4208
Andrew Geisslerf0343792020-11-18 10:42:21 -06004209 :term:`LAYERRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004210 Lists the layers, separated by spaces, recommended for use with this
4211 layer.
4212
4213 Optionally, you can specify a specific layer version for a
4214 recommendation by adding the version to the end of the layer name.
Andrew Geisslerc926e172021-05-07 16:11:35 -05004215 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004216
4217 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
4218
4219 In this previous example, version 3 of "anotherlayer" is compared
4220 against ``LAYERVERSION_anotherlayer``.
4221
4222 This variable is used in the ``conf/layer.conf`` file and must be
4223 suffixed with the name of the specific layer (e.g.
4224 ``LAYERRECOMMENDS_mylayer``).
4225
Andrew Geisslerf0343792020-11-18 10:42:21 -06004226 :term:`LAYERSERIES_COMPAT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004227 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which
Andrew Geissler09036742021-06-25 14:25:14 -05004228 a layer is compatible. Using the :term:`LAYERSERIES_COMPAT` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004229 allows the layer maintainer to indicate which combinations of the
4230 layer and OE-Core can be expected to work. The variable gives the
4231 system a way to detect when a layer has not been tested with new
4232 releases of OE-Core (e.g. the layer is not maintained).
4233
4234 To specify the OE-Core versions for which a layer is compatible, use
4235 this variable in your layer's ``conf/layer.conf`` configuration file.
4236 For the list, use the Yocto Project
Andrew Geissler09209ee2020-12-13 08:44:15 -06004237 :yocto_wiki:`Release Name </Releases>` (e.g.
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004238 &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004239 layer, use a space-separated list::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004240
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004241 LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004242
4243 .. note::
4244
Andrew Geissler09036742021-06-25 14:25:14 -05004245 Setting :term:`LAYERSERIES_COMPAT` is required by the Yocto Project
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004246 Compatible version 2 standard.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004247 The OpenEmbedded build system produces a warning if the variable
4248 is not set for any given layer.
4249
Andrew Geissler09209ee2020-12-13 08:44:15 -06004250 See the ":ref:`dev-manual/common-tasks:creating your own layer`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004251 section in the Yocto Project Development Tasks Manual.
4252
Andrew Geisslerf0343792020-11-18 10:42:21 -06004253 :term:`LAYERVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004254 Optionally specifies the version of a layer as a single number. You
4255 can use this within :term:`LAYERDEPENDS` for
4256 another layer in order to depend on a specific version of the layer.
4257 This variable is used in the ``conf/layer.conf`` file and must be
4258 suffixed with the name of the specific layer (e.g.
4259 ``LAYERVERSION_mylayer``).
4260
Andrew Geisslerf0343792020-11-18 10:42:21 -06004261 :term:`LD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004262 The minimal command and arguments used to run the linker.
4263
Andrew Geisslerf0343792020-11-18 10:42:21 -06004264 :term:`LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004265 Specifies the flags to pass to the linker. This variable is exported
4266 to an environment variable and thus made visible to the software
4267 being built during the compilation step.
4268
Andrew Geissler09036742021-06-25 14:25:14 -05004269 Default initialization for :term:`LDFLAGS` varies depending on what is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004270 being built:
4271
4272 - :term:`TARGET_LDFLAGS` when building for the
4273 target
4274
4275 - :term:`BUILD_LDFLAGS` when building for the
4276 build host (i.e. ``-native``)
4277
4278 - :term:`BUILDSDK_LDFLAGS` when building for
4279 an SDK (i.e. ``nativesdk-``)
4280
Andrew Geisslerf0343792020-11-18 10:42:21 -06004281 :term:`LEAD_SONAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004282 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
4283 that the :ref:`debian <ref-classes-debian>` class applies its
4284 naming policy to given a recipe that packages multiple libraries.
4285
4286 This variable works in conjunction with the ``debian`` class.
4287
Andrew Geisslerf0343792020-11-18 10:42:21 -06004288 :term:`LIC_FILES_CHKSUM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004289 Checksums of the license text in the recipe source code.
4290
4291 This variable tracks changes in license text of the source code
4292 files. If the license text is changed, it will trigger a build
4293 failure, which gives the developer an opportunity to review any
4294 license change.
4295
4296 This variable must be defined for all recipes (unless
4297 :term:`LICENSE` is set to "CLOSED").
4298
Andrew Geissler09209ee2020-12-13 08:44:15 -06004299 For more information, see the ":ref:`dev-manual/common-tasks:tracking license changes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004300 section in the Yocto Project Development Tasks Manual.
4301
Andrew Geisslerf0343792020-11-18 10:42:21 -06004302 :term:`LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004303 The list of source licenses for the recipe. Follow these rules:
4304
4305 - Do not use spaces within individual license names.
4306
4307 - Separate license names using \| (pipe) when there is a choice
4308 between licenses.
4309
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004310 - Separate license names using & (ampersand) when there are
4311 multiple licenses for different parts of the source.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004312
4313 - You can use spaces between license names.
4314
4315 - For standard licenses, use the names of the files in
4316 ``meta/files/common-licenses/`` or the
4317 :term:`SPDXLICENSEMAP` flag names defined in
4318 ``meta/conf/licenses.conf``.
4319
Andrew Geisslerc926e172021-05-07 16:11:35 -05004320 Here are some examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004321
4322 LICENSE = "LGPLv2.1 | GPLv3"
4323 LICENSE = "MPL-1 & LGPLv2.1"
4324 LICENSE = "GPLv2+"
4325
4326 The first example is from the
4327 recipes for Qt, which the user may choose to distribute under either
4328 the LGPL version 2.1 or GPL version 3. The second example is from
4329 Cairo where two licenses cover different parts of the source code.
4330 The final example is from ``sysstat``, which presents a single
4331 license.
4332
4333 You can also specify licenses on a per-package basis to handle
4334 situations where components of the output have different licenses.
4335 For example, a piece of software whose code is licensed under GPLv2
4336 but has accompanying documentation licensed under the GNU Free
Andrew Geisslerc926e172021-05-07 16:11:35 -05004337 Documentation License 1.2 could be specified as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004338
4339 LICENSE = "GFDL-1.2 & GPLv2"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004340 LICENSE:${PN} = "GPLv2"
4341 LICENSE:${PN}-doc = "GFDL-1.2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004342
Andrew Geisslerf0343792020-11-18 10:42:21 -06004343 :term:`LICENSE_CREATE_PACKAGE`
Andrew Geissler09036742021-06-25 14:25:14 -05004344 Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004345 build system to create an extra package (i.e.
4346 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
4347 those packages to the
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004348 :term:`RRECOMMENDS`\ ``:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004349
4350 The ``${PN}-lic`` package installs a directory in
4351 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
4352 name, and installs files in that directory that contain license and
4353 copyright information (i.e. copies of the appropriate license files
4354 from ``meta/common-licenses`` that match the licenses specified in
4355 the :term:`LICENSE` variable of the recipe metadata
4356 and copies of files marked in
4357 :term:`LIC_FILES_CHKSUM` as containing
4358 license text).
4359
4360 For related information on providing license text, see the
4361 :term:`COPY_LIC_DIRS` variable, the
4362 :term:`COPY_LIC_MANIFEST` variable, and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004363 ":ref:`dev-manual/common-tasks:providing license text`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004364 section in the Yocto Project Development Tasks Manual.
4365
Andrew Geisslerf0343792020-11-18 10:42:21 -06004366 :term:`LICENSE_FLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004367 Specifies additional flags for a recipe you must whitelist through
4368 :term:`LICENSE_FLAGS_WHITELIST` in
4369 order to allow the recipe to be built. When providing multiple flags,
4370 separate them with spaces.
4371
4372 This value is independent of :term:`LICENSE` and is
4373 typically used to mark recipes that might require additional licenses
4374 in order to be used in a commercial product. For more information,
4375 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004376 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004377 section in the Yocto Project Development Tasks Manual.
4378
Andrew Geisslerf0343792020-11-18 10:42:21 -06004379 :term:`LICENSE_FLAGS_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004380 Lists license flags that when specified in
4381 :term:`LICENSE_FLAGS` within a recipe should not
4382 prevent that recipe from being built. This practice is otherwise
4383 known as "whitelisting" license flags. For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06004384 ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004385 section in the Yocto Project Development Tasks Manual.
4386
Andrew Geisslerf0343792020-11-18 10:42:21 -06004387 :term:`LICENSE_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004388 Path to additional licenses used during the build. By default, the
Andrew Geissler09036742021-06-25 14:25:14 -05004389 OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004390 directory that holds common license text used during the build. The
Andrew Geissler09036742021-06-25 14:25:14 -05004391 :term:`LICENSE_PATH` variable allows you to extend that location to other
Andrew Geisslerc926e172021-05-07 16:11:35 -05004392 areas that have additional licenses::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004393
4394 LICENSE_PATH += "path-to-additional-common-licenses"
4395
Andrew Geisslerf0343792020-11-18 10:42:21 -06004396 :term:`LINUX_KERNEL_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004397 Defines the kernel type to be used in assembling the configuration.
4398 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
Andrew Geissler09209ee2020-12-13 08:44:15 -06004399 kernel types. See the ":ref:`kernel-dev/advanced:kernel types`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004400 section in the
4401 Yocto Project Linux Kernel Development Manual for more information on
4402 kernel types.
4403
Andrew Geissler09036742021-06-25 14:25:14 -05004404 If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004405 "standard". Together with :term:`KMACHINE`, the
Andrew Geissler09036742021-06-25 14:25:14 -05004406 :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004407 the kernel tools to find the appropriate description within the
4408 kernel :term:`Metadata` with which to build out the sources
4409 and configuration.
4410
Andrew Geisslerf0343792020-11-18 10:42:21 -06004411 :term:`LINUX_VERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004412 The Linux version from ``kernel.org`` on which the Linux kernel image
4413 being built using the OpenEmbedded build system is based. You define
4414 this variable in the kernel recipe. For example, the
4415 ``linux-yocto-3.4.bb`` kernel recipe found in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004416 ``meta/recipes-kernel/linux`` defines the variables as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004417
4418 LINUX_VERSION ?= "3.4.24"
4419
Andrew Geissler09036742021-06-25 14:25:14 -05004420 The :term:`LINUX_VERSION` variable is used to define :term:`PV`
Andrew Geisslerc926e172021-05-07 16:11:35 -05004421 for the recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004422
4423 PV = "${LINUX_VERSION}+git${SRCPV}"
4424
Andrew Geisslerf0343792020-11-18 10:42:21 -06004425 :term:`LINUX_VERSION_EXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004426 A string extension compiled into the version string of the Linux
4427 kernel built with the OpenEmbedded build system. You define this
4428 variable in the kernel recipe. For example, the linux-yocto kernel
Andrew Geisslerc926e172021-05-07 16:11:35 -05004429 recipes all define the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004430
4431 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
4432
4433 Defining this variable essentially sets the Linux kernel
4434 configuration item ``CONFIG_LOCALVERSION``, which is visible through
4435 the ``uname`` command. Here is an example that shows the extension
Andrew Geisslerc926e172021-05-07 16:11:35 -05004436 assuming it was set as previously shown::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004437
4438 $ uname -r
4439 3.7.0-rc8-custom
4440
Andrew Geisslerf0343792020-11-18 10:42:21 -06004441 :term:`LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004442 Specifies the directory to which the OpenEmbedded build system writes
4443 overall log files. The default directory is ``${TMPDIR}/log``.
4444
4445 For the directory containing logs specific to each task, see the
4446 :term:`T` variable.
4447
Andrew Geisslerf0343792020-11-18 10:42:21 -06004448 :term:`MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004449 Specifies the target device for which the image is built. You define
Andrew Geissler09036742021-06-25 14:25:14 -05004450 :term:`MACHINE` in the ``local.conf`` file found in the
4451 :term:`Build Directory`. By default, :term:`MACHINE` is set to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004452 "qemux86", which is an x86-based architecture machine to be emulated
Andrew Geisslerc926e172021-05-07 16:11:35 -05004453 using QEMU::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004454
4455 MACHINE ?= "qemux86"
4456
4457 The variable corresponds to a machine configuration file of the same
4458 name, through which machine-specific configurations are set. Thus,
Andrew Geissler09036742021-06-25 14:25:14 -05004459 when :term:`MACHINE` is set to "qemux86", the corresponding
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004460 ``qemux86.conf`` machine configuration file can be found in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004461 the :term:`Source Directory` in
4462 ``meta/conf/machine``.
4463
4464 The list of machines supported by the Yocto Project as shipped
Andrew Geisslerc926e172021-05-07 16:11:35 -05004465 include the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004466
4467 MACHINE ?= "qemuarm"
4468 MACHINE ?= "qemuarm64"
4469 MACHINE ?= "qemumips"
4470 MACHINE ?= "qemumips64"
4471 MACHINE ?= "qemuppc"
4472 MACHINE ?= "qemux86"
4473 MACHINE ?= "qemux86-64"
4474 MACHINE ?= "genericx86"
4475 MACHINE ?= "genericx86-64"
4476 MACHINE ?= "beaglebone"
4477 MACHINE ?= "edgerouter"
4478
4479 The last five are Yocto Project reference hardware
4480 boards, which are provided in the ``meta-yocto-bsp`` layer.
4481
4482 .. note::
4483
4484 Adding additional Board Support Package (BSP) layers to your
Andrew Geissler09036742021-06-25 14:25:14 -05004485 configuration adds new possible settings for :term:`MACHINE`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004486
Andrew Geisslerf0343792020-11-18 10:42:21 -06004487 :term:`MACHINE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004488 Specifies the name of the machine-specific architecture. This
4489 variable is set automatically from :term:`MACHINE` or
4490 :term:`TUNE_PKGARCH`. You should not hand-edit
Andrew Geissler09036742021-06-25 14:25:14 -05004491 the :term:`MACHINE_ARCH` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004492
Andrew Geisslerf0343792020-11-18 10:42:21 -06004493 :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004494 A list of required machine-specific packages to install as part of
4495 the image being built. The build process depends on these packages
4496 being present. Furthermore, because this is a "machine-essential"
4497 variable, the list of packages are essential for the machine to boot.
4498 The impact of this variable affects images based on
4499 ``packagegroup-core-boot``, including the ``core-image-minimal``
4500 image.
4501
4502 This variable is similar to the
Andrew Geissler09036742021-06-25 14:25:14 -05004503 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004504 that the image being built has a build dependency on the variable's
4505 list of packages. In other words, the image will not build if a file
4506 in this list is not found.
4507
4508 As an example, suppose the machine for which you are building
4509 requires ``example-init`` to be run during boot to initialize the
4510 hardware. In this case, you would use the following in the machine's
Andrew Geisslerc926e172021-05-07 16:11:35 -05004511 ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004512
4513 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4514
Andrew Geisslerf0343792020-11-18 10:42:21 -06004515 :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004516 A list of recommended machine-specific packages to install as part of
4517 the image being built. The build process does not depend on these
4518 packages being present. However, because this is a
4519 "machine-essential" variable, the list of packages are essential for
4520 the machine to boot. The impact of this variable affects images based
4521 on ``packagegroup-core-boot``, including the ``core-image-minimal``
4522 image.
4523
Andrew Geissler09036742021-06-25 14:25:14 -05004524 This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004525 variable with the exception that the image being built does not have
4526 a build dependency on the variable's list of packages. In other
4527 words, the image will still build if a package in this list is not
4528 found. Typically, this variable is used to handle essential kernel
4529 modules, whose functionality may be selected to be built into the
4530 kernel rather than as a module, in which case a package will not be
4531 produced.
4532
4533 Consider an example where you have a custom kernel where a specific
4534 touchscreen driver is required for the machine to be usable. However,
4535 the driver can be built as a module or into the kernel depending on
4536 the kernel configuration. If the driver is built as a module, you
4537 want it to be installed. But, when the driver is built into the
4538 kernel, you still want the build to succeed. This variable sets up a
4539 "recommends" relationship so that in the latter case, the build will
4540 not fail due to the missing package. To accomplish this, assuming the
4541 package for the module was called ``kernel-module-ab123``, you would
Andrew Geisslerc926e172021-05-07 16:11:35 -05004542 use the following in the machine's ``.conf`` configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004543
4544 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4545
4546 .. note::
4547
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004548 In this example, the ``kernel-module-ab123`` recipe needs to
4549 explicitly set its :term:`PACKAGES` variable to ensure that BitBake
4550 does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to
4551 satisfy the dependency.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004552
4553 Some examples of these machine essentials are flash, screen,
4554 keyboard, mouse, or touchscreen drivers (depending on the machine).
4555
Andrew Geisslerf0343792020-11-18 10:42:21 -06004556 :term:`MACHINE_EXTRA_RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004557 A list of machine-specific packages to install as part of the image
4558 being built that are not essential for the machine to boot. However,
4559 the build process for more fully-featured images depends on the
4560 packages being present.
4561
4562 This variable affects all images based on ``packagegroup-base``,
4563 which does not include the ``core-image-minimal`` or
4564 ``core-image-full-cmdline`` images.
4565
Andrew Geissler09036742021-06-25 14:25:14 -05004566 The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004567 with the exception that the image being built has a build dependency
4568 on the variable's list of packages. In other words, the image will
4569 not build if a file in this list is not found.
4570
4571 An example is a machine that has WiFi capability but is not essential
4572 for the machine to boot the image. However, if you are building a
4573 more fully-featured image, you want to enable the WiFi. The package
4574 containing the firmware for the WiFi hardware is always expected to
4575 exist, so it is acceptable for the build process to depend upon
4576 finding the package. In this case, assuming the package for the
4577 firmware was called ``wifidriver-firmware``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004578 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004579
4580 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4581
Andrew Geisslerf0343792020-11-18 10:42:21 -06004582 :term:`MACHINE_EXTRA_RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004583 A list of machine-specific packages to install as part of the image
4584 being built that are not essential for booting the machine. The image
4585 being built has no build dependency on this list of packages.
4586
4587 This variable affects only images based on ``packagegroup-base``,
4588 which does not include the ``core-image-minimal`` or
4589 ``core-image-full-cmdline`` images.
4590
Andrew Geissler09036742021-06-25 14:25:14 -05004591 This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004592 with the exception that the image being built does not have a build
4593 dependency on the variable's list of packages. In other words, the
4594 image will build if a file in this list is not found.
4595
4596 An example is a machine that has WiFi capability but is not essential
4597 For the machine to boot the image. However, if you are building a
4598 more fully-featured image, you want to enable WiFi. In this case, the
4599 package containing the WiFi kernel module will not be produced if the
4600 WiFi driver is built into the kernel, in which case you still want
4601 the build to succeed instead of failing as a result of the package
4602 not being found. To accomplish this, assuming the package for the
4603 module was called ``kernel-module-examplewifi``, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004604 following in the ``.conf`` file for the machine::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004605
4606 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4607
Andrew Geisslerf0343792020-11-18 10:42:21 -06004608 :term:`MACHINE_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004609 Specifies the list of hardware features the
4610 :term:`MACHINE` is capable of supporting. For related
4611 information on enabling features, see the
4612 :term:`DISTRO_FEATURES`,
4613 :term:`COMBINED_FEATURES`, and
4614 :term:`IMAGE_FEATURES` variables.
4615
4616 For a list of hardware features supported by the Yocto Project as
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004617 shipped, see the ":ref:`ref-features-machine`" section.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004618
Andrew Geisslerf0343792020-11-18 10:42:21 -06004619 :term:`MACHINE_FEATURES_BACKFILL`
Andrew Geissler09036742021-06-25 14:25:14 -05004620 Features to be added to :term:`MACHINE_FEATURES` if not also present in
4621 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004622
4623 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
4624 not intended to be user-configurable. It is best to just reference
4625 the variable to see which machine features are being backfilled for
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004626 all machine configurations. See the ":ref:`ref-features-backfill`"
4627 section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004628
Andrew Geisslerf0343792020-11-18 10:42:21 -06004629 :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`
Andrew Geissler09036742021-06-25 14:25:14 -05004630 Features from :term:`MACHINE_FEATURES_BACKFILL` that should not be
4631 backfilled (i.e. added to :term:`MACHINE_FEATURES`) during the build. See
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004632 the ":ref:`ref-features-backfill`" section for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004633
Andrew Geisslerf0343792020-11-18 10:42:21 -06004634 :term:`MACHINEOVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004635 A colon-separated list of overrides that apply to the current
4636 machine. By default, this list includes the value of
4637 :term:`MACHINE`.
4638
Andrew Geissler09036742021-06-25 14:25:14 -05004639 You can extend :term:`MACHINEOVERRIDES` to add extra overrides that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004640 should apply to a machine. For example, all machines emulated in QEMU
4641 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
4642 ``meta/conf/machine/include/qemu.inc`` that prepends the following
Andrew Geissler09036742021-06-25 14:25:14 -05004643 override to :term:`MACHINEOVERRIDES`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004644
4645 MACHINEOVERRIDES =. "qemuall:"
4646
4647 This
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004648 override allows variables to be overridden for all machines emulated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004649 in QEMU, like in the following example from the ``connman-conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05004650 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004651
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004652 SRC_URI:append:qemuall = " file://wired.config \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004653 file://wired-setup \
4654 "
4655
4656 The underlying mechanism behind
Andrew Geissler09036742021-06-25 14:25:14 -05004657 :term:`MACHINEOVERRIDES` is simply that it is included in the default
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004658 value of :term:`OVERRIDES`.
4659
Andrew Geisslerf0343792020-11-18 10:42:21 -06004660 :term:`MAINTAINER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004661 The email address of the distribution maintainer.
4662
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05004663 :term:`METADATA_BRANCH`
4664 The branch currently checked out for the OpenEmbedded-Core layer (path
4665 determined by :term:`COREBASE`).
4666
4667 :term:`METADATA_REVISION`
4668 The revision currently checked out for the OpenEmbedded-Core layer (path
4669 determined by :term:`COREBASE`).
4670
Andrew Geisslerf0343792020-11-18 10:42:21 -06004671 :term:`MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004672 Specifies additional paths from which the OpenEmbedded build system
4673 gets source code. When the build system searches for source code, it
4674 first tries the local download directory. If that location fails, the
4675 build system tries locations defined by
4676 :term:`PREMIRRORS`, the upstream source, and then
Andrew Geissler09036742021-06-25 14:25:14 -05004677 locations specified by :term:`MIRRORS` in that order.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004678
4679 Assuming your distribution (:term:`DISTRO`) is "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05004680 the default value for :term:`MIRRORS` is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004681 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
4682
Andrew Geisslerf0343792020-11-18 10:42:21 -06004683 :term:`MLPREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004684 Specifies a prefix has been added to :term:`PN` to create a
4685 special version of a recipe or package (i.e. a Multilib version). The
4686 variable is used in places where the prefix needs to be added to or
4687 removed from a the name (e.g. the :term:`BPN` variable).
Andrew Geissler09036742021-06-25 14:25:14 -05004688 :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004689
4690 .. note::
4691
Andrew Geissler09036742021-06-25 14:25:14 -05004692 The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation is
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004693 historical and comes from a time when ``nativesdk`` was a suffix
4694 rather than a prefix on the recipe name. When ``nativesdk`` was turned
Andrew Geissler09036742021-06-25 14:25:14 -05004695 into a prefix, it made sense to set :term:`MLPREFIX` for it as well.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004696
Andrew Geissler09036742021-06-25 14:25:14 -05004697 To help understand when :term:`MLPREFIX` might be needed, consider when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004698 :term:`BBCLASSEXTEND` is used to provide a
4699 ``nativesdk`` version of a recipe in addition to the target version.
4700 If that recipe declares build-time dependencies on tasks in other
4701 recipes by using :term:`DEPENDS`, then a dependency on
4702 "foo" will automatically get rewritten to a dependency on
4703 "nativesdk-foo". However, dependencies like the following will not
Andrew Geisslerc926e172021-05-07 16:11:35 -05004704 get rewritten automatically::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004705
4706 do_foo[depends] += "recipe:do_foo"
4707
4708 If you want such a dependency to also get transformed, you can do the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004709 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004710
4711 do_foo[depends] += "${MLPREFIX}recipe:do_foo"
4712
Andrew Geissler09036742021-06-25 14:25:14 -05004713 :term:`module_autoload`
4714 This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD`
Andrew Geissler5f350902021-07-23 13:09:54 -04004715 variable. You should replace all occurrences of :term:`module_autoload`
Andrew Geissler09036742021-06-25 14:25:14 -05004716 with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004717
4718 module_autoload_rfcomm = "rfcomm"
4719
Andrew Geisslerc926e172021-05-07 16:11:35 -05004720 should now be replaced with::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004721
4722 KERNEL_MODULE_AUTOLOAD += "rfcomm"
4723
4724 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
4725
Andrew Geissler09036742021-06-25 14:25:14 -05004726 :term:`module_conf`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06004727 Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004728 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
4729 file.
4730
4731 You can use this variable anywhere that it can be recognized by the
4732 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
4733 configuration file, a distribution configuration file, an append file
4734 for the recipe, or the recipe itself). If you use this variable, you
4735 must also be sure to list the module name in the
4736 :term:`KERNEL_MODULE_AUTOLOAD`
4737 variable.
4738
Andrew Geisslerc926e172021-05-07 16:11:35 -05004739 Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004740
4741 module_conf_module_name = "modprobe.d-syntax"
4742
4743 You must use the kernel module name override.
4744
4745 Run ``man modprobe.d`` in the shell to find out more information on
Andrew Geissler5f350902021-07-23 13:09:54 -04004746 the exact syntax you want to provide with :term:`module_conf`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004747
Andrew Geissler5f350902021-07-23 13:09:54 -04004748 Including :term:`module_conf` causes the OpenEmbedded build system to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004749 populate the ``/etc/modprobe.d/modname.conf`` file with
4750 ``modprobe.d`` syntax lines. Here is an example that adds the options
Andrew Geisslerc926e172021-05-07 16:11:35 -05004751 ``arg1`` and ``arg2`` to a module named ``mymodule``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004752
4753 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
4754
4755 For information on how to specify kernel modules to auto-load on
4756 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable.
4757
Andrew Geisslerf0343792020-11-18 10:42:21 -06004758 :term:`MODULE_TARBALL_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004759 Controls creation of the ``modules-*.tgz`` file. Set this variable to
4760 "0" to disable creation of this file, which contains all of the
4761 kernel modules resulting from a kernel build.
4762
Andrew Geisslerf0343792020-11-18 10:42:21 -06004763 :term:`MODULE_TARBALL_LINK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004764 The link name of the kernel module tarball. This variable is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004765 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004766
4767 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4768
4769 The value
4770 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004771 same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004772
4773 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4774
4775 See the :term:`MACHINE` variable for additional information.
4776
Andrew Geisslerf0343792020-11-18 10:42:21 -06004777 :term:`MODULE_TARBALL_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004778 The base name of the kernel module tarball. This variable is set in
Andrew Geisslerc926e172021-05-07 16:11:35 -05004779 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004780
4781 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4782
4783 The value of the :term:`KERNEL_ARTIFACT_NAME` variable,
Andrew Geisslerc926e172021-05-07 16:11:35 -05004784 which is set in the same file, has the following value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004785
4786 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4787
Andrew Geisslerf0343792020-11-18 10:42:21 -06004788 :term:`MULTIMACH_TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004789 Uniquely identifies the type of the target system for which packages
4790 are being built. This variable allows output for different types of
4791 target systems to be put into different subdirectories of the same
4792 output directory.
4793
Andrew Geisslerc926e172021-05-07 16:11:35 -05004794 The default value of this variable is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004795
4796 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
4797
4798 Some classes (e.g.
4799 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the
Andrew Geissler09036742021-06-25 14:25:14 -05004800 :term:`MULTIMACH_TARGET_SYS` value.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004801
4802 See the :term:`STAMP` variable for an example. See the
4803 :term:`STAGING_DIR_TARGET` variable for more information.
4804
Andrew Geisslerf0343792020-11-18 10:42:21 -06004805 :term:`NATIVELSBSTRING`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004806 A string identifying the host distribution. Strings consist of the
4807 host distributor ID followed by the release, as reported by the
4808 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
4809 example, when running a build on Ubuntu 12.10, the value is
4810 "Ubuntu-12.10". If this information is unable to be determined, the
4811 value resolves to "Unknown".
4812
4813 This variable is used by default to isolate native shared state
4814 packages for different distributions (e.g. to avoid problems with
4815 ``glibc`` version incompatibilities). Additionally, the variable is
4816 checked against
4817 :term:`SANITY_TESTED_DISTROS` if that
4818 variable is set.
4819
Andrew Geisslerf0343792020-11-18 10:42:21 -06004820 :term:`NM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004821 The minimal command and arguments to run ``nm``.
4822
Andrew Geisslerf0343792020-11-18 10:42:21 -06004823 :term:`NO_GENERIC_LICENSE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004824 Avoids QA errors when you use a non-common, non-CLOSED license in a
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004825 recipe. There are packages, such as the linux-firmware package, with many
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004826 licenses that are not in any way common. Also, new licenses are added
4827 occasionally to avoid introducing a lot of common license files,
4828 which are only applicable to a specific package.
Andrew Geissler09036742021-06-25 14:25:14 -05004829 :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004830 not exist in common licenses.
4831
Andrew Geissler09036742021-06-25 14:25:14 -05004832 The following example shows how to add :term:`NO_GENERIC_LICENSE` to a
Andrew Geisslerc926e172021-05-07 16:11:35 -05004833 recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004834
4835 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
4836
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004837 Here is an example that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004838 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
Andrew Geisslerc926e172021-05-07 16:11:35 -05004839 source::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004840
4841 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
4842
Andrew Geisslerf0343792020-11-18 10:42:21 -06004843 :term:`NO_RECOMMENDATIONS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004844 Prevents installation of all "recommended-only" packages.
4845 Recommended-only packages are packages installed only through the
4846 :term:`RRECOMMENDS` variable). Setting the
Andrew Geissler09036742021-06-25 14:25:14 -05004847 :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004848
4849 NO_RECOMMENDATIONS = "1"
4850
4851 You can set this variable globally in your ``local.conf`` file or you
4852 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05004853 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004854
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004855 NO_RECOMMENDATIONS:pn-target_image = "1"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004856
4857 It is important to realize that if you choose to not install packages
4858 using this variable and some other packages are dependent on them
4859 (i.e. listed in a recipe's :term:`RDEPENDS`
4860 variable), the OpenEmbedded build system ignores your request and
4861 will install the packages to avoid dependency errors.
4862
4863 .. note::
4864
4865 Some recommended packages might be required for certain system
4866 functionality, such as kernel modules. It is up to you to add
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004867 packages with the :term:`IMAGE_INSTALL` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004868
William A. Kennington IIIac69b482021-06-02 12:28:27 -07004869 This variable is only supported when using the IPK and RPM
4870 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004871
4872 See the :term:`BAD_RECOMMENDATIONS` and
4873 the :term:`PACKAGE_EXCLUDE` variables for
4874 related information.
4875
Andrew Geisslerf0343792020-11-18 10:42:21 -06004876 :term:`NOAUTOPACKAGEDEBUG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004877 Disables auto package from splitting ``.debug`` files. If a recipe
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004878 requires ``FILES:${PN}-dbg`` to be set manually, the
Andrew Geissler09036742021-06-25 14:25:14 -05004879 :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004880 content of the debug package. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004881
4882 NOAUTOPACKAGEDEBUG = "1"
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004883 FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
4884 FILES:${PN}-dbg = "/usr/src/debug/"
4885 FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004886
Andrew Geissler09036742021-06-25 14:25:14 -05004887 :term:`NON_MULTILIB_RECIPES`
4888 A list of recipes that should not be built for multilib. OE-Core's
4889 ``multilib.conf`` file defines a reasonable starting point for this
4890 list with::
4891
4892 NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot"
4893
Andrew Geisslerf0343792020-11-18 10:42:21 -06004894 :term:`OBJCOPY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004895 The minimal command and arguments to run ``objcopy``.
4896
Andrew Geisslerf0343792020-11-18 10:42:21 -06004897 :term:`OBJDUMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004898 The minimal command and arguments to run ``objdump``.
4899
Andrew Geisslerf0343792020-11-18 10:42:21 -06004900 :term:`OE_BINCONFIG_EXTRA_MANGLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004901 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
4902 this variable specifies additional arguments passed to the "sed"
4903 command. The sed command alters any paths in configuration scripts
4904 that have been set up during compilation. Inheriting this class
4905 results in all paths in these scripts being changed to point into the
4906 ``sysroots/`` directory so that all builds that use the script will
4907 use the correct directories for the cross compiling layout.
4908
4909 See the ``meta/classes/binconfig.bbclass`` in the
4910 :term:`Source Directory` for details on how this class
4911 applies these additional sed command arguments. For general
4912 information on the ``binconfig`` class, see the
4913 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
4914
Andrew Geisslerf0343792020-11-18 10:42:21 -06004915 :term:`OE_IMPORTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004916 An internal variable used to tell the OpenEmbedded build system what
4917 Python modules to import for every Python function run by the system.
4918
4919 .. note::
4920
4921 Do not set this variable. It is for internal use only.
4922
Andrew Geisslerf0343792020-11-18 10:42:21 -06004923 :term:`OE_INIT_ENV_SCRIPT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004924 The name of the build environment setup script for the purposes of
4925 setting up the environment within the extensible SDK. The default
4926 value is "oe-init-build-env".
4927
4928 If you use a custom script to set up your build environment, set the
Andrew Geissler09036742021-06-25 14:25:14 -05004929 :term:`OE_INIT_ENV_SCRIPT` variable to its name.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004930
Andrew Geisslerf0343792020-11-18 10:42:21 -06004931 :term:`OE_TERMINAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004932 Controls how the OpenEmbedded build system spawns interactive
4933 terminals on the host development system (e.g. using the BitBake
4934 command with the ``-c devshell`` command-line option). For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06004935 information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004936 the Yocto Project Development Tasks Manual.
4937
Andrew Geissler5f350902021-07-23 13:09:54 -04004938 You can use the following values for the :term:`OE_TERMINAL` variable:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004939
4940 - auto
4941 - gnome
4942 - xfce
4943 - rxvt
4944 - screen
4945 - konsole
4946 - none
4947
Andrew Geisslerf0343792020-11-18 10:42:21 -06004948 :term:`OEROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004949 The directory from which the top-level build environment setup script
4950 is sourced. The Yocto Project provides a top-level build environment
Andrew Geissler4c19ea12020-10-27 13:52:24 -05004951 setup script: :ref:`structure-core-script`. When you run this
Andrew Geissler09036742021-06-25 14:25:14 -05004952 script, the :term:`OEROOT` variable resolves to the directory that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004953 contains the script.
4954
4955 For additional information on how this variable is used, see the
4956 initialization script.
4957
Andrew Geisslerf0343792020-11-18 10:42:21 -06004958 :term:`OLDEST_KERNEL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004959 Declares the oldest version of the Linux kernel that the produced
4960 binaries must support. This variable is passed into the build of the
4961 Embedded GNU C Library (``glibc``).
4962
4963 The default for this variable comes from the
4964 ``meta/conf/bitbake.conf`` configuration file. You can override this
4965 default by setting the variable in a custom distribution
4966 configuration file.
4967
Andrew Geisslerf0343792020-11-18 10:42:21 -06004968 :term:`OVERRIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004969 A colon-separated list of overrides that currently apply. Overrides
4970 are a BitBake mechanism that allows variables to be selectively
4971 overridden at the end of parsing. The set of overrides in
Andrew Geissler09036742021-06-25 14:25:14 -05004972 :term:`OVERRIDES` represents the "state" during building, which includes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004973 the current recipe being built, the machine for which it is being
4974 built, and so forth.
4975
4976 As an example, if the string "an-override" appears as an element in
Andrew Geissler09036742021-06-25 14:25:14 -05004977 the colon-separated list in :term:`OVERRIDES`, then the following
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004978 assignment will override ``FOO`` with the value "overridden" at the
Andrew Geisslerc926e172021-05-07 16:11:35 -05004979 end of parsing::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004980
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004981 FOO:an-override = "overridden"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004982
4983 See the
4984 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
4985 section in the BitBake User Manual for more information on the
4986 overrides mechanism.
4987
Andrew Geissler09036742021-06-25 14:25:14 -05004988 The default value of :term:`OVERRIDES` includes the values of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004989 :term:`CLASSOVERRIDE`,
4990 :term:`MACHINEOVERRIDES`, and
4991 :term:`DISTROOVERRIDES` variables. Another
4992 important override included by default is ``pn-${PN}``. This override
4993 allows variables to be set for a single recipe within configuration
Andrew Geisslerc926e172021-05-07 16:11:35 -05004994 (``.conf``) files. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004995
Patrick Williams0ca19cc2021-08-16 14:03:13 -05004996 FOO:pn-myrecipe = "myrecipe-specific value"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05004997
4998 .. note::
4999
Andrew Geissler09036742021-06-25 14:25:14 -05005000 An easy way to see what overrides apply is to search for :term:`OVERRIDES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005001 in the output of the ``bitbake -e`` command. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005002 ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005003 Project Development Tasks Manual for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005004
Andrew Geisslerf0343792020-11-18 10:42:21 -06005005 :term:`P`
Andrew Geissler09036742021-06-25 14:25:14 -05005006 The recipe name and version. :term:`P` is comprised of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005007
5008 ${PN}-${PV}
5009
Andrew Geisslerf0343792020-11-18 10:42:21 -06005010 :term:`PACKAGE_ADD_METADATA`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005011 This variable defines additional metadata to add to packages.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005012
5013 You may find you need to inject additional metadata into packages.
5014 This variable allows you to do that by setting the injected data as
5015 the value. Multiple fields can be added by splitting the content with
5016 the literal separator "\n".
5017
5018 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
5019 to do package type specific settings. It can also be made package
5020 specific by using the package name as a suffix.
5021
5022 You can find out more about applying this variable in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005023 ":ref:`dev-manual/common-tasks:adding custom metadata to packages`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005024 section in the Yocto Project Development Tasks Manual.
5025
Andrew Geisslerf0343792020-11-18 10:42:21 -06005026 :term:`PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005027 The architecture of the resulting package or packages.
5028
5029 By default, the value of this variable is set to
5030 :term:`TUNE_PKGARCH` when building for the
5031 target, :term:`BUILD_ARCH` when building for the
5032 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
5033 SDK.
5034
5035 .. note::
5036
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005037 See :term:`SDK_ARCH` for more information.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005038
5039 However, if your recipe's output packages are built specific to the
5040 target machine rather than generally for the architecture of the
Andrew Geissler09036742021-06-25 14:25:14 -05005041 machine, you should set :term:`PACKAGE_ARCH` to the value of
Andrew Geisslerc926e172021-05-07 16:11:35 -05005042 :term:`MACHINE_ARCH` in the recipe as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005043
5044 PACKAGE_ARCH = "${MACHINE_ARCH}"
5045
Andrew Geisslerf0343792020-11-18 10:42:21 -06005046 :term:`PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005047 Specifies a list of architectures compatible with the target machine.
5048 This variable is set automatically and should not normally be
5049 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05005050 of priority. The default value for :term:`PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005051 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
5052
Andrew Geisslerf0343792020-11-18 10:42:21 -06005053 :term:`PACKAGE_BEFORE_PN`
Andrew Geissler09036742021-06-25 14:25:14 -05005054 Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005055 that those added packages can pick up files that would normally be
5056 included in the default package.
5057
Andrew Geisslerf0343792020-11-18 10:42:21 -06005058 :term:`PACKAGE_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005059 This variable, which is set in the ``local.conf`` configuration file
5060 found in the ``conf`` folder of the
5061 :term:`Build Directory`, specifies the package manager the
5062 OpenEmbedded build system uses when packaging data.
5063
5064 You can provide one or more of the following arguments for the
5065 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk
5066 package_tar"
5067
5068 .. note::
5069
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005070 While it is a legal option, the ``package_tar``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005071 class has limited functionality due to no support for package
5072 dependencies by that backend. Therefore, it is recommended that
5073 you do not use it.
5074
5075 The build system uses only the first argument in the list as the
5076 package manager when creating your image or SDK. However, packages
5077 will be created using any additional packaging classes you specify.
Andrew Geisslerc926e172021-05-07 16:11:35 -05005078 For example, if you use the following in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005079
5080 PACKAGE_CLASSES ?= "package_ipk"
5081
5082 The OpenEmbedded build system uses
5083 the IPK package manager to create your image or SDK.
5084
5085 For information on packaging and build performance effects as a
5086 result of the package manager in use, see the
5087 ":ref:`package.bbclass <ref-classes-package>`" section.
5088
Andrew Geisslerf0343792020-11-18 10:42:21 -06005089 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
Patrick Williams93c203f2021-10-06 16:15:23 -05005090 Determines how to split up and package debug and source information
5091 when creating debugging packages to be used with the GNU Project
5092 Debugger (GDB). In general, based on the value of this variable,
5093 you can combine the source and debug info in a single package,
5094 you can break out the source into a separate package that can be
5095 installed independently, or you can choose to not have the source
5096 packaged at all.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005097
Patrick Williams93c203f2021-10-06 16:15:23 -05005098 The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005099
Patrick Williams93c203f2021-10-06 16:15:23 -05005100 - "``.debug``": All debugging and source info is placed in a single
5101 ``*-dbg`` package; debug symbol files are placed next to the
5102 binary in a ``.debug`` directory so that, if a binary is installed
5103 into ``/bin``, the corresponding debug symbol file is installed
5104 in ``/bin/.debug``. Source files are installed in the same ``*-dbg``
5105 package under ``/usr/src/debug``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005106
Patrick Williams93c203f2021-10-06 16:15:23 -05005107 - "``debug-file-directory``": As above, all debugging and source info
5108 is placed in a single ``*-dbg`` package; debug symbol files are
5109 placed entirely under the directory ``/usr/lib/debug`` and separated
5110 by the path from where the binary is installed, so that if a binary
5111 is installed in ``/bin``, the corresponding debug symbols are installed
5112 in ``/usr/lib/debug/bin``, and so on. As above, source is installed
5113 in the same package under ``/usr/src/debug``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005114
Patrick Williams93c203f2021-10-06 16:15:23 -05005115 - "``debug-with-srcpkg``": Debugging info is placed in the standard
5116 ``*-dbg`` package as with the ``.debug`` value, while source is
5117 placed in a separate ``*-src`` package, which can be installed
5118 independently. This is the default setting for this variable,
5119 as defined in Poky's ``bitbake.conf`` file.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005120
Patrick Williams93c203f2021-10-06 16:15:23 -05005121 - "``debug-without-src``": The same behavior as with the ``.debug``
5122 setting, but no source is packaged at all.
5123
5124 .. note::
5125
5126 Much of the above package splitting can be overridden via
5127 use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005128
5129 You can find out more about debugging using GDB by reading the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005130 ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005131 in the Yocto Project Development Tasks Manual.
5132
Andrew Geisslerf0343792020-11-18 10:42:21 -06005133 :term:`PACKAGE_EXCLUDE_COMPLEMENTARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005134 Prevents specific packages from being installed when you are
5135 installing complementary packages.
5136
5137 You might find that you want to prevent installing certain packages
5138 when you are installing complementary packages. For example, if you
5139 are using :term:`IMAGE_FEATURES` to install
5140 ``dev-pkgs``, you might not want to install all packages from a
5141 particular multilib. If you find yourself in this situation, you can
Andrew Geissler09036742021-06-25 14:25:14 -05005142 use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005143 expressions to match the packages you want to exclude.
5144
Andrew Geisslerf0343792020-11-18 10:42:21 -06005145 :term:`PACKAGE_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005146 Lists packages that should not be installed into an image. For
Andrew Geisslerc926e172021-05-07 16:11:35 -05005147 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005148
5149 PACKAGE_EXCLUDE = "package_name package_name package_name ..."
5150
5151 You can set this variable globally in your ``local.conf`` file or you
5152 can attach it to a specific image recipe by using the recipe name
Andrew Geisslerc926e172021-05-07 16:11:35 -05005153 override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005154
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005155 PACKAGE_EXCLUDE:pn-target_image = "package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005156
5157 If you choose to not install a package using this variable and some
5158 other package is dependent on it (i.e. listed in a recipe's
5159 :term:`RDEPENDS` variable), the OpenEmbedded build
5160 system generates a fatal installation error. Because the build system
5161 halts the process with a fatal error, you can use the variable with
5162 an iterative development process to remove specific components from a
5163 system.
5164
William A. Kennington IIIac69b482021-06-02 12:28:27 -07005165 This variable is supported only when using the IPK and RPM
5166 packaging backends. DEB is not supported.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005167
5168 See the :term:`NO_RECOMMENDATIONS` and the
5169 :term:`BAD_RECOMMENDATIONS` variables for
5170 related information.
5171
Andrew Geisslerf0343792020-11-18 10:42:21 -06005172 :term:`PACKAGE_EXTRA_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005173 Specifies the list of architectures compatible with the device CPU.
5174 This variable is useful when you build for several different devices
5175 that use miscellaneous processors such as XScale and ARM926-EJS.
5176
Andrew Geisslerf0343792020-11-18 10:42:21 -06005177 :term:`PACKAGE_FEED_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005178 Optionally specifies the package architectures used as part of the
5179 package feed URIs during the build. When used, the
Andrew Geissler09036742021-06-25 14:25:14 -05005180 :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005181 URI, which is constructed using the
5182 :term:`PACKAGE_FEED_URIS` and
5183 :term:`PACKAGE_FEED_BASE_PATHS`
5184 variables.
5185
5186 .. note::
5187
Andrew Geissler09036742021-06-25 14:25:14 -05005188 You can use the :term:`PACKAGE_FEED_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005189 variable to whitelist specific package architectures. If you do
5190 not need to whitelist specific architectures, which is a common
5191 case, you can omit this variable. Omitting the variable results in
5192 all available architectures for the current machine being included
5193 into remote package feeds.
5194
Andrew Geissler09036742021-06-25 14:25:14 -05005195 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5196 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005197 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005198
5199 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5200 https://example.com/packagerepos/updates"
5201 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5202 PACKAGE_FEED_ARCHS = "all core2-64"
5203
5204 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005205
5206 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005207
5208 https://example.com/packagerepos/release/rpm/all
5209 https://example.com/packagerepos/release/rpm/core2-64
5210 https://example.com/packagerepos/release/rpm-dev/all
5211 https://example.com/packagerepos/release/rpm-dev/core2-64
5212 https://example.com/packagerepos/updates/rpm/all
5213 https://example.com/packagerepos/updates/rpm/core2-64
5214 https://example.com/packagerepos/updates/rpm-dev/all
5215 https://example.com/packagerepos/updates/rpm-dev/core2-64
5216
Andrew Geisslerf0343792020-11-18 10:42:21 -06005217 :term:`PACKAGE_FEED_BASE_PATHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005218 Specifies the base path used when constructing package feed URIs. The
Andrew Geissler09036742021-06-25 14:25:14 -05005219 :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005220 package feed URI used by the OpenEmbedded build system. The base path
5221 lies between the :term:`PACKAGE_FEED_URIS`
5222 and :term:`PACKAGE_FEED_ARCHS` variables.
5223
Andrew Geissler09036742021-06-25 14:25:14 -05005224 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5225 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005226 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005227
5228 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5229 https://example.com/packagerepos/updates"
5230 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5231 PACKAGE_FEED_ARCHS = "all core2-64"
5232
5233 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005234
5235 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005236
5237 https://example.com/packagerepos/release/rpm/all
5238 https://example.com/packagerepos/release/rpm/core2-64
5239 https://example.com/packagerepos/release/rpm-dev/all
5240 https://example.com/packagerepos/release/rpm-dev/core2-64
5241 https://example.com/packagerepos/updates/rpm/all
5242 https://example.com/packagerepos/updates/rpm/core2-64
5243 https://example.com/packagerepos/updates/rpm-dev/all
5244 https://example.com/packagerepos/updates/rpm-dev/core2-64
5245
Andrew Geisslerf0343792020-11-18 10:42:21 -06005246 :term:`PACKAGE_FEED_URIS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005247 Specifies the front portion of the package feed URI used by the
5248 OpenEmbedded build system. Each final package feed URI is comprised
Andrew Geissler09036742021-06-25 14:25:14 -05005249 of :term:`PACKAGE_FEED_URIS`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005250 :term:`PACKAGE_FEED_BASE_PATHS`, and
5251 :term:`PACKAGE_FEED_ARCHS` variables.
5252
Andrew Geissler09036742021-06-25 14:25:14 -05005253 Consider the following example where the :term:`PACKAGE_FEED_URIS`,
5254 :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005255 defined in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005256
5257 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
5258 https://example.com/packagerepos/updates"
5259 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
5260 PACKAGE_FEED_ARCHS = "all core2-64"
5261
5262 Given these settings, the resulting package feeds are as follows:
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005263
5264 .. code-block:: none
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005265
5266 https://example.com/packagerepos/release/rpm/all
5267 https://example.com/packagerepos/release/rpm/core2-64
5268 https://example.com/packagerepos/release/rpm-dev/all
5269 https://example.com/packagerepos/release/rpm-dev/core2-64
5270 https://example.com/packagerepos/updates/rpm/all
5271 https://example.com/packagerepos/updates/rpm/core2-64
5272 https://example.com/packagerepos/updates/rpm-dev/all
5273 https://example.com/packagerepos/updates/rpm-dev/core2-64
5274
Andrew Geisslerf0343792020-11-18 10:42:21 -06005275 :term:`PACKAGE_INSTALL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005276 The final list of packages passed to the package manager for
5277 installation into the image.
5278
5279 Because the package manager controls actual installation of all
Andrew Geissler09036742021-06-25 14:25:14 -05005280 packages, the list of packages passed using :term:`PACKAGE_INSTALL` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005281 not the final list of packages that are actually installed. This
5282 variable is internal to the image construction code. Consequently, in
5283 general, you should use the
5284 :term:`IMAGE_INSTALL` variable to specify
5285 packages for installation. The exception to this is when working with
Andrew Geissler09209ee2020-12-13 08:44:15 -06005286 the :ref:`core-image-minimal-initramfs <ref-manual/images:images>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005287 image. When working with an initial RAM filesystem (initramfs) image,
Andrew Geissler09036742021-06-25 14:25:14 -05005288 use the :term:`PACKAGE_INSTALL` variable. For information on creating an
Andrew Geissler09209ee2020-12-13 08:44:15 -06005289 initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005290 in the Yocto Project Development Tasks Manual.
5291
Andrew Geisslerf0343792020-11-18 10:42:21 -06005292 :term:`PACKAGE_INSTALL_ATTEMPTONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005293 Specifies a list of packages the OpenEmbedded build system attempts
5294 to install when creating an image. If a listed package fails to
5295 install, the build system does not generate an error. This variable
5296 is generally not user-defined.
5297
Andrew Geisslerf0343792020-11-18 10:42:21 -06005298 :term:`PACKAGE_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005299 Specifies a list of functions run to pre-process the
5300 :term:`PKGD` directory prior to splitting the files out
5301 to individual packages.
5302
Andrew Geisslerf0343792020-11-18 10:42:21 -06005303 :term:`PACKAGE_WRITE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005304 Specifies a list of dependencies for post-installation and
5305 pre-installation scripts on native/cross tools. If your
5306 post-installation or pre-installation script can execute at rootfs
5307 creation time rather than on the target but depends on a native tool
5308 in order to execute, you need to list the tools in
Andrew Geissler09036742021-06-25 14:25:14 -05005309 :term:`PACKAGE_WRITE_DEPS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005310
5311 For information on running post-installation scripts, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005312 ":ref:`dev-manual/common-tasks:post-installation scripts`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005313 section in the Yocto Project Development Tasks Manual.
5314
Andrew Geisslerf0343792020-11-18 10:42:21 -06005315 :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005316 This variable provides a means of enabling or disabling features of a
Andrew Geissler09036742021-06-25 14:25:14 -05005317 recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005318 recipes when you specify features and then arguments that define
5319 feature behaviors. Here is the basic block structure (broken over
Andrew Geisslerc926e172021-05-07 16:11:35 -05005320 multiple lines for readability)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005321
5322 PACKAGECONFIG ??= "f1 f2 f3 ..."
5323 PACKAGECONFIG[f1] = "\
5324 --with-f1, \
5325 --without-f1, \
5326 build-deps-for-f1, \
5327 runtime-deps-for-f1, \
5328 runtime-recommends-for-f1, \
5329 packageconfig-conflicts-for-f1"
5330 PACKAGECONFIG[f2] = "\
5331 ... and so on and so on ...
5332
Andrew Geissler5f350902021-07-23 13:09:54 -04005333 The :term:`PACKAGECONFIG` variable itself specifies a space-separated
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005334 list of the features to enable. Following the features, you can
5335 determine the behavior of each feature by providing up to six
5336 order-dependent arguments, which are separated by commas. You can
5337 omit any argument you like but must retain the separating commas. The
5338 order is important and specifies the following:
5339
5340 1. Extra arguments that should be added to the configure script
5341 argument list (:term:`EXTRA_OECONF` or
5342 :term:`PACKAGECONFIG_CONFARGS`) if
5343 the feature is enabled.
5344
Andrew Geissler09036742021-06-25 14:25:14 -05005345 2. Extra arguments that should be added to :term:`EXTRA_OECONF` or
5346 :term:`PACKAGECONFIG_CONFARGS` if the feature is disabled.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005347
5348 3. Additional build dependencies (:term:`DEPENDS`)
5349 that should be added if the feature is enabled.
5350
5351 4. Additional runtime dependencies (:term:`RDEPENDS`)
5352 that should be added if the feature is enabled.
5353
5354 5. Additional runtime recommendations
5355 (:term:`RRECOMMENDS`) that should be added if
5356 the feature is enabled.
5357
Andrew Geissler09036742021-06-25 14:25:14 -05005358 6. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005359 settings for this feature.
5360
Andrew Geissler09036742021-06-25 14:25:14 -05005361 Consider the following :term:`PACKAGECONFIG` block taken from the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005362 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
5363 three arguments that determine the feature's behavior.
5364 ::
5365
5366 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
5367
5368 The
5369 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
5370 enabled. In this case, ``--with-gtk3`` is added to the configure
Andrew Geissler09036742021-06-25 14:25:14 -05005371 script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005372 other hand, if the feature is disabled say through a ``.bbappend``
5373 file in another layer, then the second argument ``--without-gtk3`` is
5374 added to the configure script instead.
5375
Andrew Geissler09036742021-06-25 14:25:14 -05005376 The basic :term:`PACKAGECONFIG` structure previously described holds true
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005377 regardless of whether you are creating a block or changing a block.
5378 When creating a block, use the structure inside your recipe.
5379
Andrew Geissler09036742021-06-25 14:25:14 -05005380 If you want to change an existing :term:`PACKAGECONFIG` block, you can do
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005381 so one of two ways:
5382
5383 - *Append file:* Create an append file named
Andrew Geisslereff27472021-10-29 15:35:00 -05005384 ``recipename.bbappend`` in your layer and override the value of
Andrew Geissler09036742021-06-25 14:25:14 -05005385 :term:`PACKAGECONFIG`. You can either completely override the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005386 variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005387
5388 PACKAGECONFIG = "f4 f5"
5389
Andrew Geisslerc926e172021-05-07 16:11:35 -05005390 Or, you can just append the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005391
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005392 PACKAGECONFIG:append = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005393
5394 - *Configuration file:* This method is identical to changing the
5395 block through an append file except you edit your ``local.conf``
5396 or ``mydistro.conf`` file. As with append files previously
Andrew Geisslerc926e172021-05-07 16:11:35 -05005397 described, you can either completely override the variable::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005398
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005399 PACKAGECONFIG:pn-recipename = "f4 f5"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005400
Andrew Geisslerc926e172021-05-07 16:11:35 -05005401 Or, you can just amend the variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005402
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005403 PACKAGECONFIG:append:pn-recipename = " f4"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005404
Andrew Geisslerf0343792020-11-18 10:42:21 -06005405 :term:`PACKAGECONFIG_CONFARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005406 A space-separated list of configuration options generated from the
5407 :term:`PACKAGECONFIG` setting.
5408
5409 Classes such as :ref:`autotools <ref-classes-autotools>` and
Andrew Geissler09036742021-06-25 14:25:14 -05005410 :ref:`cmake <ref-classes-cmake>` use :term:`PACKAGECONFIG_CONFARGS` to
5411 pass :term:`PACKAGECONFIG` options to ``configure`` and ``cmake``,
5412 respectively. If you are using :term:`PACKAGECONFIG` but not a class that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005413 handles the ``do_configure`` task, then you need to use
Andrew Geissler09036742021-06-25 14:25:14 -05005414 :term:`PACKAGECONFIG_CONFARGS` appropriately.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005415
Andrew Geisslerf0343792020-11-18 10:42:21 -06005416 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005417 For recipes inheriting the
5418 :ref:`packagegroup <ref-classes-packagegroup>` class, setting
Andrew Geissler09036742021-06-25 14:25:14 -05005419 :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005420 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
5421 should not be automatically created by the ``packagegroup`` recipe,
5422 which is the default behavior.
5423
Andrew Geisslerf0343792020-11-18 10:42:21 -06005424 :term:`PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005425 The list of packages the recipe creates. The default value is the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005426 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005427
Andrew Geissler5199d832021-09-24 16:47:35 -05005428 ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005429
5430 During packaging, the :ref:`ref-tasks-package` task
Andrew Geissler09036742021-06-25 14:25:14 -05005431 goes through :term:`PACKAGES` and uses the :term:`FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005432 variable corresponding to each package to assign files to the
Andrew Geissler09036742021-06-25 14:25:14 -05005433 package. If a file matches the :term:`FILES` variable for more than one
5434 package in :term:`PACKAGES`, it will be assigned to the earliest
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005435 (leftmost) package.
5436
5437 Packages in the variable's list that are empty (i.e. where none of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005438 the patterns in ``FILES:``\ pkg match any files installed by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005439 :ref:`ref-tasks-install` task) are not generated,
5440 unless generation is forced through the
5441 :term:`ALLOW_EMPTY` variable.
5442
Andrew Geisslerf0343792020-11-18 10:42:21 -06005443 :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005444 A promise that your recipe satisfies runtime dependencies for
5445 optional modules that are found in other recipes.
Andrew Geissler09036742021-06-25 14:25:14 -05005446 :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005447 only states that they should be satisfied. For example, if a hard,
5448 runtime dependency (:term:`RDEPENDS`) of another
Andrew Geissler09036742021-06-25 14:25:14 -05005449 package is satisfied at build time through the :term:`PACKAGES_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005450 variable, but a package with the module name is never actually
5451 produced, then the other package will be broken. Thus, if you attempt
5452 to include that package in an image, you will get a dependency
5453 failure from the packaging system during the
5454 :ref:`ref-tasks-rootfs` task.
5455
5456 Typically, if there is a chance that such a situation can occur and
5457 the package that is not created is valid without the dependency being
5458 satisfied, then you should use :term:`RRECOMMENDS`
Andrew Geissler09036742021-06-25 14:25:14 -05005459 (a soft runtime dependency) instead of :term:`RDEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005460
Andrew Geissler09036742021-06-25 14:25:14 -05005461 For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005462 you are splitting packages, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005463 ":ref:`dev-manual/common-tasks:handling optional module packaging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005464 section in the Yocto Project Development Tasks Manual.
5465
Andrew Geisslerf0343792020-11-18 10:42:21 -06005466 :term:`PACKAGESPLITFUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005467 Specifies a list of functions run to perform additional splitting of
5468 files into individual packages. Recipes can either prepend to this
5469 variable or prepend to the ``populate_packages`` function in order to
5470 perform additional package splitting. In either case, the function
5471 should set :term:`PACKAGES`,
5472 :term:`FILES`, :term:`RDEPENDS` and
5473 other packaging variables appropriately in order to perform the
5474 desired splitting.
5475
Andrew Geisslerf0343792020-11-18 10:42:21 -06005476 :term:`PARALLEL_MAKE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005477 Extra options passed to the ``make`` command during the
5478 :ref:`ref-tasks-compile` task in order to specify
5479 parallel compilation on the local build host. This variable is
5480 usually in the form "-j x", where x represents the maximum number of
5481 parallel threads ``make`` can run.
5482
5483 .. note::
5484
Andrew Geissler09036742021-06-25 14:25:14 -05005485 In order for :term:`PARALLEL_MAKE` to be effective, ``make`` must be
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005486 called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure
5487 this is to use the ``oe_runmake`` function.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005488
5489 By default, the OpenEmbedded build system automatically sets this
5490 variable to be equal to the number of cores the build system uses.
5491
5492 .. note::
5493
5494 If the software being built experiences dependency issues during
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005495 the ``do_compile`` task that result in race conditions, you can clear
Andrew Geissler09036742021-06-25 14:25:14 -05005496 the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005497 information on addressing race conditions, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005498 ":ref:`dev-manual/common-tasks:debugging parallel make races`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005499 section in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005500
5501 For single socket systems (i.e. one CPU), you should not have to
5502 override this variable to gain optimal parallelism during builds.
5503 However, if you have very large systems that employ multiple physical
Andrew Geissler09036742021-06-25 14:25:14 -05005504 CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005505 not set higher than "-j 20".
5506
5507 For more information on speeding up builds, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005508 ":ref:`dev-manual/common-tasks:speeding up a build`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005509 section in the Yocto Project Development Tasks Manual.
5510
Andrew Geisslerf0343792020-11-18 10:42:21 -06005511 :term:`PARALLEL_MAKEINST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005512 Extra options passed to the ``make install`` command during the
5513 :ref:`ref-tasks-install` task in order to specify
5514 parallel installation. This variable defaults to the value of
5515 :term:`PARALLEL_MAKE`.
5516
5517 .. note::
5518
Andrew Geissler09036742021-06-25 14:25:14 -05005519 In order for :term:`PARALLEL_MAKEINST` to be effective, ``make`` must
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005520 be called with
5521 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
5522 way to ensure this is to use the ``oe_runmake`` function.
5523
5524 If the software being built experiences dependency issues during
5525 the ``do_install`` task that result in race conditions, you can
Andrew Geissler09036742021-06-25 14:25:14 -05005526 clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005527 workaround. For information on addressing race conditions, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005528 ":ref:`dev-manual/common-tasks:debugging parallel make races`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005529 section in the Yocto Project Development Tasks Manual.
5530
Andrew Geisslerf0343792020-11-18 10:42:21 -06005531 :term:`PATCHRESOLVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005532 Determines the action to take when a patch fails. You can set this
5533 variable to one of two values: "noop" and "user".
5534
5535 The default value of "noop" causes the build to simply fail when the
5536 OpenEmbedded build system cannot successfully apply a patch. Setting
5537 the value to "user" causes the build system to launch a shell and
5538 places you in the right location so that you can manually resolve the
5539 conflicts.
5540
5541 Set this variable in your ``local.conf`` file.
5542
Andrew Geisslerf0343792020-11-18 10:42:21 -06005543 :term:`PATCHTOOL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005544 Specifies the utility used to apply patches for a recipe during the
5545 :ref:`ref-tasks-patch` task. You can specify one of
5546 three utilities: "patch", "quilt", or "git". The default utility used
5547 is "quilt" except for the quilt-native recipe itself. Because the
5548 quilt tool is not available at the time quilt-native is being
5549 patched, it uses "patch".
5550
5551 If you wish to use an alternative patching tool, set the variable in
Andrew Geisslerc926e172021-05-07 16:11:35 -05005552 the recipe using one of the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005553
5554 PATCHTOOL = "patch"
5555 PATCHTOOL = "quilt"
5556 PATCHTOOL = "git"
5557
Andrew Geisslerf0343792020-11-18 10:42:21 -06005558 :term:`PE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005559 The epoch of the recipe. By default, this variable is unset. The
5560 variable is used to make upgrades possible when the versioning scheme
5561 changes in some backwards incompatible way.
5562
Andrew Geissler09036742021-06-25 14:25:14 -05005563 :term:`PE` is the default value of the :term:`PKGE` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005564
Andrew Geisslerf0343792020-11-18 10:42:21 -06005565 :term:`PF`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005566 Specifies the recipe or package name and includes all version and
5567 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
5568 ``bash-4.2-r1/``). This variable is comprised of the following:
5569 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
5570
Andrew Geisslerf0343792020-11-18 10:42:21 -06005571 :term:`PIXBUF_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005572 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
5573 class, this variable identifies packages that contain the pixbuf
5574 loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache``
5575 class assumes that the loaders are in the recipe's main package (i.e.
5576 ``${``\ :term:`PN`\ ``}``). Use this variable if the
5577 loaders you need are in a package other than that main package.
5578
Andrew Geisslerf0343792020-11-18 10:42:21 -06005579 :term:`PKG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005580 The name of the resulting package created by the OpenEmbedded build
5581 system.
5582
5583 .. note::
5584
Andrew Geissler09036742021-06-25 14:25:14 -05005585 When using the :term:`PKG` variable, you must use a package name override.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005586
5587 For example, when the :ref:`debian <ref-classes-debian>` class
5588 renames the output package, it does so by setting
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005589 ``PKG:packagename``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005590
Andrew Geisslerf0343792020-11-18 10:42:21 -06005591 :term:`PKG_CONFIG_PATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005592 The path to ``pkg-config`` files for the current build context.
5593 ``pkg-config`` reads this variable from the environment.
5594
Andrew Geisslerf0343792020-11-18 10:42:21 -06005595 :term:`PKGD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005596 Points to the destination directory for files to be packaged before
5597 they are split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05005598 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005599
5600 ${WORKDIR}/package
5601
5602 Do not change this default.
5603
Andrew Geisslerf0343792020-11-18 10:42:21 -06005604 :term:`PKGDATA_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005605 Points to a shared, global-state directory that holds data generated
5606 during the packaging process. During the packaging process, the
5607 :ref:`ref-tasks-packagedata` task packages data
5608 for each recipe and installs it into this temporary, shared area.
5609 This directory defaults to the following, which you should not
Andrew Geisslerc926e172021-05-07 16:11:35 -05005610 change::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005611
5612 ${STAGING_DIR_HOST}/pkgdata
5613
5614 For examples of how this data is used, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005615 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005616 section in the Yocto Project Overview and Concepts Manual and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005617 ":ref:`dev-manual/common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005618 section in the Yocto Project Development Tasks Manual. For more
5619 information on the shared, global-state directory, see
5620 :term:`STAGING_DIR_HOST`.
5621
Andrew Geisslerf0343792020-11-18 10:42:21 -06005622 :term:`PKGDEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005623 Points to the parent directory for files to be packaged after they
5624 have been split into individual packages. This directory defaults to
Andrew Geisslerc926e172021-05-07 16:11:35 -05005625 the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005626
5627 ${WORKDIR}/packages-split
5628
5629 Under this directory, the build system creates directories for each
5630 package specified in :term:`PACKAGES`. Do not change
5631 this default.
5632
Andrew Geisslerf0343792020-11-18 10:42:21 -06005633 :term:`PKGDESTWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005634 Points to a temporary work area where the
5635 :ref:`ref-tasks-package` task saves package metadata.
Andrew Geissler09036742021-06-25 14:25:14 -05005636 The :term:`PKGDESTWORK` location defaults to the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005637
5638 ${WORKDIR}/pkgdata
5639
5640 Do not change this default.
5641
5642 The :ref:`ref-tasks-packagedata` task copies the
Andrew Geissler09036742021-06-25 14:25:14 -05005643 package metadata from :term:`PKGDESTWORK` to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005644 :term:`PKGDATA_DIR` to make it available globally.
5645
Andrew Geisslerf0343792020-11-18 10:42:21 -06005646 :term:`PKGE`
Andrew Geissler09036742021-06-25 14:25:14 -05005647 The epoch of the package(s) built by the recipe. By default, :term:`PKGE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005648 is set to :term:`PE`.
5649
Andrew Geisslerf0343792020-11-18 10:42:21 -06005650 :term:`PKGR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005651 The revision of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05005652 :term:`PKGR` is set to :term:`PR`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005653
Andrew Geisslerf0343792020-11-18 10:42:21 -06005654 :term:`PKGV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005655 The version of the package(s) built by the recipe. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05005656 :term:`PKGV` is set to :term:`PV`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005657
Andrew Geisslerf0343792020-11-18 10:42:21 -06005658 :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005659 This variable can have two separate functions depending on the
5660 context: a recipe name or a resulting package name.
5661
Andrew Geissler09036742021-06-25 14:25:14 -05005662 :term:`PN` refers to a recipe name in the context of a file used by the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005663 OpenEmbedded build system as input to create a package. The name is
5664 normally extracted from the recipe file name. For example, if the
Andrew Geissler09036742021-06-25 14:25:14 -05005665 recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005666 will be "expat".
5667
5668 The variable refers to a package name in the context of a file
5669 created or produced by the OpenEmbedded build system.
5670
Andrew Geissler09036742021-06-25 14:25:14 -05005671 If applicable, the :term:`PN` variable also contains any special suffix
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005672 or prefix. For example, using ``bash`` to build packages for the
Andrew Geissler5f350902021-07-23 13:09:54 -04005673 native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build
Andrew Geissler09036742021-06-25 14:25:14 -05005674 packages for the target and for Multilib, :term:`PN` would be ``bash``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005675 and ``lib64-bash``, respectively.
5676
Andrew Geisslerf0343792020-11-18 10:42:21 -06005677 :term:`PNBLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005678 Lists recipes you do not want the OpenEmbedded build system to build.
5679 This variable works in conjunction with the
5680 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited
5681 globally.
5682
Andrew Geissler09036742021-06-25 14:25:14 -05005683 To prevent a recipe from being built, use the :term:`PNBLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005684 variable in your ``local.conf`` file. Here is an example that
Andrew Geisslerc926e172021-05-07 16:11:35 -05005685 prevents ``myrecipe`` from being built::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005686
5687 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5688
Andrew Geisslerf0343792020-11-18 10:42:21 -06005689 :term:`POPULATE_SDK_POST_HOST_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005690 Specifies a list of functions to call once the OpenEmbedded build
5691 system has created the host part of the SDK. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05005692 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005693
5694 POPULATE_SDK_POST_HOST_COMMAND += "function; ... "
5695
5696 If you need to pass the SDK path to a command within a function, you
5697 can use ``${SDK_DIR}``, which points to the parent directory used by
5698 the OpenEmbedded build system when creating SDK output. See the
5699 :term:`SDK_DIR` variable for more information.
5700
Andrew Geisslerf0343792020-11-18 10:42:21 -06005701 :term:`POPULATE_SDK_POST_TARGET_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005702 Specifies a list of functions to call once the OpenEmbedded build
5703 system has created the target part of the SDK. You can specify
Andrew Geisslerc926e172021-05-07 16:11:35 -05005704 functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005705
5706 POPULATE_SDK_POST_TARGET_COMMAND += "function; ... "
5707
5708 If you need to pass the SDK path to a command within a function, you
5709 can use ``${SDK_DIR}``, which points to the parent directory used by
5710 the OpenEmbedded build system when creating SDK output. See the
5711 :term:`SDK_DIR` variable for more information.
5712
Andrew Geisslerf0343792020-11-18 10:42:21 -06005713 :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005714 The revision of the recipe. The default value for this variable is
5715 "r0". Subsequent revisions of the recipe conventionally have the
5716 values "r1", "r2", and so forth. When :term:`PV` increases,
Andrew Geissler09036742021-06-25 14:25:14 -05005717 :term:`PR` is conventionally reset to "r0".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005718
5719 .. note::
5720
Andrew Geissler09036742021-06-25 14:25:14 -05005721 The OpenEmbedded build system does not need the aid of :term:`PR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005722 to know when to rebuild a recipe. The build system uses the task
Andrew Geissler09209ee2020-12-13 08:44:15 -06005723 :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005724 :ref:`stamp <structure-build-tmp-stamps>` and
Andrew Geissler09209ee2020-12-13 08:44:15 -06005725 :ref:`overview-manual/concepts:shared state cache`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005726 mechanisms.
5727
Andrew Geissler09036742021-06-25 14:25:14 -05005728 The :term:`PR` variable primarily becomes significant when a package
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005729 manager dynamically installs packages on an already built image. In
Andrew Geissler09036742021-06-25 14:25:14 -05005730 this case, :term:`PR`, which is the default value of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005731 :term:`PKGR`, helps the package manager distinguish which
5732 package is the most recent one in cases where many packages have the
Andrew Geissler09036742021-06-25 14:25:14 -05005733 same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with
5734 the same :term:`PV` usually means that the packages all install the same
5735 upstream version, but with later (:term:`PR`) version packages including
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005736 packaging fixes.
5737
5738 .. note::
5739
Andrew Geissler09036742021-06-25 14:25:14 -05005740 :term:`PR` does not need to be increased for changes that do not change the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005741 package contents or metadata.
5742
Andrew Geissler5f350902021-07-23 13:09:54 -04005743 Because manually managing :term:`PR` can be cumbersome and error-prone,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005744 an automated solution exists. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005745 ":ref:`dev-manual/common-tasks:working with a pr service`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005746 in the Yocto Project Development Tasks Manual for more information.
5747
Andrew Geisslerf0343792020-11-18 10:42:21 -06005748 :term:`PREFERRED_PROVIDER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005749 If multiple recipes provide the same item, this variable determines
5750 which recipe is preferred and thus provides the item (i.e. the
5751 preferred provider). You should always suffix this variable with the
5752 name of the provided item. And, you should define the variable using
5753 the preferred recipe's name (:term:`PN`). Here is a common
Andrew Geisslerc926e172021-05-07 16:11:35 -05005754 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005755
5756 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5757
5758 In the previous example, multiple recipes are providing "virtual/kernel".
Andrew Geissler09036742021-06-25 14:25:14 -05005759 The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005760 the recipe you prefer to provide "virtual/kernel".
5761
Andrew Geisslerc926e172021-05-07 16:11:35 -05005762 Following are more examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005763
5764 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5765 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5766
5767 For more
Andrew Geissler09209ee2020-12-13 08:44:15 -06005768 information, see the ":ref:`dev-manual/common-tasks:using virtual providers`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005769 section in the Yocto Project Development Tasks Manual.
5770
5771 .. note::
5772
Andrew Geissler09036742021-06-25 14:25:14 -05005773 If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005774 recipe that :term:`PROVIDES` that item but is not selected (defined)
Andrew Geissler09036742021-06-25 14:25:14 -05005775 by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually
Andrew Geissler4c19ea12020-10-27 13:52:24 -05005776 desirable since this mechanism is designed to select between mutually
5777 exclusive alternative providers.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005778
Andrew Geisslerf0343792020-11-18 10:42:21 -06005779 :term:`PREFERRED_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005780 If there are multiple versions of a recipe available, this variable
5781 determines which version should be given preference. You must always
5782 suffix the variable with the :term:`PN` you want to select (`python` in
5783 the first example below), and you should specify the :term:`PV`
5784 accordingly (`3.4.0` in the example).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005785
Andrew Geissler09036742021-06-25 14:25:14 -05005786 The :term:`PREFERRED_VERSION` variable supports limited wildcard use
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005787 through the "``%``" character. You can use the character to match any
5788 number of characters, which can be useful when specifying versions
5789 that contain long revision numbers that potentially change. Here are
Andrew Geisslerc926e172021-05-07 16:11:35 -05005790 two examples::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005791
5792 PREFERRED_VERSION_python = "3.4.0"
5793 PREFERRED_VERSION_linux-yocto = "5.0%"
5794
5795 .. note::
5796
5797 The use of the "%" character is limited in that it only works at the end of the
5798 string. You cannot use the wildcard character in any other
5799 location of the string.
5800
5801 The specified version is matched against :term:`PV`, which
5802 does not necessarily match the version part of the recipe's filename.
5803 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
Andrew Geisslerc926e172021-05-07 16:11:35 -05005804 where ``foo_git.bb`` contains the following assignment::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005805
5806 PV = "1.1+git${SRCPV}"
5807
5808 In this case, the correct way to select
Andrew Geisslerc926e172021-05-07 16:11:35 -05005809 ``foo_git.bb`` is by using an assignment such as the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005810
5811 PREFERRED_VERSION_foo = "1.1+git%"
5812
5813 Compare that previous example
Andrew Geisslerc926e172021-05-07 16:11:35 -05005814 against the following incorrect example, which does not work::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005815
5816 PREFERRED_VERSION_foo = "git"
5817
Andrew Geissler09036742021-06-25 14:25:14 -05005818 Sometimes the :term:`PREFERRED_VERSION` variable can be set by
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005819 configuration files in a way that is hard to change. You can use
5820 :term:`OVERRIDES` to set a machine-specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05005821 override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005822
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005823 PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005824
5825 Although not recommended, worst case, you can also use the
5826 "forcevariable" override, which is the strongest override possible.
Andrew Geisslerc926e172021-05-07 16:11:35 -05005827 Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005828
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005829 PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005830
5831 .. note::
5832
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005833 The ``:forcevariable`` override is not handled specially. This override
Andrew Geissler09036742021-06-25 14:25:14 -05005834 only works because the default value of :term:`OVERRIDES` includes "forcevariable".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005835
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05005836 If a recipe with the specified version is not available, a warning
5837 message will be shown. See :term:`REQUIRED_VERSION` if you want this
5838 to be an error instead.
5839
Andrew Geisslerf0343792020-11-18 10:42:21 -06005840 :term:`PREMIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005841 Specifies additional paths from which the OpenEmbedded build system
5842 gets source code. When the build system searches for source code, it
5843 first tries the local download directory. If that location fails, the
Andrew Geissler09036742021-06-25 14:25:14 -05005844 build system tries locations defined by :term:`PREMIRRORS`, the upstream
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005845 source, and then locations specified by
5846 :term:`MIRRORS` in that order.
5847
5848 Assuming your distribution (:term:`DISTRO`) is "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05005849 the default value for :term:`PREMIRRORS` is defined in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005850 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
5851
5852 Typically, you could add a specific server for the build system to
5853 attempt before any others by adding something like the following to
5854 the ``local.conf`` configuration file in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05005855 :term:`Build Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005856
Patrick Williams0ca19cc2021-08-16 14:03:13 -05005857 PREMIRRORS:prepend = "\
Andrew Geisslereff27472021-10-29 15:35:00 -05005858 git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \n \
5859 ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \n \
5860 http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \n \
5861 https://.*/.* &YOCTO_DL_URL;/mirror/sources/ \n"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005862
5863 These changes cause the
5864 build system to intercept Git, FTP, HTTP, and HTTPS requests and
5865 direct them to the ``http://`` sources mirror. You can use
5866 ``file://`` URLs to point to local directories or network shares as
5867 well.
5868
Andrew Geisslerf0343792020-11-18 10:42:21 -06005869 :term:`PRIORITY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005870 Indicates the importance of a package.
5871
Andrew Geissler09036742021-06-25 14:25:14 -05005872 :term:`PRIORITY` is considered to be part of the distribution policy
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005873 because the importance of any given recipe depends on the purpose for
Andrew Geissler09036742021-06-25 14:25:14 -05005874 which the distribution is being produced. Thus, :term:`PRIORITY` is not
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005875 normally set within recipes.
5876
Andrew Geissler09036742021-06-25 14:25:14 -05005877 You can set :term:`PRIORITY` to "required", "standard", "extra", and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005878 "optional", which is the default.
5879
Andrew Geisslerf0343792020-11-18 10:42:21 -06005880 :term:`PRIVATE_LIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005881 Specifies libraries installed within a recipe that should be ignored
5882 by the OpenEmbedded build system's shared library resolver. This
5883 variable is typically used when software being built by a recipe has
5884 its own private versions of a library normally provided by another
5885 recipe. In this case, you would not want the package containing the
5886 private libraries to be set as a dependency on other unrelated
5887 packages that should instead depend on the package providing the
5888 standard version of the library.
5889
5890 Libraries specified in this variable should be specified by their
Andrew Geisslerc926e172021-05-07 16:11:35 -05005891 file name. For example, from the Firefox recipe in meta-browser::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005892
5893 PRIVATE_LIBS = "libmozjs.so \
5894 libxpcom.so \
5895 libnspr4.so \
5896 libxul.so \
5897 libmozalloc.so \
5898 libplc4.so \
5899 libplds4.so"
5900
5901 For more information, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06005902 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005903 section in the Yocto Project Overview and Concepts Manual.
5904
Andrew Geisslerf0343792020-11-18 10:42:21 -06005905 :term:`PROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005906 A list of aliases by which a particular recipe can be known. By
Andrew Geissler09036742021-06-25 14:25:14 -05005907 default, a recipe's own :term:`PN` is implicitly already in its
5908 :term:`PROVIDES` list and therefore does not need to mention that it
5909 provides itself. If a recipe uses :term:`PROVIDES`, the additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005910 aliases are synonyms for the recipe and can be useful for satisfying
5911 dependencies of other recipes during the build as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05005912 :term:`DEPENDS`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005913
Andrew Geissler09036742021-06-25 14:25:14 -05005914 Consider the following example :term:`PROVIDES` statement from the recipe
Andrew Geisslerc926e172021-05-07 16:11:35 -05005915 file ``eudev_3.2.9.bb``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005916
Andrew Geisslerd1e89492021-02-12 15:35:20 -06005917 PROVIDES += "udev"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005918
Andrew Geissler09036742021-06-25 14:25:14 -05005919 The :term:`PROVIDES` statement
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005920 results in the "eudev" recipe also being available as simply "udev".
5921
5922 .. note::
5923
Andrew Geisslerd1e89492021-02-12 15:35:20 -06005924 A recipe's own recipe name (:term:`PN`) is always implicitly prepended
5925 to `PROVIDES`, so while using "+=" in the above example may not be
5926 strictly necessary it is recommended to avoid confusion.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005927
5928 In addition to providing recipes under alternate names, the
Andrew Geissler09036742021-06-25 14:25:14 -05005929 :term:`PROVIDES` mechanism is also used to implement virtual targets. A
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005930 virtual target is a name that corresponds to some particular
5931 functionality (e.g. a Linux kernel). Recipes that provide the
Andrew Geissler09036742021-06-25 14:25:14 -05005932 functionality in question list the virtual target in :term:`PROVIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005933 Recipes that depend on the functionality in question can include the
Andrew Geissler09036742021-06-25 14:25:14 -05005934 virtual target in :term:`DEPENDS` to leave the choice of provider open.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005935
5936 Conventionally, virtual targets have names on the form
5937 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
5938 of the name and has no syntactical significance.
5939
5940 The :term:`PREFERRED_PROVIDER` variable is
5941 used to select which particular recipe provides a virtual target.
5942
5943 .. note::
5944
5945 A corresponding mechanism for virtual runtime dependencies
5946 (packages) exists. However, the mechanism does not depend on any
5947 special functionality beyond ordinary variable assignments. For
5948 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of
5949 the component that manages the ``/dev`` directory.
5950
5951 Setting the "preferred provider" for runtime dependencies is as
Andrew Geisslerc926e172021-05-07 16:11:35 -05005952 simple as using the following assignment in a configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005953
5954 VIRTUAL-RUNTIME_dev_manager = "udev"
5955
5956
Andrew Geisslerf0343792020-11-18 10:42:21 -06005957 :term:`PRSERV_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005958 The network based :term:`PR` service host and port.
5959
5960 The ``conf/local.conf.sample.extended`` configuration file in the
5961 :term:`Source Directory` shows how the
Andrew Geissler09036742021-06-25 14:25:14 -05005962 :term:`PRSERV_HOST` variable is set::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005963
5964 PRSERV_HOST = "localhost:0"
5965
5966 You must
5967 set the variable if you want to automatically start a local :ref:`PR
Andrew Geissler09209ee2020-12-13 08:44:15 -06005968 service <dev-manual/common-tasks:working with a pr service>`. You can
Andrew Geissler09036742021-06-25 14:25:14 -05005969 set :term:`PRSERV_HOST` to other values to use a remote PR service.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005970
Andrew Geissler6ce62a22020-11-30 19:58:47 -06005971
5972 :term:`PSEUDO_IGNORE_PATHS`
5973 A comma-separated (without spaces) list of path prefixes that should be ignored
5974 by pseudo when monitoring and recording file operations, in order to avoid
5975 problems with files being written to outside of the pseudo context and
5976 reduce pseudo's overhead. A path is ignored if it matches any prefix in the list
5977 and can include partial directory (or file) names.
5978
5979
Andrew Geisslerf0343792020-11-18 10:42:21 -06005980 :term:`PTEST_ENABLED`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005981 Specifies whether or not :ref:`Package
Andrew Geissler09209ee2020-12-13 08:44:15 -06005982 Test <dev-manual/common-tasks:testing packages with ptest>` (ptest)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005983 functionality is enabled when building a recipe. You should not set
5984 this variable directly. Enabling and disabling building Package Tests
5985 at build time should be done by adding "ptest" to (or removing it
5986 from) :term:`DISTRO_FEATURES`.
5987
Andrew Geisslerf0343792020-11-18 10:42:21 -06005988 :term:`PV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005989 The version of the recipe. The version is normally extracted from the
5990 recipe filename. For example, if the recipe is named
Andrew Geissler09036742021-06-25 14:25:14 -05005991 ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1".
5992 :term:`PV` is generally not overridden within a recipe unless it is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005993 building an unstable (i.e. development) version from a source code
5994 repository (e.g. Git or Subversion).
5995
Andrew Geissler09036742021-06-25 14:25:14 -05005996 :term:`PV` is the default value of the :term:`PKGV` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005997
Andrew Geisslerf0343792020-11-18 10:42:21 -06005998 :term:`PYTHON_ABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05005999 When used by recipes that inherit the
6000 :ref:`distutils3 <ref-classes-distutils3>`,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006001 :ref:`setuptools3 <ref-classes-setuptools3>` classes, denotes the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006002 Application Binary Interface (ABI) currently in use for Python. By
6003 default, the ABI is "m". You do not have to set this variable as the
6004 OpenEmbedded build system sets it for you.
6005
6006 The OpenEmbedded build system uses the ABI to construct directory
6007 names used when installing the Python headers and libraries in
6008 sysroot (e.g. ``.../python3.3m/...``).
6009
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006010 Recipes that inherit the ``distutils3`` class during cross-builds also
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006011 use this variable to locate the headers and libraries of the
6012 appropriate Python that the extension is targeting.
6013
Andrew Geisslerf0343792020-11-18 10:42:21 -06006014 :term:`PYTHON_PN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006015 When used by recipes that inherit the
6016 `distutils3 <ref-classes-distutils3>`,
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006017 :ref:`setuptools3 <ref-classes-setuptools3>` classes, specifies the
Andrew Geissler09036742021-06-25 14:25:14 -05006018 major Python version being built. For Python 3.x, :term:`PYTHON_PN` would
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006019 be "python3". You do not have to set this variable as the
6020 OpenEmbedded build system automatically sets it for you.
6021
6022 The variable allows recipes to use common infrastructure such as the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006023 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006024
6025 DEPENDS += "${PYTHON_PN}-native"
6026
6027 In the previous example,
Andrew Geissler09036742021-06-25 14:25:14 -05006028 the version of the dependency is :term:`PYTHON_PN`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006029
Andrew Geisslerf0343792020-11-18 10:42:21 -06006030 :term:`RANLIB`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006031 The minimal command and arguments to run ``ranlib``.
6032
Andrew Geisslerf0343792020-11-18 10:42:21 -06006033 :term:`RCONFLICTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006034 The list of packages that conflict with packages. Note that packages
6035 will not be installed if conflicting packages are not first removed.
6036
6037 Like all package-controlling variables, you must always use them in
Andrew Geisslerc926e172021-05-07 16:11:35 -05006038 conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006039
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006040 RCONFLICTS:${PN} = "another_conflicting_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006041
6042 BitBake, which the OpenEmbedded build system uses, supports
6043 specifying versioned dependencies. Although the syntax varies
6044 depending on the packaging format, BitBake hides these differences
6045 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006046 :term:`RCONFLICTS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006047
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006048 RCONFLICTS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006049
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006050 For ``operator``, you can specify the following:
6051
6052 - =
6053 - <
6054 - >
6055 - <=
6056 - >=
6057
6058 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006059 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006060
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006061 RCONFLICTS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006062
Andrew Geisslerf0343792020-11-18 10:42:21 -06006063 :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006064 Lists runtime dependencies of a package. These dependencies are other
6065 packages that must be installed in order for the package to function
6066 correctly. As an example, the following assignment declares that the
6067 package ``foo`` needs the packages ``bar`` and ``baz`` to be
Andrew Geisslerc926e172021-05-07 16:11:35 -05006068 installed::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006069
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006070 RDEPENDS:foo = "bar baz"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006071
6072 The most common types of package
6073 runtime dependencies are automatically detected and added. Therefore,
Andrew Geissler09036742021-06-25 14:25:14 -05006074 most recipes do not need to set :term:`RDEPENDS`. For more information,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006075 see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006076 ":ref:`overview-manual/concepts:automatically added runtime dependencies`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006077 section in the Yocto Project Overview and Concepts Manual.
6078
Andrew Geissler09036742021-06-25 14:25:14 -05006079 The practical effect of the above :term:`RDEPENDS` assignment is that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006080 ``bar`` and ``baz`` will be declared as dependencies inside the
6081 package ``foo`` when it is written out by one of the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006082 :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006083 Exactly how this is done depends on which package format is used,
6084 which is determined by
6085 :term:`PACKAGE_CLASSES`. When the
6086 corresponding package manager installs the package, it will know to
6087 also install the packages on which it depends.
6088
6089 To ensure that the packages ``bar`` and ``baz`` get built, the
Andrew Geissler09036742021-06-25 14:25:14 -05006090 previous :term:`RDEPENDS` assignment also causes a task dependency to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006091 added. This dependency is from the recipe's
6092 :ref:`ref-tasks-build` (not to be confused with
6093 :ref:`ref-tasks-compile`) task to the
6094 ``do_package_write_*`` task of the recipes that build ``bar`` and
6095 ``baz``.
6096
Andrew Geissler09036742021-06-25 14:25:14 -05006097 The names of the packages you list within :term:`RDEPENDS` must be the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006098 names of other packages - they cannot be recipe names. Although
6099 package names and recipe names usually match, the important point
Andrew Geissler09036742021-06-25 14:25:14 -05006100 here is that you are providing package names within the :term:`RDEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006101 variable. For an example of the default list of packages created from
6102 a recipe, see the :term:`PACKAGES` variable.
6103
Andrew Geissler09036742021-06-25 14:25:14 -05006104 Because the :term:`RDEPENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006105 you should always use the variable in a form with an attached package
6106 name (remember that a single recipe can build multiple packages). For
6107 example, suppose you are building a development package that depends
6108 on the ``perl`` package. In this case, you would use the following
Andrew Geissler09036742021-06-25 14:25:14 -05006109 :term:`RDEPENDS` statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006110
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006111 RDEPENDS:${PN}-dev += "perl"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006112
6113 In the example,
6114 the development package depends on the ``perl`` package. Thus, the
Andrew Geissler5f350902021-07-23 13:09:54 -04006115 :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006116 the variable.
6117
6118 .. note::
6119
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006120 ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006121 by default. This default is set in the BitBake configuration file
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006122 (``meta/conf/bitbake.conf``). Be careful not to accidentally remove
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006123 ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006124 rather than the "=" operator.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006125
Andrew Geissler09036742021-06-25 14:25:14 -05006126 The package names you use with :term:`RDEPENDS` must appear as they would
6127 in the :term:`PACKAGES` variable. The :term:`PKG` variable
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006128 allows a different name to be used for the final package (e.g. the
6129 :ref:`debian <ref-classes-debian>` class uses this to rename
6130 packages), but this final package name cannot be used with
Andrew Geissler09036742021-06-25 14:25:14 -05006131 :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006132 independent of the package format used.
6133
6134 BitBake, which the OpenEmbedded build system uses, supports
6135 specifying versioned dependencies. Although the syntax varies
6136 depending on the packaging format, BitBake hides these differences
6137 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006138 :term:`RDEPENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006139
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006140 RDEPENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006141
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006142 For ``operator``, you can specify the following:
6143
6144 - =
6145 - <
6146 - >
6147 - <=
6148 - >=
6149
6150 For version, provide the version number.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006151
6152 .. note::
6153
Andrew Geissler09036742021-06-25 14:25:14 -05006154 You can use :term:`EXTENDPKGV` to provide a full package version
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006155 specification.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006156
6157 For example, the following sets up a dependency on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006158 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006159
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006160 RDEPENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006161
6162 For information on build-time dependencies, see the
6163 :term:`DEPENDS` variable. You can also see the
Patrick Williams213cb262021-08-07 19:21:33 -05006164 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and
6165 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006166 BitBake User Manual for additional information on tasks and
6167 dependencies.
6168
Andrew Geissler5199d832021-09-24 16:47:35 -05006169 :term:`RECIPE_NO_UPDATE_REASON`
6170 If a recipe should not be replaced by a more recent upstream version,
6171 putting the reason why in this variable in a recipe allows
6172 ``devtool check-upgrade-status`` command to display it, as explained
6173 in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`"
6174 section.
6175
Andrew Geisslerf0343792020-11-18 10:42:21 -06006176 :term:`REQUIRED_DISTRO_FEATURES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006177 When inheriting the
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006178 :ref:`features_check <ref-classes-features_check>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006179 class, this variable identifies distribution features that must exist
6180 in the current configuration in order for the OpenEmbedded build
6181 system to build the recipe. In other words, if the
Andrew Geissler09036742021-06-25 14:25:14 -05006182 :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not
6183 appear in :term:`DISTRO_FEATURES` within the current configuration, then
Andrew Geissler6ce62a22020-11-30 19:58:47 -06006184 the recipe will be skipped, and if the build system attempts to build
6185 the recipe then an error will be triggered.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006186
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006187 :term:`REQUIRED_VERSION`
6188 If there are multiple versions of a recipe available, this variable
6189 determines which version should be given preference.
6190 :term:`REQUIRED_VERSION` works in exactly the same manner as
6191 :term:`PREFERRED_VERSION`, except that if the specified version is not
6192 available then an error message is shown and the build fails
6193 immediately.
6194
6195 If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set
6196 for the same recipe, the :term:`REQUIRED_VERSION` value applies.
6197
Andrew Geisslerf0343792020-11-18 10:42:21 -06006198 :term:`RM_WORK_EXCLUDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006199 With ``rm_work`` enabled, this variable specifies a list of recipes
6200 whose work directories should not be removed. See the
6201 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more
6202 details.
6203
Andrew Geisslerf0343792020-11-18 10:42:21 -06006204 :term:`ROOT_HOME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006205 Defines the root home directory. By default, this directory is set as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006206 follows in the BitBake configuration file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006207
6208 ROOT_HOME ??= "/home/root"
6209
6210 .. note::
6211
6212 This default value is likely used because some embedded solutions
6213 prefer to have a read-only root filesystem and prefer to keep
6214 writeable data in one place.
6215
6216 You can override the default by setting the variable in any layer or
6217 in the ``local.conf`` file. Because the default is set using a "weak"
6218 assignment (i.e. "??="), you can use either of the following forms to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006219 define your override::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006220
6221 ROOT_HOME = "/root"
6222 ROOT_HOME ?= "/root"
6223
6224 These
6225 override examples use ``/root``, which is probably the most commonly
6226 used override.
6227
Andrew Geisslerf0343792020-11-18 10:42:21 -06006228 :term:`ROOTFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006229 Indicates a filesystem image to include as the root filesystem.
6230
Andrew Geissler09036742021-06-25 14:25:14 -05006231 The :term:`ROOTFS` variable is an optional variable used with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006232 :ref:`image-live <ref-classes-image-live>` class.
6233
Andrew Geisslerf0343792020-11-18 10:42:21 -06006234 :term:`ROOTFS_POSTINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006235 Specifies a list of functions to call after the OpenEmbedded build
6236 system has installed packages. You can specify functions separated by
Andrew Geisslerc926e172021-05-07 16:11:35 -05006237 semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006238
6239 ROOTFS_POSTINSTALL_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:`ROOTFS_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006248 Specifies a list of functions to call once the OpenEmbedded build
6249 system has created the root filesystem. You can specify functions
Andrew Geisslerc926e172021-05-07 16:11:35 -05006250 separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006251
6252 ROOTFS_POSTPROCESS_COMMAND += "function; ... "
6253
6254 If you need to pass the root filesystem path to a command within a
6255 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6256 directory that becomes the root filesystem image. See the
6257 :term:`IMAGE_ROOTFS` variable for more
6258 information.
6259
Andrew Geisslerf0343792020-11-18 10:42:21 -06006260 :term:`ROOTFS_POSTUNINSTALL_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006261 Specifies a list of functions to call after the OpenEmbedded build
6262 system has removed unnecessary packages. When runtime package
6263 management is disabled in the image, several packages are removed
6264 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
Andrew Geisslerc926e172021-05-07 16:11:35 -05006265 You can specify functions separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006266
6267 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... "
6268
6269 If you need to pass the root filesystem path to a command within a
6270 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6271 directory that becomes the root filesystem image. See the
6272 :term:`IMAGE_ROOTFS` variable for more
6273 information.
6274
Andrew Geisslerf0343792020-11-18 10:42:21 -06006275 :term:`ROOTFS_PREPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006276 Specifies a list of functions to call before the OpenEmbedded build
6277 system has created the root filesystem. You can specify functions
Andrew Geisslerc926e172021-05-07 16:11:35 -05006278 separated by semicolons::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006279
6280 ROOTFS_PREPROCESS_COMMAND += "function; ... "
6281
6282 If you need to pass the root filesystem path to a command within a
6283 function, you can use ``${IMAGE_ROOTFS}``, which points to the
6284 directory that becomes the root filesystem image. See the
6285 :term:`IMAGE_ROOTFS` variable for more
6286 information.
6287
Andrew Geisslerf0343792020-11-18 10:42:21 -06006288 :term:`RPROVIDES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006289 A list of package name aliases that a package also provides. These
6290 aliases are useful for satisfying runtime dependencies of other
6291 packages both during the build and on the target (as specified by
Andrew Geissler09036742021-06-25 14:25:14 -05006292 :term:`RDEPENDS`).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006293
6294 .. note::
6295
Andrew Geissler09036742021-06-25 14:25:14 -05006296 A package's own name is implicitly already in its :term:`RPROVIDES` list.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006297
6298 As with all package-controlling variables, you must always use the
6299 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05006300 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006301
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006302 RPROVIDES:${PN} = "widget-abi-2"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006303
Andrew Geisslerf0343792020-11-18 10:42:21 -06006304 :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006305 A list of packages that extends the usability of a package being
6306 built. The package being built does not depend on this list of
6307 packages in order to successfully build, but rather uses them for
6308 extended usability. To specify runtime dependencies for packages, see
Andrew Geissler09036742021-06-25 14:25:14 -05006309 the :term:`RDEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006310
Andrew Geissler09036742021-06-25 14:25:14 -05006311 The package manager will automatically install the :term:`RRECOMMENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006312 list of packages when installing the built package. However, you can
6313 prevent listed packages from being installed by using the
6314 :term:`BAD_RECOMMENDATIONS`,
6315 :term:`NO_RECOMMENDATIONS`, and
6316 :term:`PACKAGE_EXCLUDE` variables.
6317
Andrew Geissler09036742021-06-25 14:25:14 -05006318 Packages specified in :term:`RRECOMMENDS` need not actually be produced.
William A. Kennington IIIac69b482021-06-02 12:28:27 -07006319 However, there must be a recipe providing each package, either
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006320 through the :term:`PACKAGES` or
6321 :term:`PACKAGES_DYNAMIC` variables or the
6322 :term:`RPROVIDES` variable, or an error will occur
6323 during the build. If such a recipe does exist and the package is not
6324 produced, the build continues without error.
6325
Andrew Geissler09036742021-06-25 14:25:14 -05006326 Because the :term:`RRECOMMENDS` variable applies to packages being built,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006327 you should always attach an override to the variable to specify the
6328 particular package whose usability is being extended. For example,
6329 suppose you are building a development package that is extended to
6330 support wireless functionality. In this case, you would use the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006331 following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006332
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006333 RRECOMMENDS:${PN}-dev += "wireless_package_name"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006334
6335 In the
6336 example, the package name (``${PN}-dev``) must appear as it would in
Andrew Geissler09036742021-06-25 14:25:14 -05006337 the :term:`PACKAGES` namespace before any renaming of the output package
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006338 by classes such as ``debian.bbclass``.
6339
6340 BitBake, which the OpenEmbedded build system uses, supports
6341 specifying versioned recommends. Although the syntax varies depending
6342 on the packaging format, BitBake hides these differences from you.
6343 Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006344 :term:`RRECOMMENDS` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006345
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006346 RRECOMMENDS:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006347
6348 For ``operator``, you can specify the following:
6349
6350 - =
6351 - <
6352 - >
6353 - <=
6354 - >=
6355
6356 For example, the following sets up a recommend on version 1.2 or
Andrew Geisslerc926e172021-05-07 16:11:35 -05006357 greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006358
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006359 RRECOMMENDS:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006360
Andrew Geisslerf0343792020-11-18 10:42:21 -06006361 :term:`RREPLACES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006362 A list of packages replaced by a package. The package manager uses
6363 this variable to determine which package should be installed to
6364 replace other package(s) during an upgrade. In order to also have the
6365 other package(s) removed at the same time, you must add the name of
Andrew Geissler09036742021-06-25 14:25:14 -05006366 the other package to the :term:`RCONFLICTS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006367
6368 As with all package-controlling variables, you must use this variable
Andrew Geisslerc926e172021-05-07 16:11:35 -05006369 in conjunction with a package name override. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006370
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006371 RREPLACES:${PN} = "other_package_being_replaced"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006372
6373 BitBake, which the OpenEmbedded build system uses, supports
6374 specifying versioned replacements. Although the syntax varies
6375 depending on the packaging format, BitBake hides these differences
6376 from you. Here is the general syntax to specify versions with the
Andrew Geissler09036742021-06-25 14:25:14 -05006377 :term:`RREPLACES` variable::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006378
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006379 RREPLACES:${PN} = "package (operator version)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006380
6381 For ``operator``, you can specify the following:
6382
6383 - =
6384 - <
6385 - >
6386 - <=
6387 - >=
6388
6389 For example, the following sets up a replacement using version 1.2
Andrew Geisslerc926e172021-05-07 16:11:35 -05006390 or greater of the package ``foo``::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006391
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006392 RREPLACES:${PN} = "foo (>= 1.2)"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006393
Andrew Geisslerf0343792020-11-18 10:42:21 -06006394 :term:`RSUGGESTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006395 A list of additional packages that you can suggest for installation
6396 by the package manager at the time a package is installed. Not all
6397 package managers support this functionality.
6398
6399 As with all package-controlling variables, you must always use this
6400 variable in conjunction with a package name override. Here is an
Andrew Geisslerc926e172021-05-07 16:11:35 -05006401 example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006402
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006403 RSUGGESTS:${PN} = "useful_package another_package"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006404
Andrew Geisslerf0343792020-11-18 10:42:21 -06006405 :term:`S`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006406 The location in the :term:`Build Directory` where
6407 unpacked recipe source code resides. By default, this directory is
6408 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
6409 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
6410 version. If the source tarball extracts the code to a directory named
6411 anything other than ``${BPN}-${PV}``, or if the source code is
6412 fetched from an SCM such as Git or Subversion, then you must set
Andrew Geissler09036742021-06-25 14:25:14 -05006413 :term:`S` in the recipe so that the OpenEmbedded build system knows where
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006414 to find the unpacked source.
6415
6416 As an example, assume a :term:`Source Directory`
6417 top-level folder named ``poky`` and a default Build Directory at
6418 ``poky/build``. In this case, the work directory the build system
Andrew Geisslerc926e172021-05-07 16:11:35 -05006419 uses to keep the unpacked recipe for ``db`` is the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006420
6421 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6422
6423 The unpacked source code resides in the ``db-5.1.19`` folder.
6424
6425 This next example assumes a Git repository. By default, Git
6426 repositories are cloned to ``${WORKDIR}/git`` during
6427 :ref:`ref-tasks-fetch`. Since this path is different
Andrew Geissler09036742021-06-25 14:25:14 -05006428 from the default value of :term:`S`, you must set it specifically so the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006429 source can be located::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006430
6431 SRC_URI = "git://path/to/repo.git"
6432 S = "${WORKDIR}/git"
6433
Andrew Geisslerf0343792020-11-18 10:42:21 -06006434 :term:`SANITY_REQUIRED_UTILITIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006435 Specifies a list of command-line utilities that should be checked for
6436 during the initial sanity checking process when running BitBake. If
6437 any of the utilities are not installed on the build host, then
6438 BitBake immediately exits with an error.
6439
Andrew Geisslerf0343792020-11-18 10:42:21 -06006440 :term:`SANITY_TESTED_DISTROS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006441 A list of the host distribution identifiers that the build system has
6442 been tested against. Identifiers consist of the host distributor ID
6443 followed by the release, as reported by the ``lsb_release`` tool or
6444 as read from ``/etc/lsb-release``. Separate the list items with
Andrew Geissler09036742021-06-25 14:25:14 -05006445 explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006446 not empty and the current value of
6447 :term:`NATIVELSBSTRING` does not appear in the
6448 list, then the build system reports a warning that indicates the
6449 current host distribution has not been tested as a build host.
6450
Andrew Geisslerf0343792020-11-18 10:42:21 -06006451 :term:`SDK_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006452 The target architecture for the SDK. Typically, you do not directly
6453 set this variable. Instead, use :term:`SDKMACHINE`.
6454
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006455 :term:`SDK_CUSTOM_TEMPLATECONF`
Andrew Geissler09036742021-06-25 14:25:14 -05006456 When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006457 "1" and a ``conf/templateconf.conf`` file exists in the build directory
6458 (:term:`TOPDIR`) then this will be copied into the SDK.
6459
Andrew Geisslerf0343792020-11-18 10:42:21 -06006460 :term:`SDK_DEPLOY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006461 The directory set up and used by the
6462 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
6463 the SDK is deployed. The ``populate_sdk_base`` class defines
Andrew Geissler09036742021-06-25 14:25:14 -05006464 :term:`SDK_DEPLOY` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006465
6466 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
6467
Andrew Geisslerf0343792020-11-18 10:42:21 -06006468 :term:`SDK_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006469 The parent directory used by the OpenEmbedded build system when
6470 creating SDK output. The
6471 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
Andrew Geisslerc926e172021-05-07 16:11:35 -05006472 the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006473
6474 SDK_DIR = "${WORKDIR}/sdk"
6475
6476 .. note::
6477
Andrew Geissler09036742021-06-25 14:25:14 -05006478 The :term:`SDK_DIR` directory is a temporary directory as it is part of
6479 :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006480
Andrew Geisslerf0343792020-11-18 10:42:21 -06006481 :term:`SDK_EXT_TYPE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006482 Controls whether or not shared state artifacts are copied into the
6483 extensible SDK. The default value of "full" copies all of the
6484 required shared state artifacts into the extensible SDK. The value
6485 "minimal" leaves these artifacts out of the SDK.
6486
6487 .. note::
6488
6489 If you set the variable to "minimal", you need to ensure
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006490 :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the
6491 artifacts to be fetched as needed.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006492
Andrew Geisslerf0343792020-11-18 10:42:21 -06006493 :term:`SDK_HOST_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006494 The manifest file for the host part of the SDK. This file lists all
6495 the installed packages that make up the host part of the SDK. The
6496 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006497 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006498
6499 packagename packagearch version
6500
6501 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05006502 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006503
6504 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
6505
6506 The location is derived using the :term:`SDK_DEPLOY` and
6507 :term:`TOOLCHAIN_OUTPUTNAME` variables.
6508
Andrew Geisslerf0343792020-11-18 10:42:21 -06006509 :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006510 When set to "1", specifies to include the packagedata for all recipes
6511 in the "world" target in the extensible SDK. Including this data
6512 allows the ``devtool search`` command to find these recipes in search
6513 results, as well as allows the ``devtool add`` command to map
6514 dependencies more effectively.
6515
6516 .. note::
6517
Andrew Geissler09036742021-06-25 14:25:14 -05006518 Enabling the :term:`SDK_INCLUDE_PKGDATA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006519 variable significantly increases build time because all of world
6520 needs to be built. Enabling the variable also slightly increases
6521 the size of the extensible SDK.
6522
Andrew Geisslerf0343792020-11-18 10:42:21 -06006523 :term:`SDK_INCLUDE_TOOLCHAIN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006524 When set to "1", specifies to include the toolchain in the extensible
6525 SDK. Including the toolchain is useful particularly when
6526 :term:`SDK_EXT_TYPE` is set to "minimal" to keep
6527 the SDK reasonably small but you still want to provide a usable
6528 toolchain. For example, suppose you want to use the toolchain from an
6529 IDE or from other tools and you do not want to perform additional
6530 steps to install the toolchain.
6531
Andrew Geissler09036742021-06-25 14:25:14 -05006532 The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if
6533 :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
6534 :term:`SDK_EXT_TYPE` is set to "full".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006535
Andrew Geisslerf0343792020-11-18 10:42:21 -06006536 :term:`SDK_INHERIT_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006537 A list of classes to remove from the :term:`INHERIT`
6538 value globally within the extensible SDK configuration. The
6539 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
Andrew Geisslerc926e172021-05-07 16:11:35 -05006540 default value::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006541
6542 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
6543
6544 Some classes are not generally applicable within the extensible SDK
6545 context. You can use this variable to disable those classes.
6546
6547 For additional information on how to customize the extensible SDK's
6548 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006549 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006550 section in the Yocto Project Application Development and the
6551 Extensible Software Development Kit (eSDK) manual.
6552
Andrew Geisslerf0343792020-11-18 10:42:21 -06006553 :term:`SDK_LOCAL_CONF_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006554 A list of variables not allowed through from the OpenEmbedded build
6555 system configuration into the extensible SDK configuration. Usually,
6556 these are variables that are specific to the machine on which the
6557 build system is running and thus would be potentially problematic
6558 within the extensible SDK.
6559
Andrew Geissler09036742021-06-25 14:25:14 -05006560 By default, :term:`SDK_LOCAL_CONF_BLACKLIST` is set in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006561 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
6562 excludes the following variables:
6563
6564 - :term:`CONF_VERSION`
6565 - :term:`BB_NUMBER_THREADS`
Patrick Williams213cb262021-08-07 19:21:33 -05006566 - :term:`BB_NUMBER_PARSE_THREADS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006567 - :term:`PARALLEL_MAKE`
6568 - :term:`PRSERV_HOST`
6569 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
6570 - :term:`SSTATE_DIR` :term:`TMPDIR`
6571 - :term:`BB_SERVER_TIMEOUT`
6572
6573 For additional information on how to customize the extensible SDK's
6574 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006575 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006576 section in the Yocto Project Application Development and the
6577 Extensible Software Development Kit (eSDK) manual.
6578
Andrew Geisslerf0343792020-11-18 10:42:21 -06006579 :term:`SDK_LOCAL_CONF_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006580 A list of variables allowed through from the OpenEmbedded build
6581 system configuration into the extensible SDK configuration. By
6582 default, the list of variables is empty and is set in the
6583 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
6584
6585 This list overrides the variables specified using the
6586 :term:`SDK_LOCAL_CONF_BLACKLIST`
6587 variable as well as any variables identified by automatic
6588 blacklisting due to the "/" character being found at the start of the
6589 value, which is usually indicative of being a path and thus might not
6590 be valid on the system where the SDK is installed.
6591
6592 For additional information on how to customize the extensible SDK's
6593 configuration, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006594 ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006595 section in the Yocto Project Application Development and the
6596 Extensible Software Development Kit (eSDK) manual.
6597
Andrew Geisslerf0343792020-11-18 10:42:21 -06006598 :term:`SDK_NAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006599 The base name for SDK output files. The name is derived from the
6600 :term:`DISTRO`, :term:`TCLIBC`,
6601 :term:`SDK_ARCH`,
6602 :term:`IMAGE_BASENAME`, and
Andrew Geisslerc926e172021-05-07 16:11:35 -05006603 :term:`TUNE_PKGARCH` variables::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006604
6605 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6606
Andrew Geisslerf0343792020-11-18 10:42:21 -06006607 :term:`SDK_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006608 Specifies the operating system for which the SDK will be built. The
6609 default value is the value of :term:`BUILD_OS`.
6610
Andrew Geisslerf0343792020-11-18 10:42:21 -06006611 :term:`SDK_OUTPUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006612 The location used by the OpenEmbedded build system when creating SDK
6613 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
Andrew Geisslerc926e172021-05-07 16:11:35 -05006614 class defines the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006615
6616 SDK_DIR = "${WORKDIR}/sdk"
6617 SDK_OUTPUT = "${SDK_DIR}/image"
6618 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
6619
6620 .. note::
6621
Andrew Geissler09036742021-06-25 14:25:14 -05006622 The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006623 :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is
6624 :term:`SDK_DEPLOY`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006625
Andrew Geisslerf0343792020-11-18 10:42:21 -06006626 :term:`SDK_PACKAGE_ARCHS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006627 Specifies a list of architectures compatible with the SDK machine.
6628 This variable is set automatically and should not normally be
6629 hand-edited. Entries are separated using spaces and listed in order
Andrew Geissler09036742021-06-25 14:25:14 -05006630 of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006631 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
6632
Andrew Geisslerf0343792020-11-18 10:42:21 -06006633 :term:`SDK_POSTPROCESS_COMMAND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006634 Specifies a list of functions to call once the OpenEmbedded build
6635 system creates the SDK. You can specify functions separated by
6636 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... "
6637
6638 If you need to pass an SDK path to a command within a function, you
6639 can use ``${SDK_DIR}``, which points to the parent directory used by
6640 the OpenEmbedded build system when creating SDK output. See the
6641 :term:`SDK_DIR` variable for more information.
6642
Andrew Geisslerf0343792020-11-18 10:42:21 -06006643 :term:`SDK_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006644 The toolchain binary prefix used for ``nativesdk`` recipes. The
Andrew Geissler09036742021-06-25 14:25:14 -05006645 OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006646 :term:`TARGET_PREFIX` when building
6647 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
6648
Andrew Geisslerf0343792020-11-18 10:42:21 -06006649 :term:`SDK_RECRDEP_TASKS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006650 A list of shared state tasks added to the extensible SDK. By default,
6651 the following tasks are added:
6652
6653 - do_populate_lic
6654 - do_package_qa
6655 - do_populate_sysroot
6656 - do_deploy
6657
6658 Despite the default value of "" for the
Andrew Geissler09036742021-06-25 14:25:14 -05006659 :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006660 to the SDK. To specify tasks beyond these four, you need to use the
Andrew Geissler09036742021-06-25 14:25:14 -05006661 :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006662 tasks that are needed in order to build
6663 :term:`SDK_TARGETS`).
6664
Andrew Geisslerf0343792020-11-18 10:42:21 -06006665 :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006666 Specifies the system, including the architecture and the operating
6667 system, for which the SDK will be built.
6668
6669 The OpenEmbedded build system automatically sets this variable based
6670 on :term:`SDK_ARCH`,
6671 :term:`SDK_VENDOR`, and
Andrew Geissler09036742021-06-25 14:25:14 -05006672 :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006673 variable yourself.
6674
Andrew Geisslerf0343792020-11-18 10:42:21 -06006675 :term:`SDK_TARGET_MANIFEST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006676 The manifest file for the target part of the SDK. This file lists all
6677 the installed packages that make up the target part of the SDK. The
6678 file contains package information on a line-per-package basis as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006679 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006680
6681 packagename packagearch version
6682
6683 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
Andrew Geisslerc926e172021-05-07 16:11:35 -05006684 defines the manifest file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006685
6686 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
6687
6688 The location is derived using the :term:`SDK_DEPLOY` and
6689 :term:`TOOLCHAIN_OUTPUTNAME` variables.
6690
Andrew Geisslerf0343792020-11-18 10:42:21 -06006691 :term:`SDK_TARGETS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006692 A list of targets to install from shared state as part of the
6693 standard or extensible SDK installation. The default value is "${PN}"
6694 (i.e. the image from which the SDK is built).
6695
Andrew Geissler09036742021-06-25 14:25:14 -05006696 The :term:`SDK_TARGETS` variable is an internal variable and typically
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006697 would not be changed.
6698
Andrew Geisslerf0343792020-11-18 10:42:21 -06006699 :term:`SDK_TITLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006700 The title to be printed when running the SDK installer. By default,
6701 this title is based on the :term:`DISTRO_NAME` or
6702 :term:`DISTRO` variable and is set in the
6703 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006704 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006705
6706 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
6707
6708 For the default distribution "poky",
Andrew Geissler09036742021-06-25 14:25:14 -05006709 :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006710
6711 For information on how to change this default title, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006712 ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006713 section in the Yocto Project Application Development and the
6714 Extensible Software Development Kit (eSDK) manual.
6715
Andrew Geisslerf0343792020-11-18 10:42:21 -06006716 :term:`SDK_UPDATE_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006717 An optional URL for an update server for the extensible SDK. If set,
6718 the value is used as the default update server when running
6719 ``devtool sdk-update`` within the extensible SDK.
6720
Andrew Geisslerf0343792020-11-18 10:42:21 -06006721 :term:`SDK_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006722 Specifies the name of the SDK vendor.
6723
Andrew Geisslerf0343792020-11-18 10:42:21 -06006724 :term:`SDK_VERSION`
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006725 Specifies the version of the SDK. The Poky distribution configuration file
6726 (``/meta-poky/conf/distro/poky.conf``) sets the default
Andrew Geissler09036742021-06-25 14:25:14 -05006727 :term:`SDK_VERSION` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006728
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006729 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006730
6731 For additional information, see the
6732 :term:`DISTRO_VERSION` and
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05006733 :term:`METADATA_REVISION` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006734
Andrew Geisslerf0343792020-11-18 10:42:21 -06006735 :term:`SDKEXTPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006736 The default installation directory for the Extensible SDK. By
6737 default, this directory is based on the :term:`DISTRO`
6738 variable and is set in the
6739 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
Andrew Geisslerc926e172021-05-07 16:11:35 -05006740 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006741
6742 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
6743
6744 For the
Andrew Geissler09036742021-06-25 14:25:14 -05006745 default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006746
6747 For information on how to change this default directory, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06006748 ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006749 section in the Yocto Project Application Development and the
6750 Extensible Software Development Kit (eSDK) manual.
6751
Andrew Geisslerf0343792020-11-18 10:42:21 -06006752 :term:`SDKIMAGE_FEATURES`
Andrew Geissler09036742021-06-25 14:25:14 -05006753 Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to
Andrew Geisslerc926e172021-05-07 16:11:35 -05006754 the SDK generated from an image using the following command::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006755
6756 $ bitbake -c populate_sdk imagename
6757
Andrew Geisslerf0343792020-11-18 10:42:21 -06006758 :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006759 The machine for which the SDK is built. In other words, the SDK is
6760 built such that it runs on the target you specify with the
Andrew Geissler09036742021-06-25 14:25:14 -05006761 :term:`SDKMACHINE` value. The value points to a corresponding ``.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006762 file under ``conf/machine-sdk/``.
6763
6764 You can use "i686" and "x86_64" as possible values for this variable.
6765 The variable defaults to "i686" and is set in the local.conf file in
6766 the Build Directory.
6767 ::
6768
6769 SDKMACHINE ?= "i686"
6770
6771 .. note::
6772
Andrew Geissler09036742021-06-25 14:25:14 -05006773 You cannot set the :term:`SDKMACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006774 variable in your distribution configuration file. If you do, the
6775 configuration will not take affect.
6776
Andrew Geisslerf0343792020-11-18 10:42:21 -06006777 :term:`SDKPATH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006778 Defines the path offered to the user for installation of the SDK that
6779 is generated by the OpenEmbedded build system. The path appears as
6780 the default location for installing the SDK when you run the SDK's
6781 installation script. You can override the offered path when you run
6782 the script.
6783
Andrew Geisslerf0343792020-11-18 10:42:21 -06006784 :term:`SDKTARGETSYSROOT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006785 The full path to the sysroot used for cross-compilation within an SDK
6786 as it will be when installed into the default
6787 :term:`SDKPATH`.
6788
Andrew Geisslerf0343792020-11-18 10:42:21 -06006789 :term:`SECTION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006790 The section in which packages should be categorized. Package
6791 management utilities can make use of this variable.
6792
Andrew Geisslerf0343792020-11-18 10:42:21 -06006793 :term:`SELECTED_OPTIMIZATION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006794 Specifies the optimization flags passed to the C compiler when
6795 building for the target. The flags are passed through the default
6796 value of the :term:`TARGET_CFLAGS` variable.
6797
Andrew Geissler09036742021-06-25 14:25:14 -05006798 The :term:`SELECTED_OPTIMIZATION` variable takes the value of
William A. Kennington IIIac69b482021-06-02 12:28:27 -07006799 :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which
6800 case the value of :term:`DEBUG_OPTIMIZATION` is used.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006801
Andrew Geisslerf0343792020-11-18 10:42:21 -06006802 :term:`SERIAL_CONSOLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006803 Defines a serial console (TTY) to enable using
6804 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6805 value that specifies the baud rate followed by the TTY device name
Andrew Geisslerc926e172021-05-07 16:11:35 -05006806 separated by a space. You cannot specify more than one TTY device::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006807
6808 SERIAL_CONSOLE = "115200 ttyS0"
6809
6810 .. note::
6811
Andrew Geissler09036742021-06-25 14:25:14 -05006812 The :term:`SERIAL_CONSOLE` variable is deprecated. Please use the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006813 :term:`SERIAL_CONSOLES` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006814
Andrew Geisslerf0343792020-11-18 10:42:21 -06006815 :term:`SERIAL_CONSOLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006816 Defines a serial console (TTY) to enable using
6817 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6818 value that specifies the baud rate followed by the TTY device name
Andrew Geisslerc926e172021-05-07 16:11:35 -05006819 separated by a semicolon. Use spaces to separate multiple devices::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006820
6821 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6822
Andrew Geisslerf0343792020-11-18 10:42:21 -06006823 :term:`SERIAL_CONSOLES_CHECK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006824 Specifies serial consoles, which must be listed in
6825 :term:`SERIAL_CONSOLES`, to check against
6826 ``/proc/console`` before enabling them using getty. This variable
6827 allows aliasing in the format: <device>:<alias>. If a device was
6828 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in
Andrew Geisslerc926e172021-05-07 16:11:35 -05006829 ``/proc/console``, you would do the following::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006830
6831 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
6832
6833 This variable is currently only supported with SysVinit (i.e. not
Andrew Geisslerc926e172021-05-07 16:11:35 -05006834 with systemd). Note that :term:`SERIAL_CONSOLES_CHECK` also requires
6835 ``/etc/inittab`` to be writable when used with SysVinit. This makes it
6836 incompatible with customizations such as the following::
6837
6838 EXTRA_IMAGE_FEATURES += "read-only-rootfs"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006839
Andrew Geisslerf0343792020-11-18 10:42:21 -06006840 :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006841 A list of recipe dependencies that should not be used to determine
6842 signatures of tasks from one recipe when they depend on tasks from
Andrew Geisslerc926e172021-05-07 16:11:35 -05006843 another recipe. For example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006844
6845 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6846
6847 In the previous example, ``intone`` depends on ``mplayer2``.
6848
6849 You can use the special token ``"*"`` on the left-hand side of the
6850 dependency to match all recipes except the one on the right-hand
Andrew Geisslerc926e172021-05-07 16:11:35 -05006851 side. Here is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006852
6853 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
6854
6855 In the previous example, all recipes except ``quilt-native`` ignore
6856 task signatures from the ``quilt-native`` recipe when determining
6857 their task signatures.
6858
6859 Use of this variable is one mechanism to remove dependencies that
6860 affect task signatures and thus force rebuilds when a recipe changes.
6861
6862 .. note::
6863
6864 If you add an inappropriate dependency for a recipe relationship,
6865 the software might break during runtime if the interface of the
6866 second recipe was changed after the first recipe had been built.
6867
Andrew Geisslerf0343792020-11-18 10:42:21 -06006868 :term:`SIGGEN_EXCLUDERECIPES_ABISAFE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006869 A list of recipes that are completely stable and will never change.
6870 The ABI for the recipes in the list are presented by output from the
6871 tasks run to build the recipe. Use of this variable is one way to
6872 remove dependencies from one recipe on another that affect task
6873 signatures and thus force rebuilds when the recipe changes.
6874
6875 .. note::
6876
6877 If you add an inappropriate variable to this list, the software
6878 might break at runtime if the interface of the recipe was changed
6879 after the other had been built.
6880
Andrew Geisslerf0343792020-11-18 10:42:21 -06006881 :term:`SITEINFO_BITS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006882 Specifies the number of bits for the target system CPU. The value
6883 should be either "32" or "64".
6884
Andrew Geisslerf0343792020-11-18 10:42:21 -06006885 :term:`SITEINFO_ENDIANNESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006886 Specifies the endian byte order of the target system. The value
6887 should be either "le" for little-endian or "be" for big-endian.
6888
Andrew Geisslerf0343792020-11-18 10:42:21 -06006889 :term:`SKIP_FILEDEPS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006890 Enables removal of all files from the "Provides" section of an RPM
6891 package. Removal of these files is required for packages containing
6892 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
6893
6894 To enable file removal, set the variable to "1" in your
6895 ``conf/local.conf`` configuration file in your:
6896 :term:`Build Directory`.
6897 ::
6898
6899 SKIP_FILEDEPS = "1"
6900
Andrew Geisslerf0343792020-11-18 10:42:21 -06006901 :term:`SOC_FAMILY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006902 Groups together machines based upon the same family of SOC (System On
6903 Chip). You typically set this variable in a common ``.inc`` file that
6904 you include in the configuration files of all the machines.
6905
6906 .. note::
6907
Andrew Geissler4c19ea12020-10-27 13:52:24 -05006908 You must include ``conf/machine/include/soc-family.inc`` for this
6909 variable to appear in :term:`MACHINEOVERRIDES`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006910
Andrew Geisslerf0343792020-11-18 10:42:21 -06006911 :term:`SOLIBS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006912 Defines the suffix for shared libraries used on the target platform.
6913 By default, this suffix is ".so.*" for all Linux-based systems and is
6914 defined in the ``meta/conf/bitbake.conf`` configuration file.
6915
6916 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006917 ``FILES:${PN}``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006918
Andrew Geisslerf0343792020-11-18 10:42:21 -06006919 :term:`SOLIBSDEV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006920 Defines the suffix for the development symbolic link (symlink) for
6921 shared libraries on the target platform. By default, this suffix is
6922 ".so" for Linux-based systems and is defined in the
6923 ``meta/conf/bitbake.conf`` configuration file.
6924
6925 You will see this variable referenced in the default values of
Patrick Williams0ca19cc2021-08-16 14:03:13 -05006926 ``FILES:${PN}-dev``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006927
Andrew Geisslereff27472021-10-29 15:35:00 -05006928 :term:`SOURCE_DATE_EPOCH`
6929 This defines a date expressed in number of seconds since
6930 the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by
6931 multiple build systems to force a timestamp in built binaries.
6932 Many upstream projects already support this variable.
6933
6934 You will find more details in the `official specifications
6935 <https://reproducible-builds.org/specs/source-date-epoch/>`__.
6936
6937 A value for each recipe is computed from the sources by
6938 :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`.
6939
6940 If a recipe wishes to override the default behavior, it should set its
6941 own :term:`SOURCE_DATE_EPOCH` value::
6942
6943 SOURCE_DATE_EPOCH = "1613559011"
6944
Andrew Geisslerf0343792020-11-18 10:42:21 -06006945 :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006946 When you are fetching files to create a mirror of sources (i.e.
Andrew Geissler09036742021-06-25 14:25:14 -05006947 creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006948 your ``local.conf`` configuration file ensures the source for all
6949 recipes are fetched regardless of whether or not a recipe is
6950 compatible with the configuration. A recipe is considered
6951 incompatible with the currently configured machine when either or
6952 both the :term:`COMPATIBLE_MACHINE`
6953 variable and :term:`COMPATIBLE_HOST` variables
6954 specify compatibility with a machine other than that of the current
6955 machine or host.
6956
6957 .. note::
6958
Andrew Geissler09036742021-06-25 14:25:14 -05006959 Do not set the :term:`SOURCE_MIRROR_FETCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006960 variable unless you are creating a source mirror. In other words,
6961 do not set the variable during a normal build.
6962
Andrew Geisslerf0343792020-11-18 10:42:21 -06006963 :term:`SOURCE_MIRROR_URL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006964 Defines your own :term:`PREMIRRORS` from which to
6965 first fetch source before attempting to fetch from the upstream
6966 specified in :term:`SRC_URI`.
6967
6968 To use this variable, you must globally inherit the
6969 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide
Andrew Geisslerc926e172021-05-07 16:11:35 -05006970 the URL to your mirrors. Here is the general syntax::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006971
6972 INHERIT += "own-mirrors"
6973 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
6974
6975 .. note::
6976
Andrew Geissler09036742021-06-25 14:25:14 -05006977 You can specify only a single URL in :term:`SOURCE_MIRROR_URL`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006978
Andrew Geisslerf0343792020-11-18 10:42:21 -06006979 :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006980 Maps commonly used license names to their SPDX counterparts found in
Andrew Geissler09036742021-06-25 14:25:14 -05006981 ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006982 mappings, see the ``meta/conf/licenses.conf`` file.
6983
6984 For additional information, see the :term:`LICENSE`
6985 variable.
6986
Andrew Geisslerf0343792020-11-18 10:42:21 -06006987 :term:`SPECIAL_PKGSUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006988 A list of prefixes for :term:`PN` used by the OpenEmbedded
6989 build system to create variants of recipes or packages. The list
6990 specifies the prefixes to strip off during certain circumstances such
6991 as the generation of the :term:`BPN` variable.
6992
Andrew Geisslerf0343792020-11-18 10:42:21 -06006993 :term:`SPL_BINARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05006994 The file type for the Secondary Program Loader (SPL). Some devices
6995 use an SPL from which to boot (e.g. the BeagleBone development
6996 board). For such cases, you can declare the file type of the SPL
6997 binary in the ``u-boot.inc`` include file, which is used in the
6998 U-Boot recipe.
6999
7000 The SPL file type is set to "null" by default in the ``u-boot.inc``
Andrew Geisslerc926e172021-05-07 16:11:35 -05007001 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007002
7003 # Some versions of u-boot build an SPL (Second Program Loader) image that
7004 # should be packaged along with the u-boot binary as well as placed in the
7005 # deploy directory. For those versions they can set the following variables
7006 # to allow packaging the SPL.
7007 SPL_BINARY ?= ""
7008 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
7009 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
7010 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
7011
Andrew Geissler09036742021-06-25 14:25:14 -05007012 The :term:`SPL_BINARY` variable helps form
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007013 various ``SPL_*`` variables used by the OpenEmbedded build system.
7014
7015 See the BeagleBone machine configuration example in the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007016 ":ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007017 section in the Yocto Project Board Support Package Developer's Guide
7018 for additional information.
7019
Andrew Geisslerf0343792020-11-18 10:42:21 -06007020 :term:`SRC_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007021 The list of source files - local or remote. This variable tells the
7022 OpenEmbedded build system which bits to pull in for the build and how
7023 to pull them in. For example, if the recipe or append file only needs
7024 to fetch a tarball from the Internet, the recipe or append file uses
Andrew Geissler09036742021-06-25 14:25:14 -05007025 a single :term:`SRC_URI` entry. On the other hand, if the recipe or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007026 append file needs to fetch a tarball, apply two patches, and include
7027 a custom file, the recipe or append file would include four instances
7028 of the variable.
7029
7030 The following list explains the available URI protocols. URI
7031 protocols are highly dependent on particular BitBake Fetcher
7032 submodules. Depending on the fetcher BitBake uses, various URL
7033 parameters are employed. For specifics on the supported Fetchers, see
Patrick Williams213cb262021-08-07 19:21:33 -05007034 the ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers`" section in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007035 BitBake User Manual.
7036
7037 - ``file://`` - Fetches files, which are usually files shipped
7038 with the :term:`Metadata`, from the local machine (e.g.
Andrew Geissler09209ee2020-12-13 08:44:15 -06007039 :ref:`patch <overview-manual/concepts:patching>` files).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007040 The path is relative to the :term:`FILESPATH`
7041 variable. Thus, the build system searches, in order, from the
7042 following directories, which are assumed to be a subdirectories of
7043 the directory in which the recipe file (``.bb``) or append file
7044 (``.bbappend``) resides:
7045
7046 - ``${BPN}`` - The base recipe name without any special suffix
7047 or version numbers.
7048
7049 - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and
7050 version but without any special package name suffix.
7051
7052 - *files -* Files within a directory, which is named ``files``
7053 and is also alongside the recipe or append file.
7054
7055 .. note::
7056
7057 If you want the build system to pick up files specified through
7058 a
7059 SRC_URI
7060 statement from your append file, you need to be sure to extend
7061 the
7062 FILESPATH
7063 variable by also using the
7064 FILESEXTRAPATHS
7065 variable from within your append file.
7066
7067 - ``bzr://`` - Fetches files from a Bazaar revision control
7068 repository.
7069
7070 - ``git://`` - Fetches files from a Git revision control
7071 repository.
7072
Andrew Geissler3b8a17c2021-04-15 15:55:55 -05007073 - ``osc://`` - Fetches files from an OSC (openSUSE Build service)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007074 revision control repository.
7075
7076 - ``repo://`` - Fetches files from a repo (Git) repository.
7077
7078 - ``ccrc://`` - Fetches files from a ClearCase repository.
7079
7080 - ``http://`` - Fetches files from the Internet using ``http``.
7081
7082 - ``https://`` - Fetches files from the Internet using ``https``.
7083
7084 - ``ftp://`` - Fetches files from the Internet using ``ftp``.
7085
7086 - ``cvs://`` - Fetches files from a CVS revision control
7087 repository.
7088
7089 - ``hg://`` - Fetches files from a Mercurial (``hg``) revision
7090 control repository.
7091
7092 - ``p4://`` - Fetches files from a Perforce (``p4``) revision
7093 control repository.
7094
7095 - ``ssh://`` - Fetches files from a secure shell.
7096
7097 - ``svn://`` - Fetches files from a Subversion (``svn``) revision
7098 control repository.
7099
7100 - ``npm://`` - Fetches JavaScript modules from a registry.
7101
Andrew Geissler95ac1b82021-03-31 14:34:31 -05007102 - ``az://`` - Fetches files from an Azure Storage account.
7103
Andrew Geissler09036742021-06-25 14:25:14 -05007104 There are standard and recipe-specific options for :term:`SRC_URI`. Here are
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007105 standard ones:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007106
7107 - ``apply`` - Whether to apply the patch or not. The default
7108 action is to apply the patch.
7109
7110 - ``striplevel`` - Which striplevel to use when applying the
7111 patch. The default level is 1.
7112
7113 - ``patchdir`` - Specifies the directory in which the patch should
7114 be applied. The default is ``${``\ :term:`S`\ ``}``.
7115
7116 Here are options specific to recipes building code from a revision
7117 control system:
7118
7119 - ``mindate`` - Apply the patch only if
7120 :term:`SRCDATE` is equal to or greater than
7121 ``mindate``.
7122
Andrew Geissler09036742021-06-25 14:25:14 -05007123 - ``maxdate`` - Apply the patch only if :term:`SRCDATE` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007124 than ``maxdate``.
7125
Andrew Geissler09036742021-06-25 14:25:14 -05007126 - ``minrev`` - Apply the patch only if :term:`SRCREV` is equal to or
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007127 greater than ``minrev``.
7128
Andrew Geissler09036742021-06-25 14:25:14 -05007129 - ``maxrev`` - Apply the patch only if :term:`SRCREV` is not later
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007130 than ``maxrev``.
7131
Andrew Geissler09036742021-06-25 14:25:14 -05007132 - ``rev`` - Apply the patch only if :term:`SRCREV` is equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007133 ``rev``.
7134
Andrew Geissler09036742021-06-25 14:25:14 -05007135 - ``notrev`` - Apply the patch only if :term:`SRCREV` is not equal to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007136 ``rev``.
7137
7138 Here are some additional options worth mentioning:
7139
7140 - ``unpack`` - Controls whether or not to unpack the file if it is
7141 an archive. The default action is to unpack the file.
7142
7143 - ``destsuffix`` - Places the file (or extracts its contents) into
7144 the specified subdirectory of :term:`WORKDIR` when
7145 the Git fetcher is used.
7146
7147 - ``subdir`` - Places the file (or extracts its contents) into the
Andrew Geissler09036742021-06-25 14:25:14 -05007148 specified subdirectory of :term:`WORKDIR` when the local (``file://``)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007149 fetcher is used.
7150
7151 - ``localdir`` - Places the file (or extracts its contents) into
Andrew Geissler09036742021-06-25 14:25:14 -05007152 the specified subdirectory of :term:`WORKDIR` when the CVS fetcher is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007153 used.
7154
7155 - ``subpath`` - Limits the checkout to a specific subpath of the
7156 tree when using the Git fetcher is used.
7157
7158 - ``name`` - Specifies a name to be used for association with
Andrew Geissler09036742021-06-25 14:25:14 -05007159 :term:`SRC_URI` checksums or :term:`SRCREV` when you have more than one
7160 file or git repository specified in :term:`SRC_URI`. For example::
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007161
7162 SRC_URI = "git://example.com/foo.git;name=first \
7163 git://example.com/bar.git;name=second \
7164 http://example.com/file.tar.gz;name=third"
7165
7166 SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15"
7167 SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f"
7168 SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de"
7169
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007170
7171 - ``downloadfilename`` - Specifies the filename used when storing
7172 the downloaded file.
7173
Andrew Geisslerf0343792020-11-18 10:42:21 -06007174 :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007175 By default, the OpenEmbedded build system automatically detects
Andrew Geissler5f350902021-07-23 13:09:54 -04007176 whether :term:`SRC_URI` contains files that are machine-specific. If so,
Andrew Geissler09036742021-06-25 14:25:14 -05007177 the build system automatically changes :term:`PACKAGE_ARCH`. Setting this
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007178 variable to "0" disables this behavior.
7179
Andrew Geisslerf0343792020-11-18 10:42:21 -06007180 :term:`SRCDATE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007181 The date of the source code used to build the package. This variable
7182 applies only if the source was fetched from a Source Code Manager
7183 (SCM).
7184
Andrew Geisslerf0343792020-11-18 10:42:21 -06007185 :term:`SRCPV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007186 Returns the version string of the current package. This string is
7187 used to help define the value of :term:`PV`.
7188
Andrew Geissler09036742021-06-25 14:25:14 -05007189 The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007190 configuration file in the :term:`Source Directory` as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007191 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007192
7193 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7194
Andrew Geissler09036742021-06-25 14:25:14 -05007195 Recipes that need to define :term:`PV` do so with the help of the
7196 :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``)
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007197 located in ``meta/recipes-connectivity`` in the Source Directory
Andrew Geissler09036742021-06-25 14:25:14 -05007198 defines :term:`PV` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007199
7200 PV = "0.12-git${SRCPV}"
7201
Andrew Geisslerf0343792020-11-18 10:42:21 -06007202 :term:`SRCREV`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007203 The revision of the source code used to build the package. This
7204 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
7205 that if you want to build a fixed revision and you want to avoid
7206 performing a query on the remote repository every time BitBake parses
Andrew Geissler09036742021-06-25 14:25:14 -05007207 your recipe, you should specify a :term:`SRCREV` that is a full revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007208 identifier and not just a tag.
7209
7210 .. note::
7211
7212 For information on limitations when inheriting the latest revision
Andrew Geissler09036742021-06-25 14:25:14 -05007213 of software using :term:`SRCREV`, see the :term:`AUTOREV` variable
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007214 description and the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007215 ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`"
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007216 section, which is in the Yocto Project Development Tasks Manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007217
Andrew Geissler09036742021-06-25 14:25:14 -05007218 :term:`SRCTREECOVEREDTASKS`
7219 A list of tasks that are typically not relevant (and therefore skipped)
7220 when building using the :ref:`externalsrc <ref-classes-externalsrc>`
7221 class. The default value as set in that class file is the set of tasks
7222 that are rarely needed when using external source::
7223
7224 SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch"
7225
7226 The notable exception is when processing external kernel source as
7227 defined in the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
7228 class file (formatted for aesthetics)::
7229
7230 SRCTREECOVEREDTASKS += "\
7231 do_validate_branches \
7232 do_kernel_configcheck \
7233 do_kernel_checkout \
7234 do_fetch \
7235 do_unpack \
7236 do_patch \
7237 "
7238
7239 See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD`
7240 variables for more information.
7241
Andrew Geisslerf0343792020-11-18 10:42:21 -06007242 :term:`SSTATE_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007243 The directory for the shared state cache.
7244
Andrew Geisslerf0343792020-11-18 10:42:21 -06007245 :term:`SSTATE_MIRROR_ALLOW_NETWORK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007246 If set to "1", allows fetches from mirrors that are specified in
7247 :term:`SSTATE_MIRRORS` to work even when
Andrew Geissler09036742021-06-25 14:25:14 -05007248 fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to
7249 "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if
7250 you have set :term:`SSTATE_MIRRORS` to point to an internal server for
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007251 your shared state cache, but you want to disable any other fetching
7252 from the network.
7253
Andrew Geisslerf0343792020-11-18 10:42:21 -06007254 :term:`SSTATE_MIRRORS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007255 Configures the OpenEmbedded build system to search other mirror
7256 locations for prebuilt cache data objects before building out the
7257 data. This variable works like fetcher :term:`MIRRORS`
7258 and :term:`PREMIRRORS` and points to the cache
7259 locations to check for the shared state (sstate) objects.
7260
7261 You can specify a filesystem directory or a remote URL such as HTTP
7262 or FTP. The locations you specify need to contain the shared state
7263 cache (sstate-cache) results from previous builds. The sstate-cache
7264 you point to can also be from builds on other machines.
7265
7266 When pointing to sstate build artifacts on another machine that uses
7267 a different GCC version for native builds, you must configure
Andrew Geissler09036742021-06-25 14:25:14 -05007268 :term:`SSTATE_MIRRORS` with a regular expression that maps local search
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007269 paths to server paths. The paths need to take into account
7270 :term:`NATIVELSBSTRING` set by the
7271 :ref:`uninative <ref-classes-uninative>` class. For example, the
7272 following maps the local search path ``universal-4.9`` to the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007273 server-provided path server_url_sstate_path::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007274
7275 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n"
7276
7277 If a mirror uses the same structure as
7278 :term:`SSTATE_DIR`, you need to add "PATH" at the
7279 end as shown in the examples below. The build system substitutes the
7280 correct path within the directory structure.
7281 ::
7282
7283 SSTATE_MIRRORS ?= "\
7284 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
7285 file://.* file:///some-local-dir/sstate/PATH"
7286
Andrew Geisslerf0343792020-11-18 10:42:21 -06007287 :term:`SSTATE_SCAN_FILES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007288 Controls the list of files the OpenEmbedded build system scans for
7289 hardcoded installation paths. The variable uses a space-separated
7290 list of filenames (not paths) with standard wildcard characters
7291 allowed.
7292
7293 During a build, the OpenEmbedded build system creates a shared state
7294 (sstate) object during the first stage of preparing the sysroots.
7295 That object is scanned for hardcoded paths for original installation
7296 locations. The list of files that are scanned for paths is controlled
Andrew Geissler09036742021-06-25 14:25:14 -05007297 by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files
7298 they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007299 than the variable being comprehensively set. The
7300 :ref:`sstate <ref-classes-sstate>` class specifies the default list
7301 of files.
7302
7303 For details on the process, see the
7304 :ref:`staging <ref-classes-staging>` class.
7305
Andrew Geisslerf0343792020-11-18 10:42:21 -06007306 :term:`STAGING_BASE_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007307 Specifies the path to the ``/lib`` subdirectory of the sysroot
7308 directory for the build host.
7309
Andrew Geisslerf0343792020-11-18 10:42:21 -06007310 :term:`STAGING_BASELIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007311 Specifies the path to the ``/lib`` subdirectory of the sysroot
7312 directory for the target for which the current recipe is being built
7313 (:term:`STAGING_DIR_HOST`).
7314
Andrew Geisslerf0343792020-11-18 10:42:21 -06007315 :term:`STAGING_BINDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007316 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
7317 directory for the target for which the current recipe is being built
7318 (:term:`STAGING_DIR_HOST`).
7319
Andrew Geisslerf0343792020-11-18 10:42:21 -06007320 :term:`STAGING_BINDIR_CROSS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007321 Specifies the path to the directory containing binary configuration
7322 scripts. These scripts provide configuration information for other
7323 software that wants to make use of libraries or include files
7324 provided by the software associated with the script.
7325
7326 .. note::
7327
7328 This style of build configuration has been largely replaced by
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007329 ``pkg-config``. Consequently, if ``pkg-config`` is supported by the
7330 library to which you are linking, it is recommended you use
7331 ``pkg-config`` instead of a provided configuration script.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007332
Andrew Geisslerf0343792020-11-18 10:42:21 -06007333 :term:`STAGING_BINDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007334 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
7335 directory for the build host.
7336
Andrew Geisslerf0343792020-11-18 10:42:21 -06007337 :term:`STAGING_DATADIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007338 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
7339 directory for the target for which the current recipe is being built
7340 (:term:`STAGING_DIR_HOST`).
7341
Andrew Geisslerf0343792020-11-18 10:42:21 -06007342 :term:`STAGING_DATADIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007343 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
7344 directory for the build host.
7345
Andrew Geisslerf0343792020-11-18 10:42:21 -06007346 :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007347 Helps construct the ``recipe-sysroots`` directory, which is used
7348 during packaging.
7349
7350 For information on how staging for recipe-specific sysroots occurs,
7351 see the :ref:`ref-tasks-populate_sysroot`
Andrew Geissler09209ee2020-12-13 08:44:15 -06007352 task, the ":ref:`sdk-manual/extensible:sharing files between recipes`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007353 section in the Yocto Project Development Tasks Manual, the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007354 ":ref:`overview-manual/concepts:configuration, compilation, and staging`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007355 section in the Yocto Project Overview and Concepts Manual, and the
7356 :term:`SYSROOT_DIRS` variable.
7357
7358 .. note::
7359
Andrew Geissler09036742021-06-25 14:25:14 -05007360 Recipes should never write files directly under the :term:`STAGING_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007361 directory because the OpenEmbedded build system manages the
7362 directory automatically. Instead, files should be installed to
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007363 ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007364 task and then the OpenEmbedded build system will stage a subset of
7365 those files into the sysroot.
7366
Andrew Geisslerf0343792020-11-18 10:42:21 -06007367 :term:`STAGING_DIR_HOST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007368 Specifies the path to the sysroot directory for the system on which
7369 the component is built to run (the system that hosts the component).
7370 For most recipes, this sysroot is the one in which that recipe's
7371 :ref:`ref-tasks-populate_sysroot` task copies
7372 files. Exceptions include ``-native`` recipes, where the
7373 ``do_populate_sysroot`` task instead uses
7374 :term:`STAGING_DIR_NATIVE`. Depending on
Andrew Geissler09036742021-06-25 14:25:14 -05007375 the type of recipe and the build target, :term:`STAGING_DIR_HOST` can
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007376 have the following values:
7377
7378 - For recipes building for the target machine, the value is
7379 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
7380
7381 - For native recipes building for the build host, the value is empty
7382 given the assumption that when building for the build host, the
7383 build host's own directories should be used.
7384
7385 .. note::
7386
7387 ``-native`` recipes are not installed into host paths like such
7388 as ``/usr``. Rather, these recipes are installed into
Andrew Geissler5f350902021-07-23 13:09:54 -04007389 :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007390 standard build environment variables such as
7391 :term:`CPPFLAGS` and
7392 :term:`CFLAGS` are set up so that both host paths
Andrew Geissler09036742021-06-25 14:25:14 -05007393 and :term:`STAGING_DIR_NATIVE` are searched for libraries and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007394 headers using, for example, GCC's ``-isystem`` option.
7395
7396 Thus, the emphasis is that the ``STAGING_DIR*`` variables
7397 should be viewed as input variables by tasks such as
7398 :ref:`ref-tasks-configure`,
7399 :ref:`ref-tasks-compile`, and
7400 :ref:`ref-tasks-install`. Having the real system
Andrew Geissler09036742021-06-25 14:25:14 -05007401 root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007402 for ``-native`` recipes, as they make use of host headers and
7403 libraries.
7404
Andrew Geisslerf0343792020-11-18 10:42:21 -06007405 :term:`STAGING_DIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007406 Specifies the path to the sysroot directory used when building
7407 components that run on the build host itself.
7408
Andrew Geisslerf0343792020-11-18 10:42:21 -06007409 :term:`STAGING_DIR_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007410 Specifies the path to the sysroot used for the system for which the
7411 component generates code. For components that do not generate code,
Andrew Geissler09036742021-06-25 14:25:14 -05007412 which is the majority, :term:`STAGING_DIR_TARGET` is set to match
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007413 :term:`STAGING_DIR_HOST`.
7414
7415 Some recipes build binaries that can run on the target system but
7416 those binaries in turn generate code for another different system
7417 (e.g. cross-canadian recipes). Using terminology from GNU, the
7418 primary system is referred to as the "HOST" and the secondary, or
7419 different, system is referred to as the "TARGET". Thus, the binaries
7420 run on the "HOST" system and generate binaries for the "TARGET"
Andrew Geissler09036742021-06-25 14:25:14 -05007421 system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used
7422 for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007423 sysroot used for the "TARGET" system.
7424
Andrew Geisslerf0343792020-11-18 10:42:21 -06007425 :term:`STAGING_ETCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007426 Specifies the path to the ``/etc`` subdirectory of the sysroot
7427 directory for the build host.
7428
Andrew Geisslerf0343792020-11-18 10:42:21 -06007429 :term:`STAGING_EXECPREFIXDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007430 Specifies the path to the ``/usr`` subdirectory of the sysroot
7431 directory for the target for which the current recipe is being built
7432 (:term:`STAGING_DIR_HOST`).
7433
Andrew Geisslerf0343792020-11-18 10:42:21 -06007434 :term:`STAGING_INCDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007435 Specifies the path to the ``/usr/include`` subdirectory of the
7436 sysroot directory for the target for which the current recipe being
7437 built (:term:`STAGING_DIR_HOST`).
7438
Andrew Geisslerf0343792020-11-18 10:42:21 -06007439 :term:`STAGING_INCDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007440 Specifies the path to the ``/usr/include`` subdirectory of the
7441 sysroot directory for the build host.
7442
Andrew Geisslerf0343792020-11-18 10:42:21 -06007443 :term:`STAGING_KERNEL_BUILDDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007444 Points to the directory containing the kernel build artifacts.
7445 Recipes building software that needs to access kernel build artifacts
7446 (e.g. ``systemtap-uprobes``) can look in the directory specified with
Andrew Geissler09036742021-06-25 14:25:14 -05007447 the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007448 after the kernel has been built.
7449
Andrew Geisslerf0343792020-11-18 10:42:21 -06007450 :term:`STAGING_KERNEL_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007451 The directory with kernel headers that are required to build
7452 out-of-tree modules.
7453
Andrew Geisslerf0343792020-11-18 10:42:21 -06007454 :term:`STAGING_LIBDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007455 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
7456 directory for the target for which the current recipe is being built
7457 (:term:`STAGING_DIR_HOST`).
7458
Andrew Geisslerf0343792020-11-18 10:42:21 -06007459 :term:`STAGING_LIBDIR_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007460 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
7461 directory for the build host.
7462
Andrew Geisslerf0343792020-11-18 10:42:21 -06007463 :term:`STAMP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007464 Specifies the base path used to create recipe stamp files. The path
7465 to an actual stamp file is constructed by evaluating this string and
7466 then appending additional information. Currently, the default
Andrew Geissler09036742021-06-25 14:25:14 -05007467 assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05007468 file is::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007469
7470 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7471
7472 For information on how BitBake uses stamp files to determine if a
7473 task should be rerun, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007474 ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007475 section in the Yocto Project Overview and Concepts Manual.
7476
7477 See :term:`STAMPS_DIR`,
7478 :term:`MULTIMACH_TARGET_SYS`,
7479 :term:`PN`, :term:`EXTENDPE`,
7480 :term:`PV`, and :term:`PR` for related variable
7481 information.
7482
Andrew Geisslerf0343792020-11-18 10:42:21 -06007483 :term:`STAMPS_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007484 Specifies the base directory in which the OpenEmbedded build system
7485 places stamps. The default directory is ``${TMPDIR}/stamps``.
7486
Andrew Geisslerf0343792020-11-18 10:42:21 -06007487 :term:`STRIP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007488 The minimal command and arguments to run ``strip``, which is used to
7489 strip symbols.
7490
Andrew Geisslerf0343792020-11-18 10:42:21 -06007491 :term:`SUMMARY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007492 The short (72 characters or less) summary of the binary package for
7493 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
Andrew Geissler09036742021-06-25 14:25:14 -05007494 :term:`SUMMARY` is used to define the
7495 :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007496 not set in the recipe.
7497
Andrew Geisslerf0343792020-11-18 10:42:21 -06007498 :term:`SVNDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007499 The directory in which files checked out of a Subversion system are
7500 stored.
7501
Andrew Geisslerf0343792020-11-18 10:42:21 -06007502 :term:`SYSLINUX_DEFAULT_CONSOLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007503 Specifies the kernel boot default console. If you want to use a
7504 console other than the default, set this variable in your recipe as
Andrew Geisslerc926e172021-05-07 16:11:35 -05007505 follows where "X" is the console number you want to use::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007506
7507 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7508
7509 The :ref:`syslinux <ref-classes-syslinux>` class initially sets
7510 this variable to null but then checks for a value later.
7511
Andrew Geisslerf0343792020-11-18 10:42:21 -06007512 :term:`SYSLINUX_OPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007513 Lists additional options to add to the syslinux file. You need to set
7514 this variable in your recipe. If you want to list multiple options,
7515 separate the options with a semicolon character (``;``).
7516
7517 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable
7518 to create a set of options.
7519
Andrew Geisslerf0343792020-11-18 10:42:21 -06007520 :term:`SYSLINUX_SERIAL`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007521 Specifies the alternate serial port or turns it off. To turn off
7522 serial, set this variable to an empty string in your recipe. The
7523 variable's default value is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007524 :ref:`syslinux <ref-classes-syslinux>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007525
7526 SYSLINUX_SERIAL ?= "0 115200"
7527
7528 The class checks for and uses the variable as needed.
7529
Andrew Geisslerf0343792020-11-18 10:42:21 -06007530 :term:`SYSLINUX_SERIAL_TTY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007531 Specifies the alternate console=tty... kernel boot argument. The
7532 variable's default value is set in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007533 :ref:`syslinux <ref-classes-syslinux>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007534
7535 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7536
7537 The class checks for and uses the variable as needed.
7538
Andrew Geisslerf0343792020-11-18 10:42:21 -06007539 :term:`SYSLINUX_SPLASH`
7540 An ``.LSS`` file used as the background for the VGA boot menu when
7541 you use the boot menu. You need to set this variable in your recipe.
7542
7543 The :ref:`syslinux <ref-classes-syslinux>` class checks for this
7544 variable and if found, the OpenEmbedded build system installs the
7545 splash screen.
7546
7547 :term:`SYSROOT_DESTDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007548 Points to the temporary directory under the work directory (default
7549 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
7550 where the files populated into the sysroot are assembled during the
7551 :ref:`ref-tasks-populate_sysroot` task.
7552
Andrew Geisslerf0343792020-11-18 10:42:21 -06007553 :term:`SYSROOT_DIRS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007554 Directories that are staged into the sysroot by the
7555 :ref:`ref-tasks-populate_sysroot` task. By
Andrew Geisslerc926e172021-05-07 16:11:35 -05007556 default, the following directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007557
7558 SYSROOT_DIRS = " \
7559 ${includedir} \
7560 ${libdir} \
7561 ${base_libdir} \
7562 ${nonarch_base_libdir} \
7563 ${datadir} \
Andrew Geissler5199d832021-09-24 16:47:35 -05007564 /sysroot-only \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007565 "
7566
Andrew Geisslerf0343792020-11-18 10:42:21 -06007567 :term:`SYSROOT_DIRS_BLACKLIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007568 Directories that are not staged into the sysroot by the
7569 :ref:`ref-tasks-populate_sysroot` task. You
7570 can use this variable to exclude certain subdirectories of
7571 directories listed in :term:`SYSROOT_DIRS` from
Andrew Geisslerc926e172021-05-07 16:11:35 -05007572 staging. By default, the following directories are not staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007573
7574 SYSROOT_DIRS_BLACKLIST = " \
7575 ${mandir} \
7576 ${docdir} \
7577 ${infodir} \
Andrew Geissler5199d832021-09-24 16:47:35 -05007578 ${datadir}/X11/locale \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007579 ${datadir}/applications \
Andrew Geissler5199d832021-09-24 16:47:35 -05007580 ${datadir}/bash-completion \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007581 ${datadir}/fonts \
Andrew Geissler5199d832021-09-24 16:47:35 -05007582 ${datadir}/gtk-doc/html \
7583 ${datadir}/installed-tests \
7584 ${datadir}/locale \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007585 ${datadir}/pixmaps \
Andrew Geissler5199d832021-09-24 16:47:35 -05007586 ${datadir}/terminfo \
7587 ${libdir}/${BPN}/ptest \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007588 "
7589
Andrew Geisslerf0343792020-11-18 10:42:21 -06007590 :term:`SYSROOT_DIRS_NATIVE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007591 Extra directories staged into the sysroot by the
7592 :ref:`ref-tasks-populate_sysroot` task for
7593 ``-native`` recipes, in addition to those specified in
7594 :term:`SYSROOT_DIRS`. By default, the following
Andrew Geisslerc926e172021-05-07 16:11:35 -05007595 extra directories are staged::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007596
7597 SYSROOT_DIRS_NATIVE = " \
7598 ${bindir} \
7599 ${sbindir} \
7600 ${base_bindir} \
7601 ${base_sbindir} \
7602 ${libexecdir} \
7603 ${sysconfdir} \
7604 ${localstatedir} \
7605 "
7606
7607 .. note::
7608
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007609 Programs built by ``-native`` recipes run directly from the sysroot
7610 (:term:`STAGING_DIR_NATIVE`), which is why additional directories
7611 containing program executables and supporting files need to be staged.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007612
Andrew Geisslerf0343792020-11-18 10:42:21 -06007613 :term:`SYSROOT_PREPROCESS_FUNCS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007614 A list of functions to execute after files are staged into the
7615 sysroot. These functions are usually used to apply additional
7616 processing on the staged files, or to stage additional files.
7617
Andrew Geisslerf0343792020-11-18 10:42:21 -06007618 :term:`SYSTEMD_AUTO_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007619 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7620 this variable specifies whether the specified service in
7621 :term:`SYSTEMD_SERVICE` should start
7622 automatically or not. By default, the service is enabled to
7623 automatically start at boot time. The default setting is in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05007624 :ref:`systemd <ref-classes-systemd>` class as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007625
7626 SYSTEMD_AUTO_ENABLE ??= "enable"
7627
7628 You can disable the service by setting the variable to "disable".
7629
Andrew Geisslerf0343792020-11-18 10:42:21 -06007630 :term:`SYSTEMD_BOOT_CFG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007631 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007632 "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007633 configuration file that should be used. By default, the
7634 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007635 :term:`SYSTEMD_BOOT_CFG` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007636
7637 SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf"
7638
7639 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007640 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007641
Andrew Geisslerf0343792020-11-18 10:42:21 -06007642 :term:`SYSTEMD_BOOT_ENTRIES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007643 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007644 "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007645 list of entry files (``*.conf``) to install that contain one boot
7646 entry per file. By default, the
7647 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007648 :term:`SYSTEMD_BOOT_ENTRIES` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007649
7650 SYSTEMD_BOOT_ENTRIES ?= ""
7651
7652 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007653 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007654
Andrew Geisslerf0343792020-11-18 10:42:21 -06007655 :term:`SYSTEMD_BOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007656 When :term:`EFI_PROVIDER` is set to
Andrew Geissler09036742021-06-25 14:25:14 -05007657 "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007658 boot menu timeout in seconds. By default, the
7659 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007660 :term:`SYSTEMD_BOOT_TIMEOUT` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007661
7662 SYSTEMD_BOOT_TIMEOUT ?= "10"
7663
7664 For information on Systemd-boot, see the `Systemd-boot
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007665 documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007666
Andrew Geisslerf0343792020-11-18 10:42:21 -06007667 :term:`SYSTEMD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007668 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7669 this variable locates the systemd unit files when they are not found
Andrew Geissler09036742021-06-25 14:25:14 -05007670 in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007671 variable is set such that the systemd unit files are assumed to
Andrew Geisslerc926e172021-05-07 16:11:35 -05007672 reside in the recipes main package::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007673
7674 SYSTEMD_PACKAGES ?= "${PN}"
7675
7676 If these unit files are not in this recipe's main package, you need
Andrew Geissler09036742021-06-25 14:25:14 -05007677 to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007678 the build system can find the systemd unit files.
7679
Andrew Geisslerf0343792020-11-18 10:42:21 -06007680 :term:`SYSTEMD_SERVICE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007681 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
7682 this variable specifies the systemd service name for a package.
7683
7684 When you specify this file in your recipe, use a package name
7685 override to indicate the package to which the value applies. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05007686 an example from the connman recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007687
Patrick Williams0ca19cc2021-08-16 14:03:13 -05007688 SYSTEMD_SERVICE:${PN} = "connman.service"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007689
Andrew Geisslerf0343792020-11-18 10:42:21 -06007690 :term:`SYSVINIT_ENABLED_GETTYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007691 When using
Andrew Geissler09209ee2020-12-13 08:44:15 -06007692 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007693 specifies a space-separated list of the virtual terminals that should
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007694 run a `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007695 (allowing login), assuming :term:`USE_VT` is not set to
7696 "0".
7697
Andrew Geissler09036742021-06-25 14:25:14 -05007698 The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007699 run a getty on the first virtual terminal).
7700
Andrew Geisslerf0343792020-11-18 10:42:21 -06007701 :term:`T`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007702 This variable points to a directory were BitBake places temporary
7703 files, which consist mostly of task logs and scripts, when building a
Andrew Geisslerc926e172021-05-07 16:11:35 -05007704 particular recipe. The variable is typically set as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007705
7706 T = "${WORKDIR}/temp"
7707
7708 The :term:`WORKDIR` is the directory into which
7709 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
7710 file sets this variable.
7711
Andrew Geissler09036742021-06-25 14:25:14 -05007712 The :term:`T` variable is not to be confused with the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007713 :term:`TMPDIR` variable, which points to the root of
7714 the directory tree where BitBake places the output of an entire
7715 build.
7716
Andrew Geisslerf0343792020-11-18 10:42:21 -06007717 :term:`TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007718 The target machine's architecture. The OpenEmbedded build system
7719 supports many architectures. Here is an example list of architectures
7720 supported. This list is by no means complete as the architecture is
7721 configurable:
7722
7723 - arm
7724 - i586
7725 - x86_64
7726 - powerpc
7727 - powerpc64
7728 - mips
7729 - mipsel
7730
7731 For additional information on machine architectures, see the
7732 :term:`TUNE_ARCH` variable.
7733
Andrew Geisslerf0343792020-11-18 10:42:21 -06007734 :term:`TARGET_AS_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007735 Specifies architecture-specific assembler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05007736 system. :term:`TARGET_AS_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007737 :term:`TUNE_ASARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05007738 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007739
7740 TARGET_AS_ARCH = "${TUNE_ASARGS}"
7741
Andrew Geisslerf0343792020-11-18 10:42:21 -06007742 :term:`TARGET_CC_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007743 Specifies architecture-specific C compiler flags for the target
Andrew Geissler09036742021-06-25 14:25:14 -05007744 system. :term:`TARGET_CC_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007745 :term:`TUNE_CCARGS` by default.
7746
7747 .. note::
7748
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007749 It is a common workaround to append :term:`LDFLAGS` to
Andrew Geissler09036742021-06-25 14:25:14 -05007750 :term:`TARGET_CC_ARCH` in recipes that build software for the target that
7751 would not otherwise respect the exported :term:`LDFLAGS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007752
Andrew Geisslerf0343792020-11-18 10:42:21 -06007753 :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007754 This is a specific kernel compiler flag for a CPU or Application
7755 Binary Interface (ABI) tune. The flag is used rarely and only for
7756 cases where a userspace :term:`TUNE_CCARGS` is not
Andrew Geissler09036742021-06-25 14:25:14 -05007757 compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007758 variable allows the kernel (and associated modules) to use a
7759 different configuration. See the
7760 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
7761 :term:`Source Directory` for an example.
7762
Andrew Geisslerf0343792020-11-18 10:42:21 -06007763 :term:`TARGET_CFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007764 Specifies the flags to pass to the C compiler when building for the
7765 target. When building in the target context,
7766 :term:`CFLAGS` is set to the value of this variable by
7767 default.
7768
Andrew Geissler09036742021-06-25 14:25:14 -05007769 Additionally, the SDK's environment setup script sets the :term:`CFLAGS`
7770 variable in the environment to the :term:`TARGET_CFLAGS` value so that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007771 executables built using the SDK also have the flags applied.
7772
Andrew Geisslerf0343792020-11-18 10:42:21 -06007773 :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007774 Specifies the flags to pass to the C pre-processor (i.e. to both the
7775 C and the C++ compilers) when building for the target. When building
7776 in the target context, :term:`CPPFLAGS` is set to the
7777 value of this variable by default.
7778
7779 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007780 :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007781 value so that executables built using the SDK also have the flags
7782 applied.
7783
Andrew Geisslerf0343792020-11-18 10:42:21 -06007784 :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007785 Specifies the flags to pass to the C++ compiler when building for the
7786 target. When building in the target context,
7787 :term:`CXXFLAGS` is set to the value of this variable
7788 by default.
7789
7790 Additionally, the SDK's environment setup script sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007791 :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007792 value so that executables built using the SDK also have the flags
7793 applied.
7794
Andrew Geisslerf0343792020-11-18 10:42:21 -06007795 :term:`TARGET_FPU`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007796 Specifies the method for handling FPU code. For FPU-less targets,
7797 which include most ARM CPUs, the variable must be set to "soft". If
7798 not, the kernel emulation gets used, which results in a performance
7799 penalty.
7800
Andrew Geisslerf0343792020-11-18 10:42:21 -06007801 :term:`TARGET_LD_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007802 Specifies architecture-specific linker flags for the target system.
Andrew Geissler09036742021-06-25 14:25:14 -05007803 :term:`TARGET_LD_ARCH` is initialized from
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007804 :term:`TUNE_LDARGS` by default in the BitBake
Andrew Geisslerc926e172021-05-07 16:11:35 -05007805 configuration file (``meta/conf/bitbake.conf``)::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007806
7807 TARGET_LD_ARCH = "${TUNE_LDARGS}"
7808
Andrew Geisslerf0343792020-11-18 10:42:21 -06007809 :term:`TARGET_LDFLAGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007810 Specifies the flags to pass to the linker when building for the
7811 target. When building in the target context,
7812 :term:`LDFLAGS` is set to the value of this variable
7813 by default.
7814
7815 Additionally, the SDK's environment setup script sets the
7816 :term:`LDFLAGS` variable in the environment to the
Andrew Geissler09036742021-06-25 14:25:14 -05007817 :term:`TARGET_LDFLAGS` value so that executables built using the SDK also
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007818 have the flags applied.
7819
Andrew Geisslerf0343792020-11-18 10:42:21 -06007820 :term:`TARGET_OS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007821 Specifies the target's operating system. The variable can be set to
7822 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
William A. Kennington IIIac69b482021-06-02 12:28:27 -07007823 for musl libc. For ARM/EABI targets, the possible values are
7824 "linux-gnueabi" and "linux-musleabi".
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007825
Andrew Geisslerf0343792020-11-18 10:42:21 -06007826 :term:`TARGET_PREFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007827 Specifies the prefix used for the toolchain binary target tools.
7828
7829 Depending on the type of recipe and the build target,
Andrew Geissler5f350902021-07-23 13:09:54 -04007830 :term:`TARGET_PREFIX` is set as follows:
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007831
7832 - For recipes building for the target machine, the value is
7833 "${:term:`TARGET_SYS`}-".
7834
7835 - For native recipes, the build system sets the variable to the
Andrew Geissler5f350902021-07-23 13:09:54 -04007836 value of :term:`BUILD_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007837
7838 - For native SDK recipes (``nativesdk``), the build system sets the
Andrew Geissler09036742021-06-25 14:25:14 -05007839 variable to the value of :term:`SDK_PREFIX`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007840
Andrew Geisslerf0343792020-11-18 10:42:21 -06007841 :term:`TARGET_SYS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007842 Specifies the system, including the architecture and the operating
7843 system, for which the build is occurring in the context of the
7844 current recipe.
7845
7846 The OpenEmbedded build system automatically sets this variable based
7847 on :term:`TARGET_ARCH`,
7848 :term:`TARGET_VENDOR`, and
7849 :term:`TARGET_OS` variables.
7850
7851 .. note::
7852
Andrew Geissler09036742021-06-25 14:25:14 -05007853 You do not need to set the :term:`TARGET_SYS` variable yourself.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007854
7855 Consider these two examples:
7856
7857 - Given a native recipe on a 32-bit, x86 machine running Linux, the
7858 value is "i686-linux".
7859
7860 - Given a recipe being built for a little-endian, MIPS target
7861 running Linux, the value might be "mipsel-linux".
7862
Andrew Geisslerf0343792020-11-18 10:42:21 -06007863 :term:`TARGET_VENDOR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007864 Specifies the name of the target vendor.
7865
Andrew Geisslerf0343792020-11-18 10:42:21 -06007866 :term:`TCLIBC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007867 Specifies the GNU standard C library (``libc``) variant to use during
7868 the build process. This variable replaces ``POKYLIBC``, which is no
7869 longer supported.
7870
7871 You can select "glibc", "musl", "newlib", or "baremetal"
7872
Andrew Geisslerf0343792020-11-18 10:42:21 -06007873 :term:`TCLIBCAPPEND`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007874 Specifies a suffix to be appended onto the
7875 :term:`TMPDIR` value. The suffix identifies the
7876 ``libc`` variant for building. When you are building for multiple
7877 variants with the same :term:`Build Directory`, this
7878 mechanism ensures that output for different ``libc`` variants is kept
7879 separate to avoid potential conflicts.
7880
7881 In the ``defaultsetup.conf`` file, the default value of
Andrew Geissler5f350902021-07-23 13:09:54 -04007882 :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007883 which normally only support one ``libc`` variant, set
Andrew Geissler09036742021-06-25 14:25:14 -05007884 :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007885 in no suffix being applied.
7886
Andrew Geisslerf0343792020-11-18 10:42:21 -06007887 :term:`TCMODE`
Andrew Geissler09036742021-06-25 14:25:14 -05007888 Specifies the toolchain selector. :term:`TCMODE` controls the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007889 characteristics of the generated packages and images by telling the
7890 OpenEmbedded build system which toolchain profile to use. By default,
7891 the OpenEmbedded build system builds its own internal toolchain. The
7892 variable's default value is "default", which uses that internal
7893 toolchain.
7894
7895 .. note::
7896
Andrew Geissler09036742021-06-25 14:25:14 -05007897 If :term:`TCMODE` is set to a value other than "default", then it is your
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007898 responsibility to ensure that the toolchain is compatible with the
7899 default toolchain. Using older or newer versions of these
7900 components might cause build problems. See the Release Notes for
7901 the Yocto Project release for the specific components with which
7902 the toolchain must be compatible. To access the Release Notes, go
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007903 to the :yocto_home:`Downloads </software-overview/downloads>`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007904 page on the Yocto Project website and click on the "RELEASE
7905 INFORMATION" link for the appropriate release.
7906
Andrew Geissler09036742021-06-25 14:25:14 -05007907 The :term:`TCMODE` variable is similar to :term:`TCLIBC`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007908 which controls the variant of the GNU standard C library (``libc``)
7909 used during the build process: ``glibc`` or ``musl``.
7910
7911 With additional layers, it is possible to use a pre-compiled external
7912 toolchain. One example is the Sourcery G++ Toolchain. The support for
7913 this toolchain resides in the separate Mentor Graphics
7914 ``meta-sourcery`` layer at
Andrew Geisslerd1e89492021-02-12 15:35:20 -06007915 https://github.com/MentorEmbedded/meta-sourcery/.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007916
7917 The layer's ``README`` file contains information on how to use the
7918 Sourcery G++ Toolchain as an external toolchain. In summary, you must
7919 be sure to add the layer to your ``bblayers.conf`` file in front of
7920 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable
7921 in your ``local.conf`` file to the location in which you installed
7922 the toolchain.
7923
7924 The fundamentals used for this example apply to any external
7925 toolchain. You can use ``meta-sourcery`` as a template for adding
7926 support for other external toolchains.
7927
Andrew Geisslerf0343792020-11-18 10:42:21 -06007928 :term:`TEST_EXPORT_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007929 The location the OpenEmbedded build system uses to export tests when
7930 the :term:`TEST_EXPORT_ONLY` variable is set
7931 to "1".
7932
Andrew Geissler09036742021-06-25 14:25:14 -05007933 The :term:`TEST_EXPORT_DIR` variable defaults to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007934 ``"${TMPDIR}/testimage/${PN}"``.
7935
Andrew Geisslerf0343792020-11-18 10:42:21 -06007936 :term:`TEST_EXPORT_ONLY`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007937 Specifies to export the tests only. Set this variable to "1" if you
7938 do not want to run the tests but you want them to be exported in a
7939 manner that you to run them outside of the build system.
7940
Andrew Geisslerf0343792020-11-18 10:42:21 -06007941 :term:`TEST_LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007942 Holds the SSH log and the boot log for QEMU machines. The
Andrew Geissler09036742021-06-25 14:25:14 -05007943 :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007944
7945 .. note::
7946
Andrew Geissler4c19ea12020-10-27 13:52:24 -05007947 Actual test results reside in the task log (``log.do_testimage``),
7948 which is in the ``${WORKDIR}/temp/`` directory.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007949
Andrew Geisslerf0343792020-11-18 10:42:21 -06007950 :term:`TEST_POWERCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007951 For automated hardware testing, specifies the command to use to
7952 control the power of the target machine under test. Typically, this
7953 command would point to a script that performs the appropriate action
7954 (e.g. interacting with a web-enabled power strip). The specified
7955 command should expect to receive as the last argument "off", "on" or
7956 "cycle" specifying to power off, on, or cycle (power off and then
7957 power on) the device, respectively.
7958
Andrew Geisslerf0343792020-11-18 10:42:21 -06007959 :term:`TEST_POWERCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007960 For automated hardware testing, specifies additional arguments to
7961 pass through to the command specified in
7962 :term:`TEST_POWERCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05007963 :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007964 wish, for example, to separate the machine-specific and
7965 non-machine-specific parts of the arguments.
7966
Andrew Geisslerf0343792020-11-18 10:42:21 -06007967 :term:`TEST_QEMUBOOT_TIMEOUT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007968 The time in seconds allowed for an image to boot before automated
7969 runtime tests begin to run against an image. The default timeout
7970 period to allow the boot process to reach the login prompt is 500
7971 seconds. You can specify a different value in the ``local.conf``
7972 file.
7973
7974 For more information on testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06007975 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007976 section in the Yocto Project Development Tasks Manual.
7977
Andrew Geisslerf0343792020-11-18 10:42:21 -06007978 :term:`TEST_SERIALCONTROL_CMD`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007979 For automated hardware testing, specifies the command to use to
7980 connect to the serial console of the target machine under test. This
7981 command simply needs to connect to the serial console and forward
7982 that connection to standard input and output as any normal terminal
7983 program does.
7984
7985 For example, to use the Picocom terminal program on serial device
Andrew Geisslerc926e172021-05-07 16:11:35 -05007986 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007987
7988 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
7989
Andrew Geisslerf0343792020-11-18 10:42:21 -06007990 :term:`TEST_SERIALCONTROL_EXTRA_ARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007991 For automated hardware testing, specifies additional arguments to
7992 pass through to the command specified in
7993 :term:`TEST_SERIALCONTROL_CMD`. Setting
Andrew Geissler09036742021-06-25 14:25:14 -05007994 :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007995 wish, for example, to separate the machine-specific and
7996 non-machine-specific parts of the command.
7997
Andrew Geisslerf0343792020-11-18 10:42:21 -06007998 :term:`TEST_SERVER_IP`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05007999 The IP address of the build machine (host machine). This IP address
8000 is usually automatically detected. However, if detection fails, this
8001 variable needs to be set to the IP address of the build machine (i.e.
8002 where the build is taking place).
8003
8004 .. note::
8005
Andrew Geissler09036742021-06-25 14:25:14 -05008006 The :term:`TEST_SERVER_IP` variable is only used for a small number of
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008007 tests such as the "dnf" test suite, which needs to download packages
8008 from ``WORKDIR/oe-rootfs-repo``.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008009
Andrew Geisslerf0343792020-11-18 10:42:21 -06008010 :term:`TEST_SUITES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008011 An ordered list of tests (modules) to run against an image when
8012 performing automated runtime testing.
8013
8014 The OpenEmbedded build system provides a core set of tests that can
8015 be used against images.
8016
8017 .. note::
8018
8019 Currently, there is only support for running these tests under
8020 QEMU.
8021
8022 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
Andrew Geissler09036742021-06-25 14:25:14 -05008023 your own tests to the list of tests by appending :term:`TEST_SUITES` as
Andrew Geisslerc926e172021-05-07 16:11:35 -05008024 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008025
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008026 TEST_SUITES:append = " mytest"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008027
8028 Alternatively, you can
8029 provide the "auto" option to have all applicable tests run against
8030 the image.
8031 ::
8032
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008033 TEST_SUITES:append = " auto"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008034
8035 Using this option causes the
8036 build system to automatically run tests that are applicable to the
8037 image. Tests that are not applicable are skipped.
8038
8039 The order in which tests are run is important. Tests that depend on
8040 another test must appear later in the list than the test on which
8041 they depend. For example, if you append the list of tests with two
8042 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
Andrew Geisslerc926e172021-05-07 16:11:35 -05008043 ``test_A``, then you must order the tests as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008044
8045 TEST_SUITES = "test_A test_B"
8046
8047 For more information on testing images, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008048 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008049 section in the Yocto Project Development Tasks Manual.
8050
Andrew Geisslerf0343792020-11-18 10:42:21 -06008051 :term:`TEST_TARGET`
8052 Specifies the target controller to use when running tests against a
Andrew Geisslerc926e172021-05-07 16:11:35 -05008053 test image. The default controller to use is "qemu"::
Andrew Geisslerf0343792020-11-18 10:42:21 -06008054
8055 TEST_TARGET = "qemu"
8056
8057 A target controller is a class that defines how an image gets
8058 deployed on a target and how a target is started. A layer can extend
8059 the controllers by adding a module in the layer's
8060 ``/lib/oeqa/controllers`` directory and by inheriting the
8061 ``BaseTarget`` class, which is an abstract class that cannot be used
Andrew Geissler09036742021-06-25 14:25:14 -05008062 as a value of :term:`TEST_TARGET`.
Andrew Geisslerf0343792020-11-18 10:42:21 -06008063
Andrew Geissler5f350902021-07-23 13:09:54 -04008064 You can provide the following arguments with :term:`TEST_TARGET`:
Andrew Geisslerf0343792020-11-18 10:42:21 -06008065
8066 - *"qemu":* Boots a QEMU image and runs the tests. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008067 ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section
Andrew Geisslerf0343792020-11-18 10:42:21 -06008068 in the Yocto Project Development Tasks Manual for more
8069 information.
8070
8071 - *"simpleremote":* Runs the tests on target hardware that is
8072 already up and running. The hardware can be on the network or it
8073 can be a device running an image on QEMU. You must also set
8074 :term:`TEST_TARGET_IP` when you use
8075 "simpleremote".
8076
8077 .. note::
8078
8079 This argument is defined in
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008080 ``meta/lib/oeqa/controllers/simpleremote.py``.
Andrew Geisslerf0343792020-11-18 10:42:21 -06008081
8082 For information on running tests on hardware, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008083 ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008084 section in the Yocto Project Development Tasks Manual.
8085
8086 :term:`TEST_TARGET_IP`
Andrew Geissler09036742021-06-25 14:25:14 -05008087 The IP address of your hardware under test. The :term:`TEST_TARGET_IP`
Andrew Geisslerf0343792020-11-18 10:42:21 -06008088 variable has no effect when :term:`TEST_TARGET` is
8089 set to "qemu".
8090
8091 When you specify the IP address, you can also include a port. Here is
Andrew Geisslerc926e172021-05-07 16:11:35 -05008092 an example::
Andrew Geisslerf0343792020-11-18 10:42:21 -06008093
8094 TEST_TARGET_IP = "192.168.1.4:2201"
8095
8096 Specifying a port is
8097 useful when SSH is started on a non-standard port or in cases when
8098 your hardware under test is behind a firewall or network that is not
8099 directly accessible from your host and you need to do port address
8100 translation.
8101
8102 :term:`TESTIMAGE_AUTO`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008103 Automatically runs the series of automated tests for images when an
Andrew Geissler09036742021-06-25 14:25:14 -05008104 image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008105 any image that successfully builds to automatically boot under QEMU.
8106 Using the variable also adds in dependencies so that any SDK for
8107 which testing is requested is automatically built first.
8108
8109 These tests are written in Python making use of the ``unittest``
8110 module, and the majority of them run commands on the target system
8111 over ``ssh``. You can set this variable to "1" in your ``local.conf``
8112 file in the :term:`Build Directory` to have the
8113 OpenEmbedded build system automatically run these tests after an
8114 image successfully builds:
8115
8116 TESTIMAGE_AUTO = "1"
8117
8118 For more information
8119 on enabling, running, and writing these tests, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008120 ":ref:`dev-manual/common-tasks:performing automated runtime testing`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008121 section in the Yocto Project Development Tasks Manual and the
8122 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section.
8123
Andrew Geisslerf0343792020-11-18 10:42:21 -06008124 :term:`THISDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008125 The directory in which the file BitBake is currently parsing is
8126 located. Do not manually set this variable.
8127
Andrew Geisslerf0343792020-11-18 10:42:21 -06008128 :term:`TIME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008129 The time the build was started. Times appear using the hour, minute,
8130 and second (HMS) format (e.g. "140159" for one minute and fifty-nine
8131 seconds past 1400 hours).
8132
Andrew Geisslerf0343792020-11-18 10:42:21 -06008133 :term:`TMPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008134 This variable is the base directory the OpenEmbedded build system
8135 uses for all build output and intermediate files (other than the
Andrew Geissler09036742021-06-25 14:25:14 -05008136 shared state cache). By default, the :term:`TMPDIR` variable points to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008137 ``tmp`` within the :term:`Build Directory`.
8138
8139 If you want to establish this directory in a location other than the
8140 default, you can uncomment and edit the following statement in the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008141 ``conf/local.conf`` file in the :term:`Source Directory`::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008142
8143 #TMPDIR = "${TOPDIR}/tmp"
8144
Andrew Geissler09036742021-06-25 14:25:14 -05008145 An example use for this scenario is to set :term:`TMPDIR` to a local disk,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008146 which does not use NFS, while having the Build Directory use NFS.
8147
Andrew Geissler09036742021-06-25 14:25:14 -05008148 The filesystem used by :term:`TMPDIR` must have standard filesystem
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008149 semantics (i.e. mixed-case files are unique, POSIX file locking, and
8150 persistent inodes). Due to various issues with NFS and bugs in some
8151 implementations, NFS does not meet this minimum requirement.
Andrew Geissler09036742021-06-25 14:25:14 -05008152 Consequently, :term:`TMPDIR` cannot be on NFS.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008153
Andrew Geisslerf0343792020-11-18 10:42:21 -06008154 :term:`TOOLCHAIN_HOST_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008155 This variable lists packages the OpenEmbedded build system uses when
8156 building an SDK, which contains a cross-development environment. The
8157 packages specified by this variable are part of the toolchain set
8158 that runs on the :term:`SDKMACHINE`, and each
8159 package should usually have the prefix ``nativesdk-``. For example,
Andrew Geisslerc926e172021-05-07 16:11:35 -05008160 consider the following command when building an SDK::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008161
8162 $ bitbake -c populate_sdk imagename
8163
8164 In this case, a default list of packages is
8165 set in this variable, but you can add additional packages to the
8166 list. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008167 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008168 in the Yocto Project Application Development and the Extensible
8169 Software Development Kit (eSDK) manual for more information.
8170
8171 For background information on cross-development toolchains in the
8172 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008173 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008174 section in the Yocto Project Overview and Concepts Manual. For
8175 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008176 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008177
Andrew Geisslereff27472021-10-29 15:35:00 -05008178 Note that this variable applies to building an SDK, not an eSDK,
8179 in which case the term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be
8180 used instead.
8181
8182 :term:`TOOLCHAIN_HOST_TASK_ESDK`
8183 This variable allows to extend what is installed in the host
8184 portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK`
8185 applying to SDKs.
8186
Andrew Geisslerf0343792020-11-18 10:42:21 -06008187 :term:`TOOLCHAIN_OUTPUTNAME`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008188 This variable defines the name used for the toolchain output. The
8189 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
Andrew Geissler09036742021-06-25 14:25:14 -05008190 the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008191
8192 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
8193
8194 See
8195 the :term:`SDK_NAME` and
8196 :term:`SDK_VERSION` variables for additional
8197 information.
8198
Andrew Geisslerf0343792020-11-18 10:42:21 -06008199 :term:`TOOLCHAIN_TARGET_TASK`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008200 This variable lists packages the OpenEmbedded build system uses when
8201 it creates the target part of an SDK (i.e. the part built for the
8202 target hardware), which includes libraries and headers. Use this
8203 variable to add individual packages to the part of the SDK that runs
8204 on the target. See the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008205 ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008206 in the Yocto Project Application Development and the Extensible
8207 Software Development Kit (eSDK) manual for more information.
8208
8209 For background information on cross-development toolchains in the
8210 Yocto Project development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008211 ":ref:`sdk-manual/intro:the cross-development toolchain`"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008212 section in the Yocto Project Overview and Concepts Manual. For
8213 information on setting up a cross-development environment, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008214 :doc:`/sdk-manual/index` manual.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008215
Andrew Geisslerf0343792020-11-18 10:42:21 -06008216 :term:`TOPDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008217 The top-level :term:`Build Directory`. BitBake
8218 automatically sets this variable when you initialize your build
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008219 environment using :ref:`structure-core-script`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008220
Andrew Geisslerf0343792020-11-18 10:42:21 -06008221 :term:`TRANSLATED_TARGET_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008222 A sanitized version of :term:`TARGET_ARCH`. This
8223 variable is used where the architecture is needed in a value where
8224 underscores are not allowed, for example within package filenames. In
8225 this case, dash characters replace any underscore characters used in
Andrew Geissler09036742021-06-25 14:25:14 -05008226 :term:`TARGET_ARCH`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008227
8228 Do not edit this variable.
8229
Andrew Geisslerf0343792020-11-18 10:42:21 -06008230 :term:`TUNE_ARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008231 The GNU canonical architecture for a specific architecture (i.e.
8232 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
8233 this value to setup configuration.
8234
Andrew Geissler09036742021-06-25 14:25:14 -05008235 :term:`TUNE_ARCH` definitions are specific to a given architecture. The
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008236 definitions can be a single static definition, or can be dynamically
8237 adjusted. You can see details for a given CPU family by looking at
8238 the architecture's ``README`` file. For example, the
8239 ``meta/conf/machine/include/mips/README`` file in the
8240 :term:`Source Directory` provides information for
Andrew Geissler09036742021-06-25 14:25:14 -05008241 :term:`TUNE_ARCH` specific to the ``mips`` architecture.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008242
Andrew Geissler09036742021-06-25 14:25:14 -05008243 :term:`TUNE_ARCH` is tied closely to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008244 :term:`TARGET_ARCH`, which defines the target
8245 machine's architecture. The BitBake configuration file
Andrew Geissler09036742021-06-25 14:25:14 -05008246 (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008247
8248 TARGET_ARCH = "${TUNE_ARCH}"
8249
8250 The following list, which is by no means complete since architectures
8251 are configurable, shows supported machine architectures:
8252
8253 - arm
8254 - i586
8255 - x86_64
8256 - powerpc
8257 - powerpc64
8258 - mips
8259 - mipsel
8260
Andrew Geisslerf0343792020-11-18 10:42:21 -06008261 :term:`TUNE_ASARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008262 Specifies architecture-specific assembler flags for the target
8263 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008264 :term:`TUNE_ASARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008265 typically under ``meta/conf/machine/include/`` and are influenced
8266 through :term:`TUNE_FEATURES`. For example, the
8267 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05008268 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008269
8270 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
8271
8272 .. note::
8273
8274 Board Support Packages (BSPs) select the tune. The selected tune,
8275 in turn, affects the tune variables themselves (i.e. the tune can
8276 supply its own set of flags).
8277
Andrew Geisslerf0343792020-11-18 10:42:21 -06008278 :term:`TUNE_CCARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008279 Specifies architecture-specific C compiler flags for the target
8280 system. The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008281 :term:`TUNE_CCARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008282 typically under ``meta/conf/machine/include/`` and are influenced
8283 through :term:`TUNE_FEATURES`.
8284
8285 .. note::
8286
8287 Board Support Packages (BSPs) select the tune. The selected tune,
8288 in turn, affects the tune variables themselves (i.e. the tune can
8289 supply its own set of flags).
8290
Andrew Geisslerf0343792020-11-18 10:42:21 -06008291 :term:`TUNE_FEATURES`
8292 Features used to "tune" a compiler for optimal use given a specific
8293 processor. The features are defined within the tune files and allow
8294 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
8295 the features.
8296
8297 The OpenEmbedded build system verifies the features to be sure they
8298 are not conflicting and that they are supported.
8299
8300 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
Andrew Geissler09036742021-06-25 14:25:14 -05008301 :term:`TUNE_FEATURES` as follows::
Andrew Geisslerf0343792020-11-18 10:42:21 -06008302
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008303 TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008304
8305 See the :term:`DEFAULTTUNE` variable for more information.
8306
8307 :term:`TUNE_LDARGS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008308 Specifies architecture-specific linker flags for the target system.
8309 The set of flags is based on the selected tune features.
Andrew Geissler09036742021-06-25 14:25:14 -05008310 :term:`TUNE_LDARGS` is set using the tune include files, which are
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008311 typically under ``meta/conf/machine/include/`` and are influenced
8312 through :term:`TUNE_FEATURES`. For example, the
8313 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
Andrew Geisslerc926e172021-05-07 16:11:35 -05008314 for the x86 architecture as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008315
8316 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
8317
8318 .. note::
8319
8320 Board Support Packages (BSPs) select the tune. The selected tune,
8321 in turn, affects the tune variables themselves (i.e. the tune can
8322 supply its own set of flags).
8323
Andrew Geisslerf0343792020-11-18 10:42:21 -06008324 :term:`TUNE_PKGARCH`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008325 The package architecture understood by the packaging system to define
8326 the architecture, ABI, and tuning of output packages. The specific
Andrew Geisslerc926e172021-05-07 16:11:35 -05008327 tune is defined using the "_tune" override as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008328
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008329 TUNE_PKGARCH:tune-tune = "tune"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008330
8331 These tune-specific package architectures are defined in the machine
8332 include files. Here is an example of the "core2-32" tuning as used in
Andrew Geisslerd159c7f2021-09-02 21:05:58 -05008333 the ``meta/conf/machine/include/x86/tune-core2.inc`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008334
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008335 TUNE_PKGARCH:tune-core2-32 = "core2-32"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008336
Andrew Geisslerf0343792020-11-18 10:42:21 -06008337 :term:`TUNEABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008338 An underlying Application Binary Interface (ABI) used by a particular
8339 tuning in a given toolchain layer. Providers that use prebuilt
Andrew Geissler09036742021-06-25 14:25:14 -05008340 libraries can use the :term:`TUNEABI`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008341 :term:`TUNEABI_OVERRIDE`, and
8342 :term:`TUNEABI_WHITELIST` variables to check
8343 compatibility of tunings against their selection of libraries.
8344
Andrew Geissler09036742021-06-25 14:25:14 -05008345 If :term:`TUNEABI` is undefined, then every tuning is allowed. See the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008346 :ref:`sanity <ref-classes-sanity>` class to see how the variable is
8347 used.
8348
Andrew Geisslerf0343792020-11-18 10:42:21 -06008349 :term:`TUNEABI_OVERRIDE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008350 If set, the OpenEmbedded system ignores the
8351 :term:`TUNEABI_WHITELIST` variable.
8352 Providers that use prebuilt libraries can use the
Andrew Geissler09036742021-06-25 14:25:14 -05008353 :term:`TUNEABI_OVERRIDE`, :term:`TUNEABI_WHITELIST`, and
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008354 :term:`TUNEABI` variables to check compatibility of a
8355 tuning against their selection of libraries.
8356
8357 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8358 variable is used.
8359
Andrew Geisslerf0343792020-11-18 10:42:21 -06008360 :term:`TUNEABI_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008361 A whitelist of permissible :term:`TUNEABI` values. If
Andrew Geissler09036742021-06-25 14:25:14 -05008362 :term:`TUNEABI_WHITELIST` is not set, all tunes are allowed. Providers
8363 that use prebuilt libraries can use the :term:`TUNEABI_WHITELIST`,
8364 :term:`TUNEABI_OVERRIDE`, and :term:`TUNEABI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008365 variables to check compatibility of a tuning against their selection
8366 of libraries.
8367
8368 See the :ref:`sanity <ref-classes-sanity>` class to see how the
8369 variable is used.
8370
Andrew Geisslerf0343792020-11-18 10:42:21 -06008371 :term:`TUNECONFLICTS[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008372 Specifies CPU or Application Binary Interface (ABI) tuning features
8373 that conflict with feature.
8374
8375 Known tuning conflicts are specified in the machine include files in
8376 the :term:`Source Directory`. Here is an example from
8377 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
8378 that lists the "o32" and "n64" features as conflicting with the "n32"
Andrew Geisslerc926e172021-05-07 16:11:35 -05008379 feature::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008380
8381 TUNECONFLICTS[n32] = "o32 n64"
8382
Andrew Geisslerf0343792020-11-18 10:42:21 -06008383 :term:`TUNEVALID[feature]`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008384 Specifies a valid CPU or Application Binary Interface (ABI) tuning
8385 feature. The specified feature is stored as a flag. Valid features
8386 are specified in the machine include files (e.g.
8387 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
Andrew Geisslerc926e172021-05-07 16:11:35 -05008388 from that file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008389
8390 TUNEVALID[bigendian] = "Enable big-endian mode."
8391
8392 See the machine include files in the :term:`Source Directory`
8393 for these features.
8394
Andrew Geisslerf0343792020-11-18 10:42:21 -06008395 :term:`UBOOT_CONFIG`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008396 Configures the :term:`UBOOT_MACHINE` and can
8397 also define :term:`IMAGE_FSTYPES` for individual
8398 cases.
8399
8400 Following is an example from the ``meta-fsl-arm`` layer. ::
8401
8402 UBOOT_CONFIG ??= "sd"
8403 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
8404 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
8405 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
8406 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
8407
8408 In this example, "sd" is selected as the configuration of the possible four for the
Andrew Geissler09036742021-06-25 14:25:14 -05008409 :term:`UBOOT_MACHINE`. The "sd" configuration defines
8410 "mx6qsabreauto_config" as the value for :term:`UBOOT_MACHINE`, while the
Andrew Geissler5f350902021-07-23 13:09:54 -04008411 "sdcard" specifies the :term:`IMAGE_FSTYPES` to use for the U-Boot image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008412
Andrew Geissler09036742021-06-25 14:25:14 -05008413 For more information on how the :term:`UBOOT_CONFIG` is handled, see the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008414 :ref:`uboot-config <ref-classes-uboot-config>`
8415 class.
8416
Andrew Geisslerf0343792020-11-18 10:42:21 -06008417 :term:`UBOOT_DTB_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008418 Specifies the load address for the dtb image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05008419 image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008420 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify
8421 the load address to be used in
8422 creating the dtb sections of Image Tree Source for the FIT image.
8423
Andrew Geisslerf0343792020-11-18 10:42:21 -06008424 :term:`UBOOT_DTBO_LOADADDRESS`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008425 Specifies the load address for the dtbo image used by U-Boot. During FIT
Andrew Geissler09036742021-06-25 14:25:14 -05008426 image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008427 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in
8428 creating the dtbo sections of Image Tree Source for the FIT image.
8429
Andrew Geisslerf0343792020-11-18 10:42:21 -06008430 :term:`UBOOT_ENTRYPOINT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008431 Specifies the entry point for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05008432 creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008433 command-line parameter to the ``uboot-mkimage`` utility.
8434
Andrew Geisslerf0343792020-11-18 10:42:21 -06008435 :term:`UBOOT_LOADADDRESS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008436 Specifies the load address for the U-Boot image. During U-Boot image
Andrew Geissler09036742021-06-25 14:25:14 -05008437 creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008438 command-line parameter to the ``uboot-mkimage`` utility.
8439
Andrew Geisslerf0343792020-11-18 10:42:21 -06008440 :term:`UBOOT_LOCALVERSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008441 Appends a string to the name of the local version of the U-Boot
8442 image. For example, assuming the version of the U-Boot image built
8443 was "2013.10", the full version string reported by U-Boot would be
Andrew Geisslerc926e172021-05-07 16:11:35 -05008444 "2013.10-yocto" given the following statement::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008445
8446 UBOOT_LOCALVERSION = "-yocto"
8447
Andrew Geisslerf0343792020-11-18 10:42:21 -06008448 :term:`UBOOT_MACHINE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008449 Specifies the value passed on the ``make`` command line when building
8450 a U-Boot image. The value indicates the target platform
8451 configuration. You typically set this variable from the machine
8452 configuration file (i.e. ``conf/machine/machine_name.conf``).
8453
8454 Please see the "Selection of Processor Architecture and Board Type"
8455 section in the U-Boot README for valid values for this variable.
8456
Andrew Geisslerf0343792020-11-18 10:42:21 -06008457 :term:`UBOOT_MAKE_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008458 Specifies the target called in the ``Makefile``. The default target
8459 is "all".
8460
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008461 :term:`UBOOT_MKIMAGE`
8462 Specifies the name of the mkimage command as used by the
8463 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble
8464 the FIT image. This can be used to substitute an alternative command, wrapper
8465 script or function if desired. The default is "uboot-mkimage".
8466
Andrew Geisslerf0343792020-11-18 10:42:21 -06008467 :term:`UBOOT_MKIMAGE_DTCOPTS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008468 Options for the device tree compiler passed to mkimage '-D'
8469 feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class.
Andrew Geissler5f350902021-07-23 13:09:54 -04008470 If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then kernel-fitimage will not
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008471 pass the ``-D`` option to mkimage.
8472
8473 :term:`UBOOT_MKIMAGE_SIGN`
8474 Specifies the name of the mkimage command as used by the
8475 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign
8476 the FIT image after it has been assembled (if enabled). This can be used
8477 to substitute an alternative command, wrapper script or function if
8478 desired. The default is "${:term:`UBOOT_MKIMAGE`}".
8479
8480 :term:`UBOOT_MKIMAGE_SIGN_ARGS`
8481 Optionally specifies additional arguments for the
8482 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the
8483 mkimage command when signing the FIT image.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008484
Andrew Geisslerf0343792020-11-18 10:42:21 -06008485 :term:`UBOOT_RD_ENTRYPOINT`
Andrew Geissler4873add2020-11-02 18:44:49 -06008486 Specifies the entrypoint for the RAM disk image.
8487 During FIT image creation, the
Andrew Geissler09036742021-06-25 14:25:14 -05008488 :term:`UBOOT_RD_ENTRYPOINT` variable is used
Andrew Geissler4873add2020-11-02 18:44:49 -06008489 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
8490 entrypoint to be used in creating the Image Tree Source for
8491 the FIT image.
8492
Andrew Geisslerf0343792020-11-18 10:42:21 -06008493 :term:`UBOOT_RD_LOADADDRESS`
8494 Specifies the load address for the RAM disk image.
8495 During FIT image creation, the
Andrew Geissler09036742021-06-25 14:25:14 -05008496 :term:`UBOOT_RD_LOADADDRESS` variable is used
Andrew Geisslerf0343792020-11-18 10:42:21 -06008497 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
8498 load address to be used in creating the Image Tree Source for
8499 the FIT image.
8500
8501 :term:`UBOOT_SIGN_ENABLE`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008502 Enable signing of FIT image. The default value is "0".
8503
Andrew Geisslerf0343792020-11-18 10:42:21 -06008504 :term:`UBOOT_SIGN_KEYDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008505 Location of the directory containing the RSA key and
8506 certificate used for signing FIT image.
8507
Andrew Geisslerf0343792020-11-18 10:42:21 -06008508 :term:`UBOOT_SIGN_KEYNAME`
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008509 The name of keys used for signing U-Boot FIT image stored in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008510 :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt
8511 certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have
8512 :term:`UBOOT_SIGN_KEYNAME` set to "dev".
8513
Andrew Geisslerf0343792020-11-18 10:42:21 -06008514 :term:`UBOOT_SUFFIX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008515 Points to the generated U-Boot extension. For example, ``u-boot.sb``
8516 has a ``.sb`` extension.
8517
8518 The default U-Boot extension is ``.bin``
8519
Andrew Geisslerf0343792020-11-18 10:42:21 -06008520 :term:`UBOOT_TARGET`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008521 Specifies the target used for building U-Boot. The target is passed
8522 directly as part of the "make" command (e.g. SPL and AIS). If you do
8523 not specifically set this variable, the OpenEmbedded build process
8524 passes and uses "all" for the target during the U-Boot building
8525 process.
8526
Andrew Geisslerf0343792020-11-18 10:42:21 -06008527 :term:`UNKNOWN_CONFIGURE_WHITELIST`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008528 Specifies a list of options that, if reported by the configure script
8529 as being invalid, should not generate a warning during the
8530 :ref:`ref-tasks-configure` task. Normally, invalid
8531 configure options are simply not passed to the configure script (e.g.
8532 should be removed from :term:`EXTRA_OECONF` or
8533 :term:`PACKAGECONFIG_CONFARGS`).
William A. Kennington IIIac69b482021-06-02 12:28:27 -07008534 However, there are common options that are passed to all
8535 configure scripts at a class level, but might not be valid for some
8536 configure scripts. Therefore warnings about these options are useless.
Andrew Geissler09036742021-06-25 14:25:14 -05008537 For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_WHITELIST`.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008538
8539 The configure arguments check that uses
Andrew Geissler09036742021-06-25 14:25:14 -05008540 :term:`UNKNOWN_CONFIGURE_WHITELIST` is part of the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008541 :ref:`insane <ref-classes-insane>` class and is only enabled if the
8542 recipe inherits the :ref:`autotools <ref-classes-autotools>` class.
8543
Andrew Geisslerf0343792020-11-18 10:42:21 -06008544 :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008545 For recipes inheriting the
Andrew Geissler09036742021-06-25 14:25:14 -05008546 :ref:`update-rc.d <ref-classes-update-rc.d>` class, :term:`UPDATERCPN`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008547 specifies the package that contains the initscript that is enabled.
8548
8549 The default value is "${PN}". Given that almost all recipes that
8550 install initscripts package them in the main package for the recipe,
8551 you rarely need to set this variable in individual recipes.
8552
Andrew Geissler5199d832021-09-24 16:47:35 -05008553 :term:`UPSTREAM_CHECK_COMMITS`
8554 You can perform a per-recipe check for what the latest upstream
8555 source code version is by calling ``devtool latest-version recipe``. If
8556 the recipe source code is provided from Git repositories, but
8557 releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS`
8558 to ``1`` in the recipe, and the OpenEmbedded build system
8559 will compare the latest commit with the one currently specified
8560 by the recipe (:term:`SRCREV`).
8561 ::
8562
8563 UPSTREAM_CHECK_COMMITS = "1"
8564
Andrew Geisslerf0343792020-11-18 10:42:21 -06008565 :term:`UPSTREAM_CHECK_GITTAGREGEX`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008566 You can perform a per-recipe check for what the latest upstream
Andrew Geissler5199d832021-09-24 16:47:35 -05008567 source code version is by calling ``devtool latest-version recipe``. If
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008568 the recipe source code is provided from Git repositories, the
8569 OpenEmbedded build system determines the latest upstream version by
8570 picking the latest tag from the list of all repository tags.
8571
Andrew Geissler09036742021-06-25 14:25:14 -05008572 You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008573 regular expression to filter only the relevant tags should the
8574 default filter not work correctly.
8575 ::
8576
8577 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
8578
Andrew Geisslerf0343792020-11-18 10:42:21 -06008579 :term:`UPSTREAM_CHECK_REGEX`
Andrew Geissler09036742021-06-25 14:25:14 -05008580 Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008581 regular expression instead of the default one when the package
8582 checking system is parsing the page found using
8583 :term:`UPSTREAM_CHECK_URI`.
8584 ::
8585
8586 UPSTREAM_CHECK_REGEX = "package_regex"
8587
Andrew Geisslerf0343792020-11-18 10:42:21 -06008588 :term:`UPSTREAM_CHECK_URI`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008589 You can perform a per-recipe check for what the latest upstream
Andrew Geissler5199d832021-09-24 16:47:35 -05008590 source code version is by calling ``devtool latest-version recipe``. If
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008591 the source code is provided from tarballs, the latest version is
8592 determined by fetching the directory listing where the tarball is and
8593 attempting to find a later tarball. When this approach does not work,
Andrew Geissler09036742021-06-25 14:25:14 -05008594 you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008595 contains the link to the latest tarball.
8596 ::
8597
8598 UPSTREAM_CHECK_URI = "recipe_url"
8599
Andrew Geissler5199d832021-09-24 16:47:35 -05008600 :term:`UPSTREAM_VERSION_UNKNOWN`
8601 You can perform a per-recipe check for what the latest upstream
8602 source code version is by calling ``devtool latest-version recipe``.
8603 If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`,
8604 :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in
8605 the recipe allows to determine what the latest upstream version is,
8606 you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe
8607 to acknowledge that the check cannot be performed.
8608 ::
8609
8610 UPSTREAM_VERSION_UNKNOWN = "1"
8611
Andrew Geisslerf0343792020-11-18 10:42:21 -06008612 :term:`USE_DEVFS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008613 Determines if ``devtmpfs`` is used for ``/dev`` population. The
Andrew Geissler09036742021-06-25 14:25:14 -05008614 default value used for :term:`USE_DEVFS` is "1" when no value is
8615 specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008616 statically populated ``/dev`` directory.
8617
Andrew Geissler09209ee2020-12-13 08:44:15 -06008618 See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008619 the Yocto Project Development Tasks Manual for information on how to
8620 use this variable.
8621
Andrew Geisslerf0343792020-11-18 10:42:21 -06008622 :term:`USE_VT`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008623 When using
Andrew Geissler09209ee2020-12-13 08:44:15 -06008624 :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`,
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008625 determines whether or not to run a
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008626 `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008627 virtual terminals in order to enable logging in through those
8628 terminals.
8629
Andrew Geissler09036742021-06-25 14:25:14 -05008630 The default value used for :term:`USE_VT` is "1" when no default value is
8631 specifically set. Typically, you would set :term:`USE_VT` to "0" in the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008632 machine configuration file for machines that do not have a graphical
8633 display attached and therefore do not need virtual terminal
8634 functionality.
8635
Andrew Geisslerf0343792020-11-18 10:42:21 -06008636 :term:`USER_CLASSES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008637 A list of classes to globally inherit. These classes are used by the
8638 OpenEmbedded build system to enable extra features (e.g.
Andrew Geissler5f350902021-07-23 13:09:54 -04008639 ``buildstats``, ``image-prelink``, and so forth).
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008640
Andrew Geisslerc926e172021-05-07 16:11:35 -05008641 The default list is set in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008642
Andrew Geissler5f350902021-07-23 13:09:54 -04008643 USER_CLASSES ?= "buildstats image-prelink"
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008644
8645 For more information, see
8646 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`.
8647
Andrew Geisslerf0343792020-11-18 10:42:21 -06008648 :term:`USERADD_ERROR_DYNAMIC`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008649 If set to ``error``, forces the OpenEmbedded build system to produce
8650 an error if the user identification (``uid``) and group
8651 identification (``gid``) values are not defined in any of the files
8652 listed in :term:`USERADD_UID_TABLES` and
8653 :term:`USERADD_GID_TABLES`. If set to
8654 ``warn``, a warning will be issued instead.
8655
8656 The default behavior for the build system is to dynamically apply
8657 ``uid`` and ``gid`` values. Consequently, the
Andrew Geissler09036742021-06-25 14:25:14 -05008658 :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008659 on using statically assigned ``gid`` and ``uid`` values, you should
Andrew Geissler09036742021-06-25 14:25:14 -05008660 set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf``
Andrew Geisslerc926e172021-05-07 16:11:35 -05008661 file as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008662
8663 USERADD_ERROR_DYNAMIC = "error"
8664
8665 Overriding the
8666 default behavior implies you are going to also take steps to set
8667 static ``uid`` and ``gid`` values through use of the
8668 :term:`USERADDEXTENSION`,
8669 :term:`USERADD_UID_TABLES`, and
8670 :term:`USERADD_GID_TABLES` variables.
8671
8672 .. note::
8673
8674 There is a difference in behavior between setting
Andrew Geissler09036742021-06-25 14:25:14 -05008675 :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``.
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008676 When it is set to ``warn``, the build system will report a warning for
8677 every undefined ``uid`` and ``gid`` in any recipe. But when it is set
8678 to ``error``, it will only report errors for recipes that are actually
8679 built.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008680 This saves you from having to add static IDs for recipes that you
8681 know will never be built.
8682
Andrew Geisslerf0343792020-11-18 10:42:21 -06008683 :term:`USERADD_GID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008684 Specifies a password file to use for obtaining static group
8685 identification (``gid``) values when the OpenEmbedded build system
8686 adds a group to the system during package installation.
8687
8688 When applying static group identification (``gid``) values, the
8689 OpenEmbedded build system looks in :term:`BBPATH` for a
8690 ``files/group`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008691 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008692
8693
8694 USERADD_GID_TABLES = "files/group"
8695
8696 .. note::
8697
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008698 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
8699 causes the build system to use static ``gid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008700
Andrew Geisslerf0343792020-11-18 10:42:21 -06008701 :term:`USERADD_PACKAGES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008702 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
8703 this variable specifies the individual packages within the recipe
8704 that require users and/or groups to be added.
8705
8706 You must set this variable if the recipe inherits the class. For
8707 example, the following enables adding a user for the main package in
Andrew Geisslerc926e172021-05-07 16:11:35 -05008708 a recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008709
8710 USERADD_PACKAGES = "${PN}"
8711
8712 .. note::
8713
Andrew Geissler09036742021-06-25 14:25:14 -05008714 It follows that if you are going to use the :term:`USERADD_PACKAGES`
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008715 variable, you need to set one or more of the :term:`USERADD_PARAM`,
8716 :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008717
Andrew Geisslerf0343792020-11-18 10:42:21 -06008718 :term:`USERADD_PARAM`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008719 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
8720 this variable specifies for a package what parameters should pass to
8721 the ``useradd`` command if you add a user to the system when the
8722 package is installed.
8723
Andrew Geisslerc926e172021-05-07 16:11:35 -05008724 Here is an example from the ``dbus`` recipe::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008725
Patrick Williams0ca19cc2021-08-16 14:03:13 -05008726 USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008727 --no-create-home --shell /bin/false \
8728 --user-group messagebus"
8729
8730 For information on the
8731 standard Linux shell command ``useradd``, see
Andrew Geisslerd1e89492021-02-12 15:35:20 -06008732 https://linux.die.net/man/8/useradd.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008733
Andrew Geisslerf0343792020-11-18 10:42:21 -06008734 :term:`USERADD_UID_TABLES`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008735 Specifies a password file to use for obtaining static user
8736 identification (``uid``) values when the OpenEmbedded build system
8737 adds a user to the system during package installation.
8738
8739 When applying static user identification (``uid``) values, the
8740 OpenEmbedded build system looks in :term:`BBPATH` for a
8741 ``files/passwd`` file and then applies those ``uid`` values. Set the
Andrew Geisslerc926e172021-05-07 16:11:35 -05008742 variable as follows in your ``local.conf`` file::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008743
8744 USERADD_UID_TABLES = "files/passwd"
8745
8746 .. note::
8747
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008748 Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids"
8749 causes the build system to use static ``uid`` values.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008750
Andrew Geisslerf0343792020-11-18 10:42:21 -06008751 :term:`USERADDEXTENSION`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008752 When set to "useradd-staticids", causes the OpenEmbedded build system
8753 to base all user and group additions on a static ``passwd`` and
8754 ``group`` files found in :term:`BBPATH`.
8755
8756 To use static user identification (``uid``) and group identification
8757 (``gid``) values, set the variable as follows in your ``local.conf``
8758 file: USERADDEXTENSION = "useradd-staticids"
8759
8760 .. note::
8761
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008762 Setting this variable to use static ``uid`` and ``gid``
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008763 values causes the OpenEmbedded build system to employ the
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008764 :ref:`ref-classes-useradd` class.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008765
8766 If you use static ``uid`` and ``gid`` information, you must also
8767 specify the ``files/passwd`` and ``files/group`` files by setting the
8768 :term:`USERADD_UID_TABLES` and
8769 :term:`USERADD_GID_TABLES` variables.
8770 Additionally, you should also set the
8771 :term:`USERADD_ERROR_DYNAMIC` variable.
8772
Andrew Geisslerf0343792020-11-18 10:42:21 -06008773 :term:`VOLATILE_LOG_DIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008774 Specifies the persistence of the target's ``/var/log`` directory,
8775 which is used to house postinstall target log files.
8776
Andrew Geissler09036742021-06-25 14:25:14 -05008777 By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008778 file is not persistent. You can override this setting by setting the
8779 variable to "no" to make the log directory persistent.
8780
Andrew Geisslerf0343792020-11-18 10:42:21 -06008781 :term:`WARN_QA`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008782 Specifies the quality assurance checks whose failures are reported as
8783 warnings by the OpenEmbedded build system. You set this variable in
8784 your distribution configuration file. For a list of the checks you
8785 can control with this variable, see the
8786 ":ref:`insane.bbclass <ref-classes-insane>`" section.
8787
Andrew Geisslerf0343792020-11-18 10:42:21 -06008788 :term:`WKS_FILE`
8789 Specifies the location of the Wic kickstart file that is used by the
8790 OpenEmbedded build system to create a partitioned image
Andrew Geisslereff27472021-10-29 15:35:00 -05008791 (``image.wic``). For information on how to create a partitioned
Andrew Geisslerf0343792020-11-18 10:42:21 -06008792 image, see the
Andrew Geissler09209ee2020-12-13 08:44:15 -06008793 ":ref:`dev-manual/common-tasks:creating partitioned images using wic`"
Andrew Geisslerf0343792020-11-18 10:42:21 -06008794 section in the Yocto Project Development Tasks Manual. For details on
Andrew Geissler09209ee2020-12-13 08:44:15 -06008795 the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter.
Andrew Geisslerf0343792020-11-18 10:42:21 -06008796
8797 :term:`WKS_FILE_DEPENDS`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008798 When placed in the recipe that builds your image, this variable lists
Andrew Geissler09036742021-06-25 14:25:14 -05008799 build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008800 applicable when Wic images are active (i.e. when
8801 :term:`IMAGE_FSTYPES` contains entries related
8802 to Wic). If your recipe does not create Wic images, the variable has
8803 no effect.
8804
Andrew Geissler09036742021-06-25 14:25:14 -05008805 The :term:`WKS_FILE_DEPENDS` variable is similar to the
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008806 :term:`DEPENDS` variable. When you use the variable in
8807 your recipe that builds the Wic image, dependencies you list in the
Andrew Geissler09036742021-06-25 14:25:14 -05008808 :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable.
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008809
Andrew Geissler09036742021-06-25 14:25:14 -05008810 With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008811 specify a list of additional dependencies (e.g. native tools,
8812 bootloaders, and so forth), that are required to build Wic images.
Andrew Geisslerc926e172021-05-07 16:11:35 -05008813 Following is an example::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008814
8815 WKS_FILE_DEPENDS = "some-native-tool"
8816
8817 In the
8818 previous example, some-native-tool would be replaced with an actual
8819 native tool on which the build would depend.
8820
Andrew Geisslerf0343792020-11-18 10:42:21 -06008821 :term:`WORKDIR`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008822 The pathname of the work directory in which the OpenEmbedded build
8823 system builds a recipe. This directory is located within the
8824 :term:`TMPDIR` directory structure and is specific to
8825 the recipe being built and the system for which it is being built.
8826
Andrew Geissler09036742021-06-25 14:25:14 -05008827 The :term:`WORKDIR` directory is defined as follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008828
8829 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8830
8831 The actual directory depends on several things:
8832
Andrew Geissler4c19ea12020-10-27 13:52:24 -05008833 - :term:`TMPDIR`: The top-level build output directory
8834 - :term:`MULTIMACH_TARGET_SYS`: The target system identifier
8835 - :term:`PN`: The recipe name
8836 - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which
8837 is usually the case for most recipes, then `EXTENDPE` is blank)
8838 - :term:`PV`: The recipe version
8839 - :term:`PR`: The recipe revision
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008840
8841 As an example, assume a Source Directory top-level folder name
8842 ``poky``, a default Build Directory at ``poky/build``, and a
8843 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
8844 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
8845 directory the build system uses to build the package would be as
Andrew Geisslerc926e172021-05-07 16:11:35 -05008846 follows::
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008847
8848 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8849
Andrew Geisslerf0343792020-11-18 10:42:21 -06008850 :term:`XSERVER`
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008851 Specifies the packages that should be installed to provide an X
8852 server and drivers for the current machine, assuming your image
8853 directly includes ``packagegroup-core-x11-xserver`` or, perhaps
8854 indirectly, includes "x11-base" in
8855 :term:`IMAGE_FEATURES`.
8856
Andrew Geissler09036742021-06-25 14:25:14 -05008857 The default value of :term:`XSERVER`, if not specified in the machine
Andrew Geisslerc9f78652020-09-18 14:11:35 -05008858 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
8859