summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/ref-variables.rst
diff options
context:
space:
mode:
authorNicolas Dechesne <nicolas.dechesne@linaro.org>2020-06-26 19:24:06 +0200
committerRichard Purdie <richard.purdie@linuxfoundation.org>2020-09-17 10:09:33 +0100
commit0b84b3dd769d5d4dd3261836eee989da5ff0353b (patch)
tree153944c6135cae2ca62c92818f872ed7f9a50d6f /documentation/ref-manual/ref-variables.rst
parent9bd69b1f1d71a9692189beeac75af9dfbad816cc (diff)
downloadpoky-0b84b3dd769d5d4dd3261836eee989da5ff0353b.tar.gz
sphinx: ref-variables: use builtin sphinx glossary
Sphinx has a glossary directive. From the documentation: This directive must contain a reST definition list with terms and definitions. The definitions will then be referencable with the 'term' role. So anywhere in *any* manual, we can do :term:`VAR` to refer to an item from the glossary, and create a link. An HTML anchor is created for each term in the glossary, and can be accessed as: <link>/ref-variables.html#term-<NAME> To convert to a glossary, we needed proper indentation (e.g. added 3 spaces to each line) (From yocto-docs rev: af16cc4233ae9672698cf2fbb7bf0a78e461122e) Signed-off-by: Nicolas Dechesne <nicolas.dechesne@linaro.org> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual/ref-variables.rst')
-rw-r--r--documentation/ref-manual/ref-variables.rst15786
1 files changed, 7893 insertions, 7893 deletions
diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
index 3fa1b6ccaa..485fbb27f5 100644
--- a/documentation/ref-manual/ref-variables.rst
+++ b/documentation/ref-manual/ref-variables.rst
@@ -1,3 +1,5 @@
1.. SPDX-License-Identifier: CC-BY-2.0-UK
2
1****************** 3******************
2Variables Glossary 4Variables Glossary
3****************** 5******************
@@ -5,7920 +7,7918 @@ Variables Glossary
5This chapter lists common variables used in the OpenEmbedded build 7This chapter lists common variables used in the OpenEmbedded build
6system and gives an overview of their function and contents. 8system and gives an overview of their function and contents.
7 9
8`A <#var-ABIEXTENSION>`__ `B <#var-B>`__ `C <#var-CACHE>`__ 10`A <#var-ABIEXTENSION>`__ :term:`B` `C <#var-CACHE>`__
9`D <#var-D>`__ `E <#var-EFI_PROVIDER>`__ `F <#var-FEATURE_PACKAGES>`__ 11:term:`D` `E <#var-EFI_PROVIDER>`__ `F <#var-FEATURE_PACKAGES>`__
10`G <#var-GCCPIE>`__ `H <#var-HOMEPAGE>`__ `I <#var-ICECC_DISABLED>`__ 12`G <#var-GCCPIE>`__ `H <#var-HOMEPAGE>`__ `I <#var-ICECC_DISABLED>`__
11`K <#var-KARCH>`__ `L <#var-LABELS>`__ `M <#var-MACHINE>`__ 13`K <#var-KARCH>`__ `L <#var-LABELS>`__ `M <#var-MACHINE>`__
12`N <#var-NATIVELSBSTRING>`__ `O <#var-OBJCOPY>`__ `P <#var-P>`__ 14`N <#var-NATIVELSBSTRING>`__ `O <#var-OBJCOPY>`__ :term:`P`
13`R <#var-RANLIB>`__ `S <#var-S>`__ `T <#var-T>`__ 15`R <#var-RANLIB>`__ :term:`S` :term:`T`
14`U <#var-UBOOT_CONFIG>`__ `V <#var-VOLATILE_LOG_DIR>`__ 16`U <#var-UBOOT_CONFIG>`__ `V <#var-VOLATILE_LOG_DIR>`__
15`W <#var-WARN_QA>`__ `X <#var-XSERVER>`__ 17`W <#var-WARN_QA>`__ `X <#var-XSERVER>`__
16 18
17ABIEXTENSION 19.. glossary::
18 Extension to the Application Binary Interface (ABI) field of the GNU 20
19 canonical architecture name (e.g. "eabi"). 21 ABIEXTENSION
20 22 Extension to the Application Binary Interface (ABI) field of the GNU
21 ABI extensions are set in the machine include files. For example, the 23 canonical architecture name (e.g. "eabi").
22 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the 24
23 following extension: ABIEXTENSION = "eabi" 25 ABI extensions are set in the machine include files. For example, the
24 26 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
25ALLOW_EMPTY 27 following extension: ABIEXTENSION = "eabi"
26 Specifies whether to produce an output package even if it is empty. 28
27 By default, BitBake does not produce empty packages. This default 29 ALLOW_EMPTY
28 behavior can cause issues when there is an 30 Specifies whether to produce an output package even if it is empty.
29 ```RDEPENDS`` <#var-RDEPENDS>`__ or some other hard runtime 31 By default, BitBake does not produce empty packages. This default
30 requirement on the existence of the package. 32 behavior can cause issues when there is an
31 33 :term:`RDEPENDS` or some other hard runtime
32 Like all package-controlling variables, you must always use them in 34 requirement on the existence of the package.
33 conjunction with a package name override, as in: ALLOW_EMPTY_${PN} = 35
34 "1" ALLOW_EMPTY_${PN}-dev = "1" ALLOW_EMPTY_${PN}-staticdev = "1" 36 Like all package-controlling variables, you must always use them in
35 37 conjunction with a package name override, as in: ALLOW_EMPTY_${PN} =
36ALTERNATIVE 38 "1" ALLOW_EMPTY_${PN}-dev = "1" ALLOW_EMPTY_${PN}-staticdev = "1"
37 Lists commands in a package that need an alternative binary naming 39
38 scheme. Sometimes the same command is provided in multiple packages. 40 ALTERNATIVE
39 When this occurs, the OpenEmbedded build system needs to use the 41 Lists commands in a package that need an alternative binary naming
40 alternatives system to create a different binary naming scheme so the 42 scheme. Sometimes the same command is provided in multiple packages.
41 commands can co-exist. 43 When this occurs, the OpenEmbedded build system needs to use the
42 44 alternatives system to create a different binary naming scheme so the
43 To use the variable, list out the package's commands that also exist 45 commands can co-exist.
44 as part of another package. For example, if the ``busybox`` package 46
45 has four commands that also exist as part of another package, you 47 To use the variable, list out the package's commands that also exist
46 identify them as follows: ALTERNATIVE_busybox = "sh sed test bracket" 48 as part of another package. For example, if the ``busybox`` package
47 For more information on the alternatives system, see the 49 has four commands that also exist as part of another package, you
48 "```update-alternatives.bbclass`` <#ref-classes-update-alternatives>`__" 50 identify them as follows: ALTERNATIVE_busybox = "sh sed test bracket"
49 section. 51 For more information on the alternatives system, see the
50 52 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
51ALTERNATIVE_LINK_NAME 53 section.
52 Used by the alternatives system to map duplicated commands to actual 54
53 locations. For example, if the ``bracket`` command provided by the 55 ALTERNATIVE_LINK_NAME
54 ``busybox`` package is duplicated through another package, you must 56 Used by the alternatives system to map duplicated commands to actual
55 use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual 57 locations. For example, if the ``bracket`` command provided by the
56 location: ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" 58 ``busybox`` package is duplicated through another package, you must
57 59 use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual
58 In this example, the binary for the ``bracket`` command (i.e. ``[``) 60 location: ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
59 from the ``busybox`` package resides in ``/usr/bin/``. 61
60 62 In this example, the binary for the ``bracket`` command (i.e. ``[``)
61 .. note:: 63 from the ``busybox`` package resides in ``/usr/bin/``.
62 64
63 If 65 .. note::
64 ALTERNATIVE_LINK_NAME 66
65 is not defined, it defaults to 67 If
66 ${bindir}/ 68 ALTERNATIVE_LINK_NAME
67 name 69 is not defined, it defaults to
68 . 70 ${bindir}/
69 71 name
70 For more information on the alternatives system, see the 72 .
71 "```update-alternatives.bbclass`` <#ref-classes-update-alternatives>`__" 73
72 section. 74 For more information on the alternatives system, see the
73 75 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
74ALTERNATIVE_PRIORITY 76 section.
75 Used by the alternatives system to create default priorities for 77
76 duplicated commands. You can use the variable to create a single 78 ALTERNATIVE_PRIORITY
77 default regardless of the command name or package, a default for 79 Used by the alternatives system to create default priorities for
78 specific duplicated commands regardless of the package, or a default 80 duplicated commands. You can use the variable to create a single
79 for specific commands tied to particular packages. Here are the 81 default regardless of the command name or package, a default for
80 available syntax forms: ALTERNATIVE_PRIORITY = "priority" 82 specific duplicated commands regardless of the package, or a default
81 ALTERNATIVE_PRIORITY[name] = "priority" 83 for specific commands tied to particular packages. Here are the
82 ALTERNATIVE_PRIORITY_pkg[name] = "priority" 84 available syntax forms: ALTERNATIVE_PRIORITY = "priority"
83 85 ALTERNATIVE_PRIORITY[name] = "priority"
84 For more information on the alternatives system, see the 86 ALTERNATIVE_PRIORITY_pkg[name] = "priority"
85 "```update-alternatives.bbclass`` <#ref-classes-update-alternatives>`__" 87
86 section. 88 For more information on the alternatives system, see the
87 89 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
88ALTERNATIVE_TARGET 90 section.
89 Used by the alternatives system to create default link locations for 91
90 duplicated commands. You can use the variable to create a single 92 ALTERNATIVE_TARGET
91 default location for all duplicated commands regardless of the 93 Used by the alternatives system to create default link locations for
92 command name or package, a default for specific duplicated commands 94 duplicated commands. You can use the variable to create a single
93 regardless of the package, or a default for specific commands tied to 95 default location for all duplicated commands regardless of the
94 particular packages. Here are the available syntax forms: 96 command name or package, a default for specific duplicated commands
95 ALTERNATIVE_TARGET = "target" ALTERNATIVE_TARGET[name] = "target" 97 regardless of the package, or a default for specific commands tied to
96 ALTERNATIVE_TARGET_pkg[name] = "target" 98 particular packages. Here are the available syntax forms:
97 99 ALTERNATIVE_TARGET = "target" ALTERNATIVE_TARGET[name] = "target"
98 .. note:: 100 ALTERNATIVE_TARGET_pkg[name] = "target"
99 101
100 If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value 102 .. note::
101 from the 103
102 ```ALTERNATIVE_LINK_NAME`` <#var-ALTERNATIVE_LINK_NAME>`__ 104 If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value
105 from the
106 :term:`ALTERNATIVE_LINK_NAME`
107 variable.
108
109 If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the
110 same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``"
111 appended to it.
112
113 Finally, if the file referenced has not been renamed, the
114 alternatives system will rename it to avoid the need to rename
115 alternative files in the :ref:`ref-tasks-install`
116 task while retaining support for the command if necessary.
117
118 For more information on the alternatives system, see the
119 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
120 section.
121
122 APPEND
123 An override list of append strings for each target specified with
124 :term:`LABELS`.
125
126 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
127 information on how this variable is used.
128
129 AR
130 The minimal command and arguments used to run ``ar``.
131
132 ARCHIVER_MODE
133 When used with the :ref:`archiver <ref-classes-archiver>` class,
134 determines the type of information used to create a released archive.
135 You can use this variable to create archives of patched source,
136 original source, configured source, and so forth by employing the
137 following variable flags (varflags): ARCHIVER_MODE[src] = "original"
138 # Uses original (unpacked) source # files. ARCHIVER_MODE[src] =
139 "patched" # Uses patched source files. This is # the default.
140 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
141 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and #
142 do_patch. ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists
143 files and directories to # exclude from diff. ARCHIVER_MODE[dumpdata]
144 = "1" # Uses environment data. ARCHIVER_MODE[recipe] = "1" # Uses
145 recipe and include files. ARCHIVER_MODE[srpm] = "1" # Uses RPM
146 package files. For information on how the variable works, see the
147 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
148
149 AS
150 Minimal command and arguments needed to run the assembler.
151
152 ASSUME_PROVIDED
153 Lists recipe names (:term:`PN` values) BitBake does not
154 attempt to build. Instead, BitBake assumes these recipes have already
155 been built.
156
157 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native
158 tools that should not be built. An example is ``git-native``, which
159 when specified, allows for the Git binary from the host to be used
160 rather than building ``git-native``.
161
162 ASSUME_SHLIBS
163 Provides additional ``shlibs`` provider mapping information, which
164 adds to or overwrites the information provided automatically by the
165 system. Separate multiple entries using spaces.
166
167 As an example, use the following form to add an ``shlib`` provider of
168 shlibname in packagename with the optional version:
169 shlibname:packagename[_version]
170
171 Here is an example that adds a shared library named ``libEGL.so.1``
172 as being provided by the ``libegl-implementation`` package:
173 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
174
175 AUTHOR
176 The email address used to contact the original author or authors in
177 order to send patches and forward bugs.
178
179 AUTO_LIBNAME_PKGS
180 When the :ref:`debian <ref-classes-debian>` class is inherited,
181 which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which
182 packages should be checked for libraries and renamed according to
183 Debian library package naming.
184
185 The default value is "${PACKAGES}", which causes the debian class to
186 act on all packages that are explicitly generated by the recipe.
187
188 AUTO_SYSLINUXMENU
189 Enables creating an automatic menu for the syslinux bootloader. You
190 must set this variable in your recipe. The
191 :ref:`syslinux <ref-classes-syslinux>` class checks this variable.
192
193 AUTOREV
194 When ``SRCREV`` is set to the value of this variable, it specifies to
195 use the latest source revision in the repository. Here is an example:
196 SRCREV = "${AUTOREV}"
197
198 If you use the previous statement to retrieve the latest version of
199 software, you need to be sure :term:`PV` contains
200 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you
201 have a kernel recipe that inherits the
202 :ref:`kernel <ref-classes-kernel>` class and you use the previous
203 statement. In this example, ``${SRCPV}`` does not automatically get
204 into ``PV``. Consequently, you need to change ``PV`` in your recipe
205 so that it does contain ``${SRCPV}``.
206
207 For more information see the "`Automatically Incrementing a Binary
208 Package Revision
209 Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__"
210 section in the Yocto Project Development Tasks Manual.
211
212 AVAILABLE_LICENSES
213 List of licenses found in the directories specified by
214 :term:`COMMON_LICENSE_DIR` and
215 :term:`LICENSE_PATH`.
216
217 .. note::
218
219 It is assumed that all changes to
220 COMMON_LICENSE_DIR
221 and
222 LICENSE_PATH
223 have been done before
224 AVAILABLE_LICENSES
225 is defined (in
226 license.bbclass
227 ).
228
229 AVAILTUNES
230 The list of defined CPU and Application Binary Interface (ABI)
231 tunings (i.e. "tunes") available for use by the OpenEmbedded build
232 system.
233
234 The list simply presents the tunes that are available. Not all tunes
235 may be compatible with a particular machine configuration, or with
236 each other in a
237 `Multilib <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__
238 configuration.
239
240 To add a tune to the list, be sure to append it with spaces using the
241 "+=" BitBake operator. Do not simply replace the list by using the
242 "=" operator. See the
243 ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake
244 User Manual for more information.
245
246 B
247 The directory within the :term:`Build Directory` in
248 which the OpenEmbedded build system places generated objects during a
249 recipe's build process. By default, this directory is the same as the
250 :term:`S` directory, which is defined as: S =
251 "${WORKDIR}/${BP}"
252
253 You can separate the (``S``) directory and the directory pointed to
254 by the ``B`` variable. Most Autotools-based recipes support
255 separating these directories. The build system defaults to using
256 separate directories for ``gcc`` and some kernel recipes.
257
258 BAD_RECOMMENDATIONS
259 Lists "recommended-only" packages to not install. Recommended-only
260 packages are packages installed only through the
261 :term:`RRECOMMENDS` variable. You can prevent any
262 of these "recommended" packages from being installed by listing them
263 with the ``BAD_RECOMMENDATIONS`` variable: BAD_RECOMMENDATIONS =
264 "package_name package_name package_name ..."
265
266 You can set this variable globally in your ``local.conf`` file or you
267 can attach it to a specific image recipe by using the recipe name
268 override: BAD_RECOMMENDATIONS_pn-target_image = "package_name"
269
270 It is important to realize that if you choose to not install packages
271 using this variable and some other packages are dependent on them
272 (i.e. listed in a recipe's :term:`RDEPENDS`
273 variable), the OpenEmbedded build system ignores your request and
274 will install the packages to avoid dependency errors.
275
276 Support for this variable exists only when using the IPK and RPM
277 packaging backend. Support does not exist for DEB.
278
279 See the :term:`NO_RECOMMENDATIONS` and the
280 :term:`PACKAGE_EXCLUDE` variables for related
281 information.
282
283 BASE_LIB
284 The library directory name for the CPU or Application Binary
285 Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib
286 context. See the "`Combining Multiple Versions of Library Files into
287 One
288 Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__"
289 section in the Yocto Project Development Tasks Manual for information
290 on Multilib.
291
292 The ``BASE_LIB`` variable is defined in the machine include files in
293 the :term:`Source Directory`. If Multilib is not
294 being used, the value defaults to "lib".
295
296 BASE_WORKDIR
297 Points to the base of the work directory for all recipes. The default
298 value is "${TMPDIR}/work".
299
300 BB_ALLOWED_NETWORKS
301 Specifies a space-delimited list of hosts that the fetcher is allowed
302 to use to obtain the required source code. Following are
303 considerations surrounding this variable:
304
305 - This host list is only used if ``BB_NO_NETWORK`` is either not set
306 or set to "0".
307
308 - Limited support for wildcard matching against the beginning of
309 host names exists. For example, the following setting matches
310 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
311 BB_ALLOWED_NETWORKS = "*.gnu.org"
312
313 .. note::
314
315 The use of the "``*``" character only works at the beginning of
316 a host name and it must be isolated from the remainder of the
317 host name. You cannot use the wildcard character in any other
318 location of the name or combined with the front part of the
319 name.
320
321 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
322 is not.
323
324 - Mirrors not in the host list are skipped and logged in debug.
325
326 - Attempts to access networks not in the host list cause a failure.
327
328 Using ``BB_ALLOWED_NETWORKS`` in conjunction with
329 :term:`PREMIRRORS` is very useful. Adding the host
330 you want to use to ``PREMIRRORS`` results in the source code being
331 fetched from an allowed location and avoids raising an error when a
332 host that is not allowed is in a :term:`SRC_URI`
333 statement. This is because the fetcher does not attempt to use the
334 host listed in ``SRC_URI`` after a successful fetch from the
335 ``PREMIRRORS`` occurs.
336
337 BB_DANGLINGAPPENDS_WARNONLY
338 Defines how BitBake handles situations where an append file
339 (``.bbappend``) has no corresponding recipe file (``.bb``). This
340 condition often occurs when layers get out of sync (e.g. ``oe-core``
341 bumps a recipe version and the old recipe no longer exists and the
342 other layer has not been updated to the new version of the recipe
343 yet).
344
345 The default fatal behavior is safest because it is the sane reaction
346 given something is out of sync. It is important to realize when your
347 changes are no longer being applied.
348
349 You can change the default behavior by setting this variable to "1",
350 "yes", or "true" in your ``local.conf`` file, which is located in the
351 :term:`Build Directory`: Here is an example:
352 BB_DANGLINGAPPENDS_WARNONLY = "1"
353
354 BB_DISKMON_DIRS
355 Monitors disk space and available inodes during the build and allows
356 you to control the build based on these parameters.
357
358 Disk space monitoring is disabled by default. To enable monitoring,
359 add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file
360 found in the :term:`Build Directory`. Use the
361 following form: BB_DISKMON_DIRS = "action,dir,threshold [...]" where:
362 action is: ABORT: Immediately abort the build when a threshold is
363 broken. STOPTASKS: Stop the build after the currently executing tasks
364 have finished when a threshold is broken. WARN: Issue a warning but
365 continue the build when a threshold is broken. Subsequent warnings
366 are issued as defined by the BB_DISKMON_WARNINTERVAL variable, which
367 must be defined in the conf/local.conf file. dir is: Any directory
368 you choose. You can specify one or more directories to monitor by
369 separating the groupings with a space. If two directories are on the
370 same device, only the first directory is monitored. threshold is:
371 Either the minimum available disk space, the minimum number of free
372 inodes, or both. You must specify at least one. To omit one or the
373 other, simply omit the value. Specify the threshold using G, M, K for
374 Gbytes, Mbytes, and Kbytes, respectively. If you do not specify G, M,
375 or K, Kbytes is assumed by default. Do not use GB, MB, or KB.
376
377 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K
378 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS =
379 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
380 The first example works only if you also provide the
381 :term:`BB_DISKMON_WARNINTERVAL`
382 variable in the ``conf/local.conf``. This example causes the build
383 system to immediately abort when either the disk space in
384 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops
385 below 100 Kbytes. Because two directories are provided with the
386 variable, the build system also issue a warning when the disk space
387 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number
388 of free inodes drops below 100 Kbytes. Subsequent warnings are issued
389 during intervals as defined by the ``BB_DISKMON_WARNINTERVAL``
103 variable. 390 variable.
104 391
105 If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the 392 The second example stops the build after all currently executing
106 same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" 393 tasks complete when the minimum disk space in the ``${TMPDIR}``
107 appended to it. 394 directory drops below 1 Gbyte. No disk monitoring occurs for the free
108 395 inodes in this case.
109 Finally, if the file referenced has not been renamed, the 396
110 alternatives system will rename it to avoid the need to rename 397 The final example immediately aborts the build when the number of
111 alternative files in the ```do_install`` <#ref-tasks-install>`__ 398 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
112 task while retaining support for the command if necessary. 399 disk space monitoring for the directory itself occurs in this case.
113 400
114 For more information on the alternatives system, see the 401 BB_DISKMON_WARNINTERVAL
115 "```update-alternatives.bbclass`` <#ref-classes-update-alternatives>`__" 402 Defines the disk space and free inode warning intervals. To set these
116 section. 403 intervals, define the variable in your ``conf/local.conf`` file in
117 404 the :term:`Build Directory`.
118APPEND 405
119 An override list of append strings for each target specified with 406 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you
120 ```LABELS`` <#var-LABELS>`__. 407 must also use the :term:`BB_DISKMON_DIRS`
121 408 variable and define its action as "WARN". During the build,
122 See the ```grub-efi`` <#ref-classes-grub-efi>`__ class for more 409 subsequent warnings are issued each time disk space or number of free
123 information on how this variable is used. 410 inodes further reduces by the respective interval.
124 411
125AR 412 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you
126 The minimal command and arguments used to run ``ar``. 413 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk
127 414 monitoring interval defaults to the following:
128ARCHIVER_MODE 415 BB_DISKMON_WARNINTERVAL = "50M,5K"
129 When used with the ```archiver`` <#ref-classes-archiver>`__ class, 416
130 determines the type of information used to create a released archive. 417 When specifying the variable in your configuration file, use the
131 You can use this variable to create archives of patched source, 418 following form: BB_DISKMON_WARNINTERVAL =
132 original source, configured source, and so forth by employing the 419 "disk_space_interval,disk_inode_interval" where: disk_space_interval
133 following variable flags (varflags): ARCHIVER_MODE[src] = "original" 420 is: An interval of memory expressed in either G, M, or K for Gbytes,
134 # Uses original (unpacked) source # files. ARCHIVER_MODE[src] = 421 Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB.
135 "patched" # Uses patched source files. This is # the default. 422 disk_inode_interval is: An interval of free inodes expressed in
136 ARCHIVER_MODE[src] = "configured" # Uses configured source files. 423 either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You
137 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and # 424 cannot use GB, MB, or KB.
138 do_patch. ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists 425
139 files and directories to # exclude from diff. ARCHIVER_MODE[dumpdata] 426 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
140 = "1" # Uses environment data. ARCHIVER_MODE[recipe] = "1" # Uses 427 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause the
141 recipe and include files. ARCHIVER_MODE[srpm] = "1" # Uses RPM 428 OpenEmbedded build system to issue subsequent warnings each time the
142 package files. For information on how the variable works, see the 429 available disk space further reduces by 50 Mbytes or the number of
143 ``meta/classes/archiver.bbclass`` file in the `Source 430 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
144 Directory <#source-directory>`__. 431 directory. Subsequent warnings based on the interval occur each time
145 432 a respective interval is reached beyond the initial warning (i.e. 1
146AS 433 Gbytes and 100 Kbytes).
147 Minimal command and arguments needed to run the assembler. 434
148 435 BB_GENERATE_MIRROR_TARBALLS
149ASSUME_PROVIDED 436 Causes tarballs of the source control repositories (e.g. Git
150 Lists recipe names (```PN`` <#var-PN>`__ values) BitBake does not 437 repositories), including metadata, to be placed in the
151 attempt to build. Instead, BitBake assumes these recipes have already 438 :term:`DL_DIR` directory.
152 been built. 439
153 440 For performance reasons, creating and placing tarballs of these
154 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native 441 repositories is not the default action by the OpenEmbedded build
155 tools that should not be built. An example is ``git-native``, which 442 system. BB_GENERATE_MIRROR_TARBALLS = "1" Set this variable in your
156 when specified, allows for the Git binary from the host to be used 443 ``local.conf`` file in the :term:`Build Directory`.
157 rather than building ``git-native``. 444
158 445 Once you have the tarballs containing your source files, you can
159ASSUME_SHLIBS 446 clean up your ``DL_DIR`` directory by deleting any Git or other
160 Provides additional ``shlibs`` provider mapping information, which 447 source control work directories.
161 adds to or overwrites the information provided automatically by the 448
162 system. Separate multiple entries using spaces. 449 BB_NUMBER_THREADS
163 450 The maximum number of tasks BitBake should run in parallel at any one
164 As an example, use the following form to add an ``shlib`` provider of 451 time. The OpenEmbedded build system automatically configures this
165 shlibname in packagename with the optional version: 452 variable to be equal to the number of cores on the build system. For
166 shlibname:packagename[_version] 453 example, a system with a dual core processor that also uses
167 454 hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default
168 Here is an example that adds a shared library named ``libEGL.so.1`` 455 to "4".
169 as being provided by the ``libegl-implementation`` package: 456
170 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" 457 For single socket systems (i.e. one CPU), you should not have to
171 458 override this variable to gain optimal parallelism during builds.
172AUTHOR 459 However, if you have very large systems that employ multiple physical
173 The email address used to contact the original author or authors in 460 CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable
174 order to send patches and forward bugs. 461 is not set higher than "20".
175 462
176AUTO_LIBNAME_PKGS 463 For more information on speeding up builds, see the "`Speeding Up a
177 When the ```debian`` <#ref-classes-debian>`__ class is inherited, 464 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the
178 which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which 465 Yocto Project Development Tasks Manual.
179 packages should be checked for libraries and renamed according to 466
180 Debian library package naming. 467 BB_SERVER_TIMEOUT
181 468 Specifies the time (in seconds) after which to unload the BitBake
182 The default value is "${PACKAGES}", which causes the debian class to 469 server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how
183 act on all packages that are explicitly generated by the recipe. 470 long the BitBake server stays resident between invocations.
184 471
185AUTO_SYSLINUXMENU 472 For example, the following statement in your ``local.conf`` file
186 Enables creating an automatic menu for the syslinux bootloader. You 473 instructs the server to be unloaded after 20 seconds of inactivity:
187 must set this variable in your recipe. The 474 BB_SERVER_TIMEOUT = "20" If you want the server to never be unloaded,
188 ```syslinux`` <#ref-classes-syslinux>`__ class checks this variable. 475 set ``BB_SERVER_TIMEOUT`` to "-1".
189 476
190AUTOREV 477 BBCLASSEXTEND
191 When ``SRCREV`` is set to the value of this variable, it specifies to 478 Allows you to extend a recipe so that it builds variants of the
192 use the latest source revision in the repository. Here is an example: 479 software. Common variants for recipes exist such as "natives" like
193 SRCREV = "${AUTOREV}" 480 ``quilt-native``, which is a copy of Quilt built to run on the build
194 481 system; "crosses" such as ``gcc-cross``, which is a compiler built to
195 If you use the previous statement to retrieve the latest version of 482 run on the build machine but produces binaries that run on the target
196 software, you need to be sure ```PV`` <#var-PV>`__ contains 483 :term:`MACHINE`; "nativesdk", which targets the SDK
197 ``${``\ ```SRCPV`` <#var-SRCPV>`__\ ``}``. For example, suppose you 484 machine instead of ``MACHINE``; and "mulitlibs" in the form
198 have a kernel recipe that inherits the 485 "``multilib:``\ multilib_name".
199 `kernel <#ref-classes-kernel>`__ class and you use the previous 486
200 statement. In this example, ``${SRCPV}`` does not automatically get 487 To build a different variant of the recipe with a minimal amount of
201 into ``PV``. Consequently, you need to change ``PV`` in your recipe 488 code, it usually is as simple as adding the following to your recipe:
202 so that it does contain ``${SRCPV}``. 489 BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+
203 490 "multilib:multilib_name"
204 For more information see the "`Automatically Incrementing a Binary 491
205 Package Revision
206 Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__"
207 section in the Yocto Project Development Tasks Manual.
208
209AVAILABLE_LICENSES
210 List of licenses found in the directories specified by
211 ```COMMON_LICENSE_DIR`` <#var-COMMON_LICENSE_DIR>`__ and
212 ```LICENSE_PATH`` <#var-LICENSE_PATH>`__.
213
214 .. note::
215
216 It is assumed that all changes to
217 COMMON_LICENSE_DIR
218 and
219 LICENSE_PATH
220 have been done before
221 AVAILABLE_LICENSES
222 is defined (in
223 license.bbclass
224 ).
225
226AVAILTUNES
227 The list of defined CPU and Application Binary Interface (ABI)
228 tunings (i.e. "tunes") available for use by the OpenEmbedded build
229 system.
230
231 The list simply presents the tunes that are available. Not all tunes
232 may be compatible with a particular machine configuration, or with
233 each other in a
234 `Multilib <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__
235 configuration.
236
237 To add a tune to the list, be sure to append it with spaces using the
238 "+=" BitBake operator. Do not simply replace the list by using the
239 "=" operator. See the "`Basic
240 Syntax <&YOCTO_DOCS_BB_URL;#basic-syntax>`__" section in the BitBake
241 User Manual for more information.
242
243B
244 The directory within the `Build Directory <#build-directory>`__ in
245 which the OpenEmbedded build system places generated objects during a
246 recipe's build process. By default, this directory is the same as the
247 ```S`` <#var-S>`__ directory, which is defined as: S =
248 "${WORKDIR}/${BP}"
249
250 You can separate the (``S``) directory and the directory pointed to
251 by the ``B`` variable. Most Autotools-based recipes support
252 separating these directories. The build system defaults to using
253 separate directories for ``gcc`` and some kernel recipes.
254
255BAD_RECOMMENDATIONS
256 Lists "recommended-only" packages to not install. Recommended-only
257 packages are packages installed only through the
258 ```RRECOMMENDS`` <#var-RRECOMMENDS>`__ variable. You can prevent any
259 of these "recommended" packages from being installed by listing them
260 with the ``BAD_RECOMMENDATIONS`` variable: BAD_RECOMMENDATIONS =
261 "package_name package_name package_name ..."
262
263 You can set this variable globally in your ``local.conf`` file or you
264 can attach it to a specific image recipe by using the recipe name
265 override: BAD_RECOMMENDATIONS_pn-target_image = "package_name"
266
267 It is important to realize that if you choose to not install packages
268 using this variable and some other packages are dependent on them
269 (i.e. listed in a recipe's ```RDEPENDS`` <#var-RDEPENDS>`__
270 variable), the OpenEmbedded build system ignores your request and
271 will install the packages to avoid dependency errors.
272
273 Support for this variable exists only when using the IPK and RPM
274 packaging backend. Support does not exist for DEB.
275
276 See the ```NO_RECOMMENDATIONS`` <#var-NO_RECOMMENDATIONS>`__ and the
277 ```PACKAGE_EXCLUDE`` <#var-PACKAGE_EXCLUDE>`__ variables for related
278 information.
279
280BASE_LIB
281 The library directory name for the CPU or Application Binary
282 Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib
283 context. See the "`Combining Multiple Versions of Library Files into
284 One
285 Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__"
286 section in the Yocto Project Development Tasks Manual for information
287 on Multilib.
288
289 The ``BASE_LIB`` variable is defined in the machine include files in
290 the `Source Directory <#source-directory>`__. If Multilib is not
291 being used, the value defaults to "lib".
292
293BASE_WORKDIR
294 Points to the base of the work directory for all recipes. The default
295 value is "${TMPDIR}/work".
296
297BB_ALLOWED_NETWORKS
298 Specifies a space-delimited list of hosts that the fetcher is allowed
299 to use to obtain the required source code. Following are
300 considerations surrounding this variable:
301
302 - This host list is only used if ``BB_NO_NETWORK`` is either not set
303 or set to "0".
304
305 - Limited support for wildcard matching against the beginning of
306 host names exists. For example, the following setting matches
307 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
308 BB_ALLOWED_NETWORKS = "*.gnu.org"
309
310 .. note:: 492 .. note::
311 493
312 The use of the "``*``" character only works at the beginning of 494 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe
313 a host name and it must be isolated from the remainder of the 495 variants by rewriting variable values and applying overrides such
314 host name. You cannot use the wildcard character in any other 496 as ``_class-native``. For example, to generate a native version of
315 location of the name or combined with the front part of the 497 a recipe, a :term:`DEPENDS` on "foo" is rewritten
316 name. 498 to a ``DEPENDS`` on "foo-native".
317 499
318 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` 500 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once.
319 is not. 501 Parsing once adds some limitations. For example, it is not
320 502 possible to include a different file depending on the variant,
321 - Mirrors not in the host list are skipped and logged in debug. 503 since ``include`` statements are processed when the recipe is
322 504 parsed.
323 - Attempts to access networks not in the host list cause a failure. 505
324 506 BBFILE_COLLECTIONS
325 Using ``BB_ALLOWED_NETWORKS`` in conjunction with 507 Lists the names of configured layers. These names are used to find
326 ```PREMIRRORS`` <#var-PREMIRRORS>`__ is very useful. Adding the host 508 the other ``BBFILE_*`` variables. Typically, each layer will append
327 you want to use to ``PREMIRRORS`` results in the source code being 509 its name to this variable in its ``conf/layer.conf`` file.
328 fetched from an allowed location and avoids raising an error when a 510
329 host that is not allowed is in a ```SRC_URI`` <#var-SRC_URI>`__ 511 BBFILE_PATTERN
330 statement. This is because the fetcher does not attempt to use the 512 Variable that expands to match files from
331 host listed in ``SRC_URI`` after a successful fetch from the 513 :term:`BBFILES` in a particular layer. This variable
332 ``PREMIRRORS`` occurs. 514 is used in the ``conf/layer.conf`` file and must be suffixed with the
333 515 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
334BB_DANGLINGAPPENDS_WARNONLY 516
335 Defines how BitBake handles situations where an append file 517 BBFILE_PRIORITY
336 (``.bbappend``) has no corresponding recipe file (``.bb``). This 518 Assigns the priority for recipe files in each layer.
337 condition often occurs when layers get out of sync (e.g. ``oe-core`` 519
338 bumps a recipe version and the old recipe no longer exists and the 520 This variable is useful in situations where the same recipe appears
339 other layer has not been updated to the new version of the recipe 521 in more than one layer. Setting this variable allows you to
340 yet). 522 prioritize a layer against other layers that contain the same recipe
341 523 - effectively letting you control the precedence for the multiple
342 The default fatal behavior is safest because it is the sane reaction 524 layers. The precedence established through this variable stands
343 given something is out of sync. It is important to realize when your 525 regardless of a recipe's version (:term:`PV` variable). For
344 changes are no longer being applied. 526 example, a layer that has a recipe with a higher ``PV`` value but for
345 527 which the ``BBFILE_PRIORITY`` is set to have a lower precedence still
346 You can change the default behavior by setting this variable to "1", 528 has a lower precedence.
347 "yes", or "true" in your ``local.conf`` file, which is located in the 529
348 `Build Directory <#build-directory>`__: Here is an example: 530 A larger value for the ``BBFILE_PRIORITY`` variable results in a
349 BB_DANGLINGAPPENDS_WARNONLY = "1" 531 higher precedence. For example, the value 6 has a higher precedence
350 532 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable
351BB_DISKMON_DIRS 533 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable
352 Monitors disk space and available inodes during the build and allows 534 for more information. The default priority, if unspecified for a
353 you to control the build based on these parameters. 535 layer with no dependencies, is the lowest defined priority + 1 (or 1
354 536 if no priorities are defined).
355 Disk space monitoring is disabled by default. To enable monitoring, 537
356 add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file 538 .. tip::
357 found in the `Build Directory <#build-directory>`__. Use the 539
358 following form: BB_DISKMON_DIRS = "action,dir,threshold [...]" where: 540 You can use the command
359 action is: ABORT: Immediately abort the build when a threshold is 541 bitbake-layers show-layers
360 broken. STOPTASKS: Stop the build after the currently executing tasks 542 to list all configured layers along with their priorities.
361 have finished when a threshold is broken. WARN: Issue a warning but 543
362 continue the build when a threshold is broken. Subsequent warnings 544 BBFILES
363 are issued as defined by the BB_DISKMON_WARNINTERVAL variable, which 545 A space-separated list of recipe files BitBake uses to build
364 must be defined in the conf/local.conf file. dir is: Any directory 546 software.
365 you choose. You can specify one or more directories to monitor by 547
366 separating the groupings with a space. If two directories are on the 548 When specifying recipe files, you can pattern match using Python's
367 same device, only the first directory is monitored. threshold is: 549 ```glob`https://docs.python.org/3/library/glob.html syntax.
368 Either the minimum available disk space, the minimum number of free 550 For details on the syntax, see the documentation by following the
369 inodes, or both. You must specify at least one. To omit one or the 551 previous link.
370 other, simply omit the value. Specify the threshold using G, M, K for 552
371 Gbytes, Mbytes, and Kbytes, respectively. If you do not specify G, M, 553 BBFILES_DYNAMIC
372 or K, Kbytes is assumed by default. Do not use GB, MB, or KB. 554 Activates content when identified layers are present. You identify
373 555 the layers by the collections that the layers define.
374 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K 556
375 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = 557 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files
376 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 558 whose corresponding ``.bb`` file is in a layer that attempts to
377 The first example works only if you also provide the 559 modify other layers through ``.bbappend`` but does not want to
378 ```BB_DISKMON_WARNINTERVAL`` <#var-BB_DISKMON_WARNINTERVAL>`__ 560 introduce a hard dependency on those other layers.
379 variable in the ``conf/local.conf``. This example causes the build 561
380 system to immediately abort when either the disk space in 562 Use the following form for ``BBFILES_DYNAMIC``:
381 ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops 563 collection_name:filename_pattern The following example identifies two
382 below 100 Kbytes. Because two directories are provided with the 564 collection names and two filename patterns: BBFILES_DYNAMIC += " \\
383 variable, the build system also issue a warning when the disk space 565 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \\
384 in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number 566 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \\ "
385 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 567 This next example shows an error message that occurs because invalid
386 during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` 568 entries are found, which cause parsing to abort: ERROR:
387 variable. 569 BBFILES_DYNAMIC entries must be of the form <collection
388 570 name>:<filename pattern>, not:
389 The second example stops the build after all currently executing 571 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
390 tasks complete when the minimum disk space in the ``${TMPDIR}`` 572 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
391 directory drops below 1 Gbyte. No disk monitoring occurs for the free 573
392 inodes in this case. 574 BBINCLUDELOGS
393 575 Variable that controls how BitBake displays logs on build failure.
394 The final example immediately aborts the build when the number of 576
395 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 577 BBINCLUDELOGS_LINES
396 disk space monitoring for the directory itself occurs in this case. 578 If :term:`BBINCLUDELOGS` is set, specifies the
397 579 maximum number of lines from the task log file to print when
398BB_DISKMON_WARNINTERVAL 580 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``,
399 Defines the disk space and free inode warning intervals. To set these 581 the entire log is printed.
400 intervals, define the variable in your ``conf/local.conf`` file in 582
401 the `Build Directory <#build-directory>`__. 583 BBLAYERS
402 584 Lists the layers to enable during the build. This variable is defined
403 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you 585 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
404 must also use the ```BB_DISKMON_DIRS`` <#var-BB_DISKMON_DIRS>`__ 586 Here is an example: BBLAYERS = " \\
405 variable and define its action as "WARN". During the build, 587 /home/scottrif/poky/meta \\ /home/scottrif/poky/meta-poky \\
406 subsequent warnings are issued each time disk space or number of free 588 /home/scottrif/poky/meta-yocto-bsp \\
407 inodes further reduces by the respective interval. 589 /home/scottrif/poky/meta-mykernel \\ "
408 590
409 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you 591 This example enables four layers, one of which is a custom,
410 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk 592 user-defined layer named ``meta-mykernel``.
411 monitoring interval defaults to the following: 593
412 BB_DISKMON_WARNINTERVAL = "50M,5K" 594 BBMASK
413 595 Prevents BitBake from processing recipes and recipe append files.
414 When specifying the variable in your configuration file, use the 596
415 following form: BB_DISKMON_WARNINTERVAL = 597 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and
416 "disk_space_interval,disk_inode_interval" where: disk_space_interval 598 ``.bbappend`` files. BitBake ignores any recipe or recipe append
417 is: An interval of memory expressed in either G, M, or K for Gbytes, 599 files that match any of the expressions. It is as if BitBake does not
418 Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. 600 see them at all. Consequently, matching files are not parsed or
419 disk_inode_interval is: An interval of free inodes expressed in 601 otherwise used by BitBake.
420 either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You 602
421 cannot use GB, MB, or KB. 603 The values you provide are passed to Python's regular expression
422 604 compiler. Consequently, the syntax follows Python's Regular
423 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 605 Expression (re) syntax. The expressions are compared against the full
424 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause the 606 paths to the files. For complete syntax information, see Python's
425 OpenEmbedded build system to issue subsequent warnings each time the 607 documentation at http://docs.python.org/3/library/re.html#re.
426 available disk space further reduces by 50 Mbytes or the number of 608
427 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` 609 The following example uses a complete regular expression to tell
428 directory. Subsequent warnings based on the interval occur each time 610 BitBake to ignore all recipe and recipe append files in the
429 a respective interval is reached beyond the initial warning (i.e. 1 611 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/"
430 Gbytes and 100 Kbytes). 612 If you want to mask out multiple directories or recipes, you can
431 613 specify multiple regular expression fragments. This next example
432BB_GENERATE_MIRROR_TARBALLS 614 masks out multiple directories and individual recipes: BBMASK +=
433 Causes tarballs of the source control repositories (e.g. Git 615 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK +=
434 repositories), including metadata, to be placed in the 616 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK
435 ```DL_DIR`` <#var-DL_DIR>`__ directory. 617 += "opencv.*\.bbappend" BBMASK += "lzma"
436 618
437 For performance reasons, creating and placing tarballs of these 619 .. note::
438 repositories is not the default action by the OpenEmbedded build 620
439 system. BB_GENERATE_MIRROR_TARBALLS = "1" Set this variable in your 621 When specifying a directory name, use the trailing slash character
440 ``local.conf`` file in the `Build Directory <#build-directory>`__. 622 to ensure you match just that directory name.
441 623
442 Once you have the tarballs containing your source files, you can 624 BBMULTICONFIG
443 clean up your ``DL_DIR`` directory by deleting any Git or other 625 Specifies each additional separate configuration when you are
444 source control work directories. 626 building targets with multiple configurations. Use this variable in
445 627 your ``conf/local.conf`` configuration file. Specify a
446BB_NUMBER_THREADS 628 multiconfigname for each configuration file you are using. For
447 The maximum number of tasks BitBake should run in parallel at any one 629 example, the following line specifies three configuration files:
448 time. The OpenEmbedded build system automatically configures this 630 BBMULTICONFIG = "configA configB configC" Each configuration file you
449 variable to be equal to the number of cores on the build system. For 631 use must reside in the :term:`Build Directory`
450 example, a system with a dual core processor that also uses 632 ``conf/multiconfig`` directory (e.g.
451 hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default 633 build_directory\ ``/conf/multiconfig/configA.conf``).
452 to "4". 634
453 635 For information on how to use ``BBMULTICONFIG`` in an environment
454 For single socket systems (i.e. one CPU), you should not have to 636 that supports building targets with multiple configurations, see the
455 override this variable to gain optimal parallelism during builds. 637 "`Building Images for Multiple Targets Using Multiple
456 However, if you have very large systems that employ multiple physical 638 Configurations <&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations>`__"
457 CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable 639 section in the Yocto Project Development Tasks Manual.
458 is not set higher than "20". 640
459 641 BBPATH
460 For more information on speeding up builds, see the "`Speeding Up a 642 Used by BitBake to locate ``.bbclass`` and configuration files. This
461 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the 643 variable is analogous to the ``PATH`` variable.
462 Yocto Project Development Tasks Manual. 644
463 645 .. note::
464BB_SERVER_TIMEOUT 646
465 Specifies the time (in seconds) after which to unload the BitBake 647 If you run BitBake from a directory outside of the
466 server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how 648 Build Directory
467 long the BitBake server stays resident between invocations. 649 , you must be sure to set
468 650 BBPATH
469 For example, the following statement in your ``local.conf`` file 651 to point to the Build Directory. Set the variable as you would any
470 instructs the server to be unloaded after 20 seconds of inactivity: 652 environment variable and then run BitBake:
471 BB_SERVER_TIMEOUT = "20" If you want the server to never be unloaded, 653 ::
472 set ``BB_SERVER_TIMEOUT`` to "-1". 654
473 655 $ BBPATH = "build_directory"
474BBCLASSEXTEND 656 $ export BBPATH
475 Allows you to extend a recipe so that it builds variants of the 657 $ bitbake target
476 software. Common variants for recipes exist such as "natives" like 658
477 ``quilt-native``, which is a copy of Quilt built to run on the build 659
478 system; "crosses" such as ``gcc-cross``, which is a compiler built to 660 BBSERVER
479 run on the build machine but produces binaries that run on the target 661 If defined in the BitBake environment, ``BBSERVER`` points to the
480 ```MACHINE`` <#var-MACHINE>`__; "nativesdk", which targets the SDK 662 BitBake remote server.
481 machine instead of ``MACHINE``; and "mulitlibs" in the form 663
482 "``multilib:``\ multilib_name". 664 Use the following format to export the variable to the BitBake
483 665 environment: export BBSERVER=localhost:$port
484 To build a different variant of the recipe with a minimal amount of 666
485 code, it usually is as simple as adding the following to your recipe: 667 By default, ``BBSERVER`` also appears in
486 BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ 668 :term:`bitbake:BB_HASHBASE_WHITELIST`.
487 "multilib:multilib_name" 669 Consequently, ``BBSERVER`` is excluded from checksum and dependency
488 670 data.
489 .. note:: 671
490 672 BINCONFIG
491 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe 673 When inheriting the
492 variants by rewriting variable values and applying overrides such 674 :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class,
493 as ``_class-native``. For example, to generate a native version of 675 this variable specifies binary configuration scripts to disable in
494 a recipe, a ```DEPENDS`` <#var-DEPENDS>`__ on "foo" is rewritten 676 favor of using ``pkg-config`` to query the information. The
495 to a ``DEPENDS`` on "foo-native". 677 ``binconfig-disabled`` class will modify the specified scripts to
496 678 return an error so that calls to them can be easily found and
497 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. 679 replaced.
498 Parsing once adds some limitations. For example, it is not 680
499 possible to include a different file depending on the variant, 681 To add multiple scripts, separate them by spaces. Here is an example
500 since ``include`` statements are processed when the recipe is 682 from the ``libpng`` recipe: BINCONFIG = "${bindir}/libpng-config
501 parsed. 683 ${bindir}/libpng16-config"
502 684
503BBFILE_COLLECTIONS 685 BINCONFIG_GLOB
504 Lists the names of configured layers. These names are used to find 686 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
505 the other ``BBFILE_*`` variables. Typically, each layer will append 687 this variable specifies a wildcard for configuration scripts that
506 its name to this variable in its ``conf/layer.conf`` file. 688 need editing. The scripts are edited to correct any paths that have
507 689 been set up during compilation so that they are correct for use when
508BBFILE_PATTERN 690 installed into the sysroot and called by the build processes of other
509 Variable that expands to match files from 691 recipes.
510 ```BBFILES`` <#var-BBFILES>`__ in a particular layer. This variable 692
511 is used in the ``conf/layer.conf`` file and must be suffixed with the 693 .. note::
512 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). 694
513 695 The
514BBFILE_PRIORITY 696 BINCONFIG_GLOB
515 Assigns the priority for recipe files in each layer. 697 variable uses
516 698 shell globbing
517 This variable is useful in situations where the same recipe appears 699 , which is recognition and expansion of wildcards during pattern
518 in more than one layer. Setting this variable allows you to 700 matching. Shell globbing is very similar to
519 prioritize a layer against other layers that contain the same recipe 701 fnmatch
520 - effectively letting you control the precedence for the multiple 702 and
521 layers. The precedence established through this variable stands 703 glob
522 regardless of a recipe's version (```PV`` <#var-PV>`__ variable). For 704 .
523 example, a layer that has a recipe with a higher ``PV`` value but for 705
524 which the ``BBFILE_PRIORITY`` is set to have a lower precedence still 706 For more information on how this variable works, see
525 has a lower precedence. 707 ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`.
526 708 You can also find general
527 A larger value for the ``BBFILE_PRIORITY`` variable results in a 709 information on the class in the
528 higher precedence. For example, the value 6 has a higher precedence 710 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
529 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable 711
530 is set based on layer dependencies (see the ``LAYERDEPENDS`` variable 712 BP
531 for more information. The default priority, if unspecified for a 713 The base recipe name and version but without any special recipe name
532 layer with no dependencies, is the lowest defined priority + 1 (or 1 714 suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is
533 if no priorities are defined). 715 comprised of the following: ${BPN}-${PV}
534 716
535 .. tip:: 717 BPN
536 718 This variable is a version of the :term:`PN` variable with
537 You can use the command 719 common prefixes and suffixes removed, such as ``nativesdk-``,
538 bitbake-layers show-layers 720 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``.
539 to list all configured layers along with their priorities. 721 The exact lists of prefixes and suffixes removed are specified by the
540 722 :term:`MLPREFIX` and
541BBFILES 723 :term:`SPECIAL_PKGSUFFIX` variables,
542 A space-separated list of recipe files BitBake uses to build 724 respectively.
543 software. 725
544 726 BUGTRACKER
545 When specifying recipe files, you can pattern match using Python's 727 Specifies a URL for an upstream bug tracking website for a recipe.
546 ```glob`` <https://docs.python.org/3/library/glob.html>`__ syntax. 728 The OpenEmbedded build system does not use this variable. Rather, the
547 For details on the syntax, see the documentation by following the 729 variable is a useful pointer in case a bug in the software being
548 previous link. 730 built needs to be manually reported.
549 731
550BBFILES_DYNAMIC 732 BUILD_ARCH
551 Activates content when identified layers are present. You identify 733 Specifies the architecture of the build host (e.g. ``i686``). The
552 the layers by the collections that the layers define. 734 OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the
553 735 machine name reported by the ``uname`` command.
554 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files 736
555 whose corresponding ``.bb`` file is in a layer that attempts to 737 BUILD_AS_ARCH
556 modify other layers through ``.bbappend`` but does not want to 738 Specifies the architecture-specific assembler flags for the build
557 introduce a hard dependency on those other layers. 739 host. By default, the value of ``BUILD_AS_ARCH`` is empty.
558 740
559 Use the following form for ``BBFILES_DYNAMIC``: 741 BUILD_CC_ARCH
560 collection_name:filename_pattern The following example identifies two 742 Specifies the architecture-specific C compiler flags for the build
561 collection names and two filename patterns: BBFILES_DYNAMIC += " \\ 743 host. By default, the value of ``BUILD_CC_ARCH`` is empty.
562 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \\ 744
563 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \\ " 745 BUILD_CCLD
564 This next example shows an error message that occurs because invalid 746 Specifies the linker command to be used for the build host when the C
565 entries are found, which cause parsing to abort: ERROR: 747 compiler is being used as the linker. By default, ``BUILD_CCLD``
566 BBFILES_DYNAMIC entries must be of the form <collection 748 points to GCC and passes as arguments the value of
567 name>:<filename pattern>, not: 749 :term:`BUILD_CC_ARCH`, assuming
568 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 750 ``BUILD_CC_ARCH`` is set.
569 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 751
570 752 BUILD_CFLAGS
571BBINCLUDELOGS 753 Specifies the flags to pass to the C compiler when building for the
572 Variable that controls how BitBake displays logs on build failure. 754 build host. When building in the ``-native`` context,
573 755 :term:`CFLAGS` is set to the value of this variable by
574BBINCLUDELOGS_LINES 756 default.
575 If ```BBINCLUDELOGS`` <#var-BBINCLUDELOGS>`__ is set, specifies the 757
576 maximum number of lines from the task log file to print when 758 BUILD_CPPFLAGS
577 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, 759 Specifies the flags to pass to the C preprocessor (i.e. to both the C
578 the entire log is printed. 760 and the C++ compilers) when building for the build host. When
579 761 building in the ``-native`` context, :term:`CPPFLAGS`
580BBLAYERS 762 is set to the value of this variable by default.
581 Lists the layers to enable during the build. This variable is defined 763
582 in the ``bblayers.conf`` configuration file in the `Build 764 BUILD_CXXFLAGS
583 Directory <#build-directory>`__. Here is an example: BBLAYERS = " \\ 765 Specifies the flags to pass to the C++ compiler when building for the
584 /home/scottrif/poky/meta \\ /home/scottrif/poky/meta-poky \\ 766 build host. When building in the ``-native`` context,
585 /home/scottrif/poky/meta-yocto-bsp \\ 767 :term:`CXXFLAGS` is set to the value of this variable
586 /home/scottrif/poky/meta-mykernel \\ " 768 by default.
587 769
588 This example enables four layers, one of which is a custom, 770 BUILD_FC
589 user-defined layer named ``meta-mykernel``. 771 Specifies the Fortran compiler command for the build host. By
590 772 default, ``BUILD_FC`` points to Gfortran and passes as arguments the
591BBMASK 773 value of :term:`BUILD_CC_ARCH`, assuming
592 Prevents BitBake from processing recipes and recipe append files. 774 ``BUILD_CC_ARCH`` is set.
593 775
594 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and 776 BUILD_LD
595 ``.bbappend`` files. BitBake ignores any recipe or recipe append 777 Specifies the linker command for the build host. By default,
596 files that match any of the expressions. It is as if BitBake does not 778 ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments
597 see them at all. Consequently, matching files are not parsed or 779 the value of :term:`BUILD_LD_ARCH`, assuming
598 otherwise used by BitBake. 780 ``BUILD_LD_ARCH`` is set.
599 781
600 The values you provide are passed to Python's regular expression 782 BUILD_LD_ARCH
601 compiler. Consequently, the syntax follows Python's Regular 783 Specifies architecture-specific linker flags for the build host. By
602 Expression (re) syntax. The expressions are compared against the full 784 default, the value of ``BUILD_LD_ARCH`` is empty.
603 paths to the files. For complete syntax information, see Python's 785
604 documentation at ` <http://docs.python.org/3/library/re.html#re>`__. 786 BUILD_LDFLAGS
605 787 Specifies the flags to pass to the linker when building for the build
606 The following example uses a complete regular expression to tell 788 host. When building in the ``-native`` context,
607 BitBake to ignore all recipe and recipe append files in the 789 :term:`LDFLAGS` is set to the value of this variable
608 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/" 790 by default.
609 If you want to mask out multiple directories or recipes, you can 791
610 specify multiple regular expression fragments. This next example 792 BUILD_OPTIMIZATION
611 masks out multiple directories and individual recipes: BBMASK += 793 Specifies the optimization flags passed to the C compiler when
612 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK += 794 building for the build host or the SDK. The flags are passed through
613 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK 795 the :term:`BUILD_CFLAGS` and
614 += "opencv.*\.bbappend" BBMASK += "lzma" 796 :term:`BUILDSDK_CFLAGS` default values.
615 797
616 .. note:: 798 The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2
617 799 -pipe".
618 When specifying a directory name, use the trailing slash character 800
619 to ensure you match just that directory name. 801 BUILD_OS
620 802 Specifies the operating system in use on the build host (e.g.
621BBMULTICONFIG 803 "linux"). The OpenEmbedded build system sets the value of
622 Specifies each additional separate configuration when you are 804 ``BUILD_OS`` from the OS reported by the ``uname`` command - the
623 building targets with multiple configurations. Use this variable in 805 first word, converted to lower-case characters.
624 your ``conf/local.conf`` configuration file. Specify a 806
625 multiconfigname for each configuration file you are using. For 807 BUILD_PREFIX
626 example, the following line specifies three configuration files: 808 The toolchain binary prefix used for native recipes. The OpenEmbedded
627 BBMULTICONFIG = "configA configB configC" Each configuration file you 809 build system uses the ``BUILD_PREFIX`` value to set the
628 use must reside in the `Build Directory <#build-directory>`__ 810 :term:`TARGET_PREFIX` when building for
629 ``conf/multiconfig`` directory (e.g. 811 ``native`` recipes.
630 build_directory\ ``/conf/multiconfig/configA.conf``). 812
631 813 BUILD_STRIP
632 For information on how to use ``BBMULTICONFIG`` in an environment 814 Specifies the command to be used to strip debugging symbols from
633 that supports building targets with multiple configurations, see the 815 binaries produced for the build host. By default, ``BUILD_STRIP``
634 "`Building Images for Multiple Targets Using Multiple 816 points to
635 Configurations <&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations>`__" 817 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
636 section in the Yocto Project Development Tasks Manual. 818
637 819 BUILD_SYS
638BBPATH 820 Specifies the system, including the architecture and the operating
639 Used by BitBake to locate ``.bbclass`` and configuration files. This 821 system, to use when building for the build host (i.e. when building
640 variable is analogous to the ``PATH`` variable. 822 ``native`` recipes).
641 823
642 .. note:: 824 The OpenEmbedded build system automatically sets this variable based
643 825 on :term:`BUILD_ARCH`,
644 If you run BitBake from a directory outside of the 826 :term:`BUILD_VENDOR`, and
645 Build Directory 827 :term:`BUILD_OS`. You do not need to set the
646 , you must be sure to set 828 ``BUILD_SYS`` variable yourself.
647 BBPATH 829
648 to point to the Build Directory. Set the variable as you would any 830 BUILD_VENDOR
649 environment variable and then run BitBake: 831 Specifies the vendor name to use when building for the build host.
650 :: 832 The default value is an empty string ("").
651 833
652 $ BBPATH = "build_directory" 834 BUILDDIR
653 $ export BBPATH 835 Points to the location of the :term:`Build Directory`.
654 $ bitbake target 836 You can define this directory indirectly through the
655 837 ````` <#structure-core-script>`__ script by passing in a Build
656 838 Directory path when you run the script. If you run the script and do
657BBSERVER 839 not provide a Build Directory path, the ``BUILDDIR`` defaults to
658 If defined in the BitBake environment, ``BBSERVER`` points to the 840 ``build`` in the current directory.
659 BitBake remote server. 841
660 842 BUILDHISTORY_COMMIT
661 Use the following format to export the variable to the BitBake 843 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
662 environment: export BBSERVER=localhost:$port 844 class, this variable specifies whether or not to commit the build
663 845 history output in a local Git repository. If set to "1", this local
664 By default, ``BBSERVER`` also appears in 846 repository will be maintained automatically by the ``buildhistory``
665 ```BB_HASHBASE_WHITELIST`` <&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST>`__. 847 class and a commit will be created on every build for changes to each
666 Consequently, ``BBSERVER`` is excluded from checksum and dependency 848 top-level subdirectory of the build history output (images, packages,
667 data. 849 and sdk). If you want to track changes to build history over time,
668 850 you should set this value to "1".
669BINCONFIG 851
670 When inheriting the 852 By default, the ``buildhistory`` class does not commit the build
671 ```binconfig-disabled`` <#ref-classes-binconfig-disabled>`__ class, 853 history output in a local Git repository: BUILDHISTORY_COMMIT ?= "0"
672 this variable specifies binary configuration scripts to disable in 854
673 favor of using ``pkg-config`` to query the information. The 855 BUILDHISTORY_COMMIT_AUTHOR
674 ``binconfig-disabled`` class will modify the specified scripts to 856 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
675 return an error so that calls to them can be easily found and 857 class, this variable specifies the author to use for each Git commit.
676 replaced. 858 In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the
677 859 :term:`BUILDHISTORY_COMMIT` variable must
678 To add multiple scripts, separate them by spaces. Here is an example 860 be set to "1".
679 from the ``libpng`` recipe: BINCONFIG = "${bindir}/libpng-config 861
680 ${bindir}/libpng16-config" 862 Git requires that the value you provide for the
681 863 ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name
682BINCONFIG_GLOB 864 email@host". Providing an email address or host that is not valid
683 When inheriting the ```binconfig`` <#ref-classes-binconfig>`__ class, 865 does not produce an error.
684 this variable specifies a wildcard for configuration scripts that 866
685 need editing. The scripts are edited to correct any paths that have 867 By default, the ``buildhistory`` class sets the variable as follows:
686 been set up during compilation so that they are correct for use when 868 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
687 installed into the sysroot and called by the build processes of other 869
688 recipes. 870 BUILDHISTORY_DIR
689 871 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
690 .. note:: 872 class, this variable specifies the directory in which build history
691 873 information is kept. For more information on how the variable works,
692 The 874 see the ``buildhistory.class``.
693 BINCONFIG_GLOB 875
694 variable uses 876 By default, the ``buildhistory`` class sets the directory as follows:
695 shell globbing 877 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
696 , which is recognition and expansion of wildcards during pattern 878
697 matching. Shell globbing is very similar to 879 BUILDHISTORY_FEATURES
698 fnmatch 880 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
699 and 881 class, this variable specifies the build history features to be
700 glob 882 enabled. For more information on how build history works, see the
701 . 883 "`Maintaining Build Output
702 884 Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
703 For more information on how this variable works, see 885 section in the Yocto Project Development Tasks Manual.
704 ``meta/classes/binconfig.bbclass`` in the `Source 886
705 Directory <#source-directory>`__. You can also find general 887 You can specify these features in the form of a space-separated list:
706 information on the class in the 888
707 "```binconfig.bbclass`` <#ref-classes-binconfig>`__" section. 889 - *image:* Analysis of the contents of images, which includes the
708 890 list of installed packages among other things.
709BP 891
710 The base recipe name and version but without any special recipe name 892 - *package:* Analysis of the contents of individual packages.
711 suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is 893
712 comprised of the following: ${BPN}-${PV} 894 - *sdk:* Analysis of the contents of the software development kit
713 895 (SDK).
714BPN 896
715 This variable is a version of the ```PN`` <#var-PN>`__ variable with 897 - *task:* Save output file signatures for `shared
716 common prefixes and suffixes removed, such as ``nativesdk-``, 898 state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ (sstate) tasks.
717 ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. 899 This saves one file per task and lists the SHA-256 checksums for
718 The exact lists of prefixes and suffixes removed are specified by the 900 each file staged (i.e. the output of the task).
719 ```MLPREFIX`` <#var-MLPREFIX>`__ and 901
720 ```SPECIAL_PKGSUFFIX`` <#var-SPECIAL_PKGSUFFIX>`__ variables, 902 By default, the ``buildhistory`` class enables the following
721 respectively. 903 features: BUILDHISTORY_FEATURES ?= "image package sdk"
722 904
723BUGTRACKER 905 BUILDHISTORY_IMAGE_FILES
724 Specifies a URL for an upstream bug tracking website for a recipe. 906 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
725 The OpenEmbedded build system does not use this variable. Rather, the 907 class, this variable specifies a list of paths to files copied from
726 variable is a useful pointer in case a bug in the software being 908 the image contents into the build history directory under an
727 built needs to be manually reported. 909 "image-files" directory in the directory for the image, so that you
728 910 can track the contents of each file. The default is to copy
729BUILD_ARCH 911 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for
730 Specifies the architecture of the build host (e.g. ``i686``). The 912 changes in user and group entries. You can modify the list to include
731 OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the 913 any file. Specifying an invalid path does not produce an error.
732 machine name reported by the ``uname`` command. 914 Consequently, you can include files that might not always be present.
733 915
734BUILD_AS_ARCH 916 By default, the ``buildhistory`` class provides paths to the
735 Specifies the architecture-specific assembler flags for the build 917 following files: BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
736 host. By default, the value of ``BUILD_AS_ARCH`` is empty. 918
737 919 BUILDHISTORY_PUSH_REPO
738BUILD_CC_ARCH 920 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
739 Specifies the architecture-specific C compiler flags for the build 921 class, this variable optionally specifies a remote repository to
740 host. By default, the value of ``BUILD_CC_ARCH`` is empty. 922 which build history pushes Git changes. In order for
741 923 ``BUILDHISTORY_PUSH_REPO`` to work,
742BUILD_CCLD 924 :term:`BUILDHISTORY_COMMIT` must be set to
743 Specifies the linker command to be used for the build host when the C 925 "1".
744 compiler is being used as the linker. By default, ``BUILD_CCLD`` 926
745 points to GCC and passes as arguments the value of 927 The repository should correspond to a remote address that specifies a
746 ```BUILD_CC_ARCH`` <#var-BUILD_CC_ARCH>`__, assuming 928 repository as understood by Git, or alternatively to a remote name
747 ``BUILD_CC_ARCH`` is set. 929 that you have set up manually using ``git remote`` within the local
748 930 repository.
749BUILD_CFLAGS 931
750 Specifies the flags to pass to the C compiler when building for the 932 By default, the ``buildhistory`` class sets the variable as follows:
751 build host. When building in the ``-native`` context, 933 BUILDHISTORY_PUSH_REPO ?= ""
752 ```CFLAGS`` <#var-CFLAGS>`__ is set to the value of this variable by 934
753 default. 935 BUILDSDK_CFLAGS
754 936 Specifies the flags to pass to the C compiler when building for the
755BUILD_CPPFLAGS 937 SDK. When building in the ``nativesdk-`` context,
756 Specifies the flags to pass to the C preprocessor (i.e. to both the C 938 :term:`CFLAGS` is set to the value of this variable by
757 and the C++ compilers) when building for the build host. When 939 default.
758 building in the ``-native`` context, ```CPPFLAGS`` <#var-CPPFLAGS>`__ 940
759 is set to the value of this variable by default. 941 BUILDSDK_CPPFLAGS
760 942 Specifies the flags to pass to the C pre-processor (i.e. to both the
761BUILD_CXXFLAGS 943 C and the C++ compilers) when building for the SDK. When building in
762 Specifies the flags to pass to the C++ compiler when building for the 944 the ``nativesdk-`` context, :term:`CPPFLAGS` is set
763 build host. When building in the ``-native`` context, 945 to the value of this variable by default.
764 ```CXXFLAGS`` <#var-CXXFLAGS>`__ is set to the value of this variable 946
765 by default. 947 BUILDSDK_CXXFLAGS
766 948 Specifies the flags to pass to the C++ compiler when building for the
767BUILD_FC 949 SDK. When building in the ``nativesdk-`` context,
768 Specifies the Fortran compiler command for the build host. By 950 :term:`CXXFLAGS` is set to the value of this variable
769 default, ``BUILD_FC`` points to Gfortran and passes as arguments the 951 by default.
770 value of ```BUILD_CC_ARCH`` <#var-BUILD_CC_ARCH>`__, assuming 952
771 ``BUILD_CC_ARCH`` is set. 953 BUILDSDK_LDFLAGS
772 954 Specifies the flags to pass to the linker when building for the SDK.
773BUILD_LD 955 When building in the ``nativesdk-`` context,
774 Specifies the linker command for the build host. By default, 956 :term:`LDFLAGS` is set to the value of this variable
775 ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments 957 by default.
776 the value of ```BUILD_LD_ARCH`` <#var-BUILD_LD_ARCH>`__, assuming 958
777 ``BUILD_LD_ARCH`` is set. 959 BUILDSTATS_BASE
778 960 Points to the location of the directory that holds build statistics
779BUILD_LD_ARCH 961 when you use and enable the
780 Specifies architecture-specific linker flags for the build host. By 962 :ref:`buildstats <ref-classes-buildstats>` class. The
781 default, the value of ``BUILD_LD_ARCH`` is empty. 963 ``BUILDSTATS_BASE`` directory defaults to
782 964 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
783BUILD_LDFLAGS 965
784 Specifies the flags to pass to the linker when building for the build 966 BUSYBOX_SPLIT_SUID
785 host. When building in the ``-native`` context, 967 For the BusyBox recipe, specifies whether to split the output
786 ```LDFLAGS`` <#var-LDFLAGS>`__ is set to the value of this variable 968 executable file into two parts: one for features that require
787 by default. 969 ``setuid root``, and one for the remaining features (i.e. those that
788 970 do not require ``setuid root``).
789BUILD_OPTIMIZATION 971
790 Specifies the optimization flags passed to the C compiler when 972 The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in
791 building for the build host or the SDK. The flags are passed through 973 splitting the output executable file. Set the variable to "0" to get
792 the ```BUILD_CFLAGS`` <#var-BUILD_CFLAGS>`__ and 974 a single output executable file.
793 ```BUILDSDK_CFLAGS`` <#var-BUILDSDK_CFLAGS>`__ default values. 975
794 976 CACHE
795 The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 977 Specifies the directory BitBake uses to store a cache of the
796 -pipe". 978 :term:`Metadata` so it does not need to be parsed every time
797 979 BitBake is started.
798BUILD_OS 980
799 Specifies the operating system in use on the build host (e.g. 981 CC
800 "linux"). The OpenEmbedded build system sets the value of 982 The minimal command and arguments used to run the C compiler.
801 ``BUILD_OS`` from the OS reported by the ``uname`` command - the 983
802 first word, converted to lower-case characters. 984 CFLAGS
803 985 Specifies the flags to pass to the C compiler. This variable is
804BUILD_PREFIX 986 exported to an environment variable and thus made visible to the
805 The toolchain binary prefix used for native recipes. The OpenEmbedded 987 software being built during the compilation step.
806 build system uses the ``BUILD_PREFIX`` value to set the 988
807 ```TARGET_PREFIX`` <#var-TARGET_PREFIX>`__ when building for 989 Default initialization for ``CFLAGS`` varies depending on what is
808 ``native`` recipes. 990 being built:
809 991
810BUILD_STRIP 992 - :term:`TARGET_CFLAGS` when building for the
811 Specifies the command to be used to strip debugging symbols from 993 target
812 binaries produced for the build host. By default, ``BUILD_STRIP`` 994
813 points to 995 - :term:`BUILD_CFLAGS` when building for the
814 ``${``\ ```BUILD_PREFIX`` <#var-BUILD_PREFIX>`__\ ``}strip``. 996 build host (i.e. ``-native``)
815 997
816BUILD_SYS 998 - :term:`BUILDSDK_CFLAGS` when building for
817 Specifies the system, including the architecture and the operating 999 an SDK (i.e. ``nativesdk-``)
818 system, to use when building for the build host (i.e. when building 1000
819 ``native`` recipes). 1001 CLASSOVERRIDE
820 1002 An internal variable specifying the special class override that
821 The OpenEmbedded build system automatically sets this variable based 1003 should currently apply (e.g. "class-target", "class-native", and so
822 on ```BUILD_ARCH`` <#var-BUILD_ARCH>`__, 1004 forth). The classes that use this variable (e.g.
823 ```BUILD_VENDOR`` <#var-BUILD_VENDOR>`__, and 1005 :ref:`native <ref-classes-native>`,
824 ```BUILD_OS`` <#var-BUILD_OS>`__. You do not need to set the 1006 :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the
825 ``BUILD_SYS`` variable yourself. 1007 variable to appropriate values.
826 1008
827BUILD_VENDOR 1009 .. note::
828 Specifies the vendor name to use when building for the build host. 1010
829 The default value is an empty string (""). 1011 CLASSOVERRIDE
830 1012 gets its default "class-target" value from the
831BUILDDIR 1013 bitbake.conf
832 Points to the location of the `Build Directory <#build-directory>`__. 1014 file.
833 You can define this directory indirectly through the 1015
834 ````` <#structure-core-script>`__ script by passing in a Build 1016 As an example, the following override allows you to install extra
835 Directory path when you run the script. If you run the script and do 1017 files, but only when building for the target:
836 not provide a Build Directory path, the ``BUILDDIR`` defaults to 1018 do_install_append_class-target() { install my-extra-file
837 ``build`` in the current directory. 1019 ${D}${sysconfdir} } Here is an example where ``FOO`` is set to
838 1020 "native" when building for the build host, and to "other" when not
839BUILDHISTORY_COMMIT 1021 building for the build host: FOO_class-native = "native" FOO =
840 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1022 "other" The underlying mechanism behind ``CLASSOVERRIDE`` is simply
841 class, this variable specifies whether or not to commit the build 1023 that it is included in the default value of
842 history output in a local Git repository. If set to "1", this local 1024 :term:`OVERRIDES`.
843 repository will be maintained automatically by the ``buildhistory`` 1025
844 class and a commit will be created on every build for changes to each 1026 CLEANBROKEN
845 top-level subdirectory of the build history output (images, packages, 1027 If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the
846 and sdk). If you want to track changes to build history over time, 1028 ``make clean`` command does not work for the software being built.
847 you should set this value to "1". 1029 Consequently, the OpenEmbedded build system will not try to run
848 1030 ``make clean`` during the :ref:`ref-tasks-configure`
849 By default, the ``buildhistory`` class does not commit the build 1031 task, which is the default behavior.
850 history output in a local Git repository: BUILDHISTORY_COMMIT ?= "0" 1032
851 1033 COMBINED_FEATURES
852BUILDHISTORY_COMMIT_AUTHOR 1034 Provides a list of hardware features that are enabled in both
853 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1035 :term:`MACHINE_FEATURES` and
854 class, this variable specifies the author to use for each Git commit. 1036 :term:`DISTRO_FEATURES`. This select list of
855 In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the 1037 features contains features that make sense to be controlled both at
856 ```BUILDHISTORY_COMMIT`` <#var-BUILDHISTORY_COMMIT>`__ variable must 1038 the machine and distribution configuration level. For example, the
857 be set to "1". 1039 "bluetooth" feature requires hardware support but should also be
858 1040 optional at the distribution level, in case the hardware supports
859 Git requires that the value you provide for the 1041 Bluetooth but you do not ever intend to use it.
860 ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name 1042
861 email@host". Providing an email address or host that is not valid 1043 COMMON_LICENSE_DIR
862 does not produce an error. 1044 Points to ``meta/files/common-licenses`` in the
863 1045 :term:`Source Directory`, which is where generic license
864 By default, the ``buildhistory`` class sets the variable as follows: 1046 files reside.
865 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 1047
866 1048 COMPATIBLE_HOST
867BUILDHISTORY_DIR 1049 A regular expression that resolves to one or more hosts (when the
868 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1050 recipe is native) or one or more targets (when the recipe is
869 class, this variable specifies the directory in which build history 1051 non-native) with which a recipe is compatible. The regular expression
870 information is kept. For more information on how the variable works, 1052 is matched against :term:`HOST_SYS`. You can use the
871 see the ``buildhistory.class``. 1053 variable to stop recipes from being built for classes of systems with
872 1054 which the recipes are not compatible. Stopping these builds is
873 By default, the ``buildhistory`` class sets the directory as follows: 1055 particularly useful with kernels. The variable also helps to increase
874 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 1056 parsing speed since the build system skips parsing recipes not
875 1057 compatible with the current system.
876BUILDHISTORY_FEATURES 1058
877 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1059 COMPATIBLE_MACHINE
878 class, this variable specifies the build history features to be 1060 A regular expression that resolves to one or more target machines
879 enabled. For more information on how build history works, see the 1061 with which a recipe is compatible. The regular expression is matched
880 "`Maintaining Build Output 1062 against :term:`MACHINEOVERRIDES`. You can use
881 Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__" 1063 the variable to stop recipes from being built for machines with which
882 section in the Yocto Project Development Tasks Manual. 1064 the recipes are not compatible. Stopping these builds is particularly
883 1065 useful with kernels. The variable also helps to increase parsing
884 You can specify these features in the form of a space-separated list: 1066 speed since the build system skips parsing recipes not compatible
885 1067 with the current machine.
886 - *image:* Analysis of the contents of images, which includes the 1068
887 list of installed packages among other things. 1069 COMPLEMENTARY_GLOB
888 1070 Defines wildcards to match when installing a list of complementary
889 - *package:* Analysis of the contents of individual packages. 1071 packages for all the packages explicitly (or implicitly) installed in
890 1072 an image.
891 - *sdk:* Analysis of the contents of the software development kit 1073
892 (SDK). 1074 .. note::
893 1075
894 - *task:* Save output file signatures for `shared 1076 The
895 state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ (sstate) tasks. 1077 COMPLEMENTARY_GLOB
896 This saves one file per task and lists the SHA-256 checksums for 1078 variable uses Unix filename pattern matching (
897 each file staged (i.e. the output of the task). 1079 fnmatch
898 1080 ), which is similar to the Unix style pathname pattern expansion (
899 By default, the ``buildhistory`` class enables the following 1081 glob
900 features: BUILDHISTORY_FEATURES ?= "image package sdk" 1082 ).
901 1083
902BUILDHISTORY_IMAGE_FILES 1084 The resulting list of complementary packages is associated with an
903 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1085 item that can be added to
904 class, this variable specifies a list of paths to files copied from 1086 :term:`IMAGE_FEATURES`. An example usage of
905 the image contents into the build history directory under an 1087 this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES``
906 "image-files" directory in the directory for the image, so that you 1088 will install -dev packages (containing headers and other development
907 can track the contents of each file. The default is to copy 1089 files) for every package in the image.
908 ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for 1090
909 changes in user and group entries. You can modify the list to include 1091 To add a new feature item pointing to a wildcard, use a variable flag
910 any file. Specifying an invalid path does not produce an error. 1092 to specify the feature item name and use the value to specify the
911 Consequently, you can include files that might not always be present. 1093 wildcard. Here is an example: COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
912 1094
913 By default, the ``buildhistory`` class provides paths to the 1095 COMPONENTS_DIR
914 following files: BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1096 Stores sysroot components for each recipe. The OpenEmbedded build
915 1097 system uses ``COMPONENTS_DIR`` when constructing recipe-specific
916BUILDHISTORY_PUSH_REPO 1098 sysroots for other recipes.
917 When inheriting the ```buildhistory`` <#ref-classes-buildhistory>`__ 1099
918 class, this variable optionally specifies a remote repository to 1100 The default is
919 which build history pushes Git changes. In order for 1101 "``${``\ :term:`STAGING_DIR`\ ``}-components``."
920 ``BUILDHISTORY_PUSH_REPO`` to work, 1102 (i.e.
921 ```BUILDHISTORY_COMMIT`` <#var-BUILDHISTORY_COMMIT>`__ must be set to 1103 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
922 "1". 1104
923 1105 CONF_VERSION
924 The repository should correspond to a remote address that specifies a 1106 Tracks the version of the local configuration file (i.e.
925 repository as understood by Git, or alternatively to a remote name 1107 ``local.conf``). The value for ``CONF_VERSION`` increments each time
926 that you have set up manually using ``git remote`` within the local 1108 ``build/conf/`` compatibility changes.
927 repository. 1109
928 1110 CONFFILES
929 By default, the ``buildhistory`` class sets the variable as follows: 1111 Identifies editable or configurable files that are part of a package.
930 BUILDHISTORY_PUSH_REPO ?= "" 1112 If the Package Management System (PMS) is being used to update
931 1113 packages on the target system, it is possible that configuration
932BUILDSDK_CFLAGS 1114 files you have changed after the original installation and that you
933 Specifies the flags to pass to the C compiler when building for the 1115 now want to remain unchanged are overwritten. In other words,
934 SDK. When building in the ``nativesdk-`` context, 1116 editable files might exist in the package that you do not want reset
935 ```CFLAGS`` <#var-CFLAGS>`__ is set to the value of this variable by 1117 as part of the package update process. You can use the ``CONFFILES``
936 default. 1118 variable to list the files in the package that you wish to prevent
937 1119 the PMS from overwriting during this update process.
938BUILDSDK_CPPFLAGS 1120
939 Specifies the flags to pass to the C pre-processor (i.e. to both the 1121 To use the ``CONFFILES`` variable, provide a package name override
940 C and the C++ compilers) when building for the SDK. When building in 1122 that identifies the resulting package. Then, provide a
941 the ``nativesdk-`` context, ```CPPFLAGS`` <#var-CPPFLAGS>`__ is set 1123 space-separated list of files. Here is an example: CONFFILES_${PN} +=
942 to the value of this variable by default. 1124 "${sysconfdir}/file1 \\ ${sysconfdir}/file2 ${sysconfdir}/file3"
943 1125
944BUILDSDK_CXXFLAGS 1126 A relationship exists between the ``CONFFILES`` and ``FILES``
945 Specifies the flags to pass to the C++ compiler when building for the 1127 variables. The files listed within ``CONFFILES`` must be a subset of
946 SDK. When building in the ``nativesdk-`` context, 1128 the files listed within ``FILES``. Because the configuration files
947 ```CXXFLAGS`` <#var-CXXFLAGS>`__ is set to the value of this variable 1129 you provide with ``CONFFILES`` are simply being identified so that
948 by default. 1130 the PMS will not overwrite them, it makes sense that the files must
949 1131 already be included as part of the package through the ``FILES``
950BUILDSDK_LDFLAGS
951 Specifies the flags to pass to the linker when building for the SDK.
952 When building in the ``nativesdk-`` context,
953 ```LDFLAGS`` <#var-LDFLAGS>`__ is set to the value of this variable
954 by default.
955
956BUILDSTATS_BASE
957 Points to the location of the directory that holds build statistics
958 when you use and enable the
959 ```buildstats`` <#ref-classes-buildstats>`__ class. The
960 ``BUILDSTATS_BASE`` directory defaults to
961 ``${``\ ```TMPDIR`` <#var-TMPDIR>`__\ ``}/buildstats/``.
962
963BUSYBOX_SPLIT_SUID
964 For the BusyBox recipe, specifies whether to split the output
965 executable file into two parts: one for features that require
966 ``setuid root``, and one for the remaining features (i.e. those that
967 do not require ``setuid root``).
968
969 The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in
970 splitting the output executable file. Set the variable to "0" to get
971 a single output executable file.
972
973CACHE
974 Specifies the directory BitBake uses to store a cache of the
975 `Metadata <#metadata>`__ so it does not need to be parsed every time
976 BitBake is started.
977
978CC
979 The minimal command and arguments used to run the C compiler.
980
981CFLAGS
982 Specifies the flags to pass to the C compiler. This variable is
983 exported to an environment variable and thus made visible to the
984 software being built during the compilation step.
985
986 Default initialization for ``CFLAGS`` varies depending on what is
987 being built:
988
989 - ```TARGET_CFLAGS`` <#var-TARGET_CFLAGS>`__ when building for the
990 target
991
992 - ```BUILD_CFLAGS`` <#var-BUILD_CFLAGS>`__ when building for the
993 build host (i.e. ``-native``)
994
995 - ```BUILDSDK_CFLAGS`` <#var-BUILDSDK_CFLAGS>`__ when building for
996 an SDK (i.e. ``nativesdk-``)
997
998CLASSOVERRIDE
999 An internal variable specifying the special class override that
1000 should currently apply (e.g. "class-target", "class-native", and so
1001 forth). The classes that use this variable (e.g.
1002 ```native`` <#ref-classes-native>`__,
1003 ```nativesdk`` <#ref-classes-nativesdk>`__, and so forth) set the
1004 variable to appropriate values.
1005
1006 .. note::
1007
1008 CLASSOVERRIDE
1009 gets its default "class-target" value from the
1010 bitbake.conf
1011 file.
1012
1013 As an example, the following override allows you to install extra
1014 files, but only when building for the target:
1015 do_install_append_class-target() { install my-extra-file
1016 ${D}${sysconfdir} } Here is an example where ``FOO`` is set to
1017 "native" when building for the build host, and to "other" when not
1018 building for the build host: FOO_class-native = "native" FOO =
1019 "other" The underlying mechanism behind ``CLASSOVERRIDE`` is simply
1020 that it is included in the default value of
1021 ```OVERRIDES`` <#var-OVERRIDES>`__.
1022
1023CLEANBROKEN
1024 If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the
1025 ``make clean`` command does not work for the software being built.
1026 Consequently, the OpenEmbedded build system will not try to run
1027 ``make clean`` during the ```do_configure`` <#ref-tasks-configure>`__
1028 task, which is the default behavior.
1029
1030COMBINED_FEATURES
1031 Provides a list of hardware features that are enabled in both
1032 ```MACHINE_FEATURES`` <#var-MACHINE_FEATURES>`__ and
1033 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__. This select list of
1034 features contains features that make sense to be controlled both at
1035 the machine and distribution configuration level. For example, the
1036 "bluetooth" feature requires hardware support but should also be
1037 optional at the distribution level, in case the hardware supports
1038 Bluetooth but you do not ever intend to use it.
1039
1040COMMON_LICENSE_DIR
1041 Points to ``meta/files/common-licenses`` in the `Source
1042 Directory <#source-directory>`__, which is where generic license
1043 files reside.
1044
1045COMPATIBLE_HOST
1046 A regular expression that resolves to one or more hosts (when the
1047 recipe is native) or one or more targets (when the recipe is
1048 non-native) with which a recipe is compatible. The regular expression
1049 is matched against ```HOST_SYS`` <#var-HOST_SYS>`__. You can use the
1050 variable to stop recipes from being built for classes of systems with
1051 which the recipes are not compatible. Stopping these builds is
1052 particularly useful with kernels. The variable also helps to increase
1053 parsing speed since the build system skips parsing recipes not
1054 compatible with the current system.
1055
1056COMPATIBLE_MACHINE
1057 A regular expression that resolves to one or more target machines
1058 with which a recipe is compatible. The regular expression is matched
1059 against ```MACHINEOVERRIDES`` <#var-MACHINEOVERRIDES>`__. You can use
1060 the variable to stop recipes from being built for machines with which
1061 the recipes are not compatible. Stopping these builds is particularly
1062 useful with kernels. The variable also helps to increase parsing
1063 speed since the build system skips parsing recipes not compatible
1064 with the current machine.
1065
1066COMPLEMENTARY_GLOB
1067 Defines wildcards to match when installing a list of complementary
1068 packages for all the packages explicitly (or implicitly) installed in
1069 an image.
1070
1071 .. note::
1072
1073 The
1074 COMPLEMENTARY_GLOB
1075 variable uses Unix filename pattern matching (
1076 fnmatch
1077 ), which is similar to the Unix style pathname pattern expansion (
1078 glob
1079 ).
1080
1081 The resulting list of complementary packages is associated with an
1082 item that can be added to
1083 ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__. An example usage of
1084 this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES``
1085 will install -dev packages (containing headers and other development
1086 files) for every package in the image.
1087
1088 To add a new feature item pointing to a wildcard, use a variable flag
1089 to specify the feature item name and use the value to specify the
1090 wildcard. Here is an example: COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1091
1092COMPONENTS_DIR
1093 Stores sysroot components for each recipe. The OpenEmbedded build
1094 system uses ``COMPONENTS_DIR`` when constructing recipe-specific
1095 sysroots for other recipes.
1096
1097 The default is
1098 "``${``\ ```STAGING_DIR`` <#var-STAGING_DIR>`__\ ``}-components``."
1099 (i.e.
1100 "``${``\ ```TMPDIR`` <#var-TMPDIR>`__\ ``}/sysroots-components``").
1101
1102CONF_VERSION
1103 Tracks the version of the local configuration file (i.e.
1104 ``local.conf``). The value for ``CONF_VERSION`` increments each time
1105 ``build/conf/`` compatibility changes.
1106
1107CONFFILES
1108 Identifies editable or configurable files that are part of a package.
1109 If the Package Management System (PMS) is being used to update
1110 packages on the target system, it is possible that configuration
1111 files you have changed after the original installation and that you
1112 now want to remain unchanged are overwritten. In other words,
1113 editable files might exist in the package that you do not want reset
1114 as part of the package update process. You can use the ``CONFFILES``
1115 variable to list the files in the package that you wish to prevent
1116 the PMS from overwriting during this update process.
1117
1118 To use the ``CONFFILES`` variable, provide a package name override
1119 that identifies the resulting package. Then, provide a
1120 space-separated list of files. Here is an example: CONFFILES_${PN} +=
1121 "${sysconfdir}/file1 \\ ${sysconfdir}/file2 ${sysconfdir}/file3"
1122
1123 A relationship exists between the ``CONFFILES`` and ``FILES``
1124 variables. The files listed within ``CONFFILES`` must be a subset of
1125 the files listed within ``FILES``. Because the configuration files
1126 you provide with ``CONFFILES`` are simply being identified so that
1127 the PMS will not overwrite them, it makes sense that the files must
1128 already be included as part of the package through the ``FILES``
1129 variable.
1130
1131 .. note::
1132
1133 When specifying paths as part of the
1134 CONFFILES
1135 variable, it is good practice to use appropriate path variables.
1136 For example,
1137 ${sysconfdir}
1138 rather than
1139 /etc
1140 or
1141 ${bindir}
1142 rather than
1143 /usr/bin
1144 . You can find a list of these variables at the top of the
1145 meta/conf/bitbake.conf
1146 file in the
1147 Source Directory
1148 .
1149
1150CONFIG_INITRAMFS_SOURCE
1151 Identifies the initial RAM filesystem (initramfs) source files. The
1152 OpenEmbedded build system receives and uses this kernel Kconfig
1153 variable as an environment variable. By default, the variable is set
1154 to null ("").
1155
1156 The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive
1157 with a ``.cpio`` suffix or a space-separated list of directories and
1158 files for building the initramfs image. A cpio archive should contain
1159 a filesystem archive to be used as an initramfs image. Directories
1160 should contain a filesystem layout to be included in the initramfs
1161 image. Files should contain entries according to the format described
1162 by the ``usr/gen_init_cpio`` program in the kernel tree.
1163
1164 If you specify multiple directories and files, the initramfs image
1165 will be the aggregate of all of them.
1166
1167 For information on creating an initramfs, see the "`Building an
1168 Initial RAM Filesystem (initramfs)
1169 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
1170 in the Yocto Project Development Tasks Manual.
1171
1172CONFIG_SITE
1173 A list of files that contains ``autoconf`` test results relevant to
1174 the current build. This variable is used by the Autotools utilities
1175 when running ``configure``.
1176
1177CONFIGURE_FLAGS
1178 The minimal arguments for GNU configure.
1179
1180CONFLICT_DISTRO_FEATURES
1181 When inheriting the
1182 ```distro_features_check`` <#ref-classes-distro_features_check>`__
1183 class, this variable identifies distribution features that would be
1184 in conflict should the recipe be built. In other words, if the
1185 ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also
1186 appears in ``DISTRO_FEATURES`` within the current configuration, an
1187 error occurs and the build stops.
1188
1189COPYLEFT_LICENSE_EXCLUDE
1190 A space-separated list of licenses to exclude from the source
1191 archived by the ```archiver`` <#ref-classes-archiver>`__ class. In
1192 other words, if a license in a recipe's
1193 ```LICENSE`` <#var-LICENSE>`__ value is in the value of
1194 ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the
1195 class.
1196
1197 .. note::
1198
1199 The
1200 COPYLEFT_LICENSE_EXCLUDE
1201 variable takes precedence over the
1202 COPYLEFT_LICENSE_INCLUDE
1203 variable. 1132 variable.
1204 1133
1205 The default value, which is "CLOSED Proprietary", for 1134 .. note::
1206 ``COPYLEFT_LICENSE_EXCLUDE`` is set by the 1135
1207 ```copyleft_filter`` <#ref-classes-copyleft_filter>`__ class, which 1136 When specifying paths as part of the
1208 is inherited by the ``archiver`` class. 1137 CONFFILES
1209 1138 variable, it is good practice to use appropriate path variables.
1210COPYLEFT_LICENSE_INCLUDE 1139 For example,
1211 A space-separated list of licenses to include in the source archived 1140 ${sysconfdir}
1212 by the ```archiver`` <#ref-classes-archiver>`__ class. In other 1141 rather than
1213 words, if a license in a recipe's ```LICENSE`` <#var-LICENSE>`__ 1142 /etc
1214 value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its 1143 or
1215 source is archived by the class. 1144 ${bindir}
1216 1145 rather than
1217 The default value is set by the 1146 /usr/bin
1218 ```copyleft_filter`` <#ref-classes-copyleft_filter>`__ class, which 1147 . You can find a list of these variables at the top of the
1219 is inherited by the ``archiver`` class. The default value includes 1148 meta/conf/bitbake.conf
1220 "GPL*", "LGPL*", and "AGPL*". 1149 file in the
1221 1150 Source Directory
1222COPYLEFT_PN_EXCLUDE 1151 .
1223 A list of recipes to exclude in the source archived by the 1152
1224 ```archiver`` <#ref-classes-archiver>`__ class. The 1153 CONFIG_INITRAMFS_SOURCE
1225 ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and 1154 Identifies the initial RAM filesystem (initramfs) source files. The
1226 exclusion caused through the 1155 OpenEmbedded build system receives and uses this kernel Kconfig
1227 ```COPYLEFT_LICENSE_INCLUDE`` <#var-COPYLEFT_LICENSE_INCLUDE>`__ and 1156 variable as an environment variable. By default, the variable is set
1228 ```COPYLEFT_LICENSE_EXCLUDE`` <#var-COPYLEFT_LICENSE_EXCLUDE>`__ 1157 to null ("").
1229 variables, respectively. 1158
1230 1159 The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive
1231 The default value, which is "" indicating to not explicitly exclude 1160 with a ``.cpio`` suffix or a space-separated list of directories and
1232 any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the 1161 files for building the initramfs image. A cpio archive should contain
1233 ```copyleft_filter`` <#ref-classes-copyleft_filter>`__ class, which 1162 a filesystem archive to be used as an initramfs image. Directories
1234 is inherited by the ``archiver`` class. 1163 should contain a filesystem layout to be included in the initramfs
1235 1164 image. Files should contain entries according to the format described
1236COPYLEFT_PN_INCLUDE 1165 by the ``usr/gen_init_cpio`` program in the kernel tree.
1237 A list of recipes to include in the source archived by the 1166
1238 ```archiver`` <#ref-classes-archiver>`__ class. The 1167 If you specify multiple directories and files, the initramfs image
1239 ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and 1168 will be the aggregate of all of them.
1240 exclusion caused through the 1169
1241 ```COPYLEFT_LICENSE_INCLUDE`` <#var-COPYLEFT_LICENSE_INCLUDE>`__ and 1170 For information on creating an initramfs, see the "`Building an
1242 ```COPYLEFT_LICENSE_EXCLUDE`` <#var-COPYLEFT_LICENSE_EXCLUDE>`__ 1171 Initial RAM Filesystem (initramfs)
1243 variables, respectively. 1172 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
1244 1173 in the Yocto Project Development Tasks Manual.
1245 The default value, which is "" indicating to not explicitly include 1174
1246 any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the 1175 CONFIG_SITE
1247 ```copyleft_filter`` <#ref-classes-copyleft_filter>`__ class, which 1176 A list of files that contains ``autoconf`` test results relevant to
1248 is inherited by the ``archiver`` class. 1177 the current build. This variable is used by the Autotools utilities
1249 1178 when running ``configure``.
1250COPYLEFT_RECIPE_TYPES 1179
1251 A space-separated list of recipe types to include in the source 1180 CONFIGURE_FLAGS
1252 archived by the ```archiver`` <#ref-classes-archiver>`__ class. 1181 The minimal arguments for GNU configure.
1253 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, 1182
1254 ``crosssdk``, and ``cross-canadian``. 1183 CONFLICT_DISTRO_FEATURES
1255 1184 When inheriting the
1256 The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` 1185 :ref:`distro_features_check <ref-classes-distro_features_check>`
1257 is set by the ```copyleft_filter`` <#ref-classes-copyleft_filter>`__ 1186 class, this variable identifies distribution features that would be
1258 class, which is inherited by the ``archiver`` class. 1187 in conflict should the recipe be built. In other words, if the
1259 1188 ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also
1260COPY_LIC_DIRS 1189 appears in ``DISTRO_FEATURES`` within the current configuration, an
1261 If set to "1" along with the 1190 error occurs and the build stops.
1262 ```COPY_LIC_MANIFEST`` <#var-COPY_LIC_MANIFEST>`__ variable, the 1191
1263 OpenEmbedded build system copies into the image the license files, 1192 COPYLEFT_LICENSE_EXCLUDE
1264 which are located in ``/usr/share/common-licenses``, for each 1193 A space-separated list of licenses to exclude from the source
1265 package. The license files are placed in directories within the image 1194 archived by the :ref:`archiver <ref-classes-archiver>` class. In
1266 itself during build time. 1195 other words, if a license in a recipe's
1267 1196 :term:`LICENSE` value is in the value of
1268 .. note:: 1197 ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the
1269 1198 class.
1270 The 1199
1271 COPY_LIC_DIRS 1200 .. note::
1272 does not offer a path for adding licenses for newly installed 1201
1273 packages to an image, which might be most suitable for read-only 1202 The
1274 filesystems that cannot be upgraded. See the 1203 COPYLEFT_LICENSE_EXCLUDE
1275 LICENSE_CREATE_PACKAGE 1204 variable takes precedence over the
1276 variable for additional information. You can also reference the " 1205 COPYLEFT_LICENSE_INCLUDE
1277 Providing License Text 1206 variable.
1278 " section in the Yocto Project Development Tasks Manual for 1207
1279 information on providing license text. 1208 The default value, which is "CLOSED Proprietary", for
1280 1209 ``COPYLEFT_LICENSE_EXCLUDE`` is set by the
1281COPY_LIC_MANIFEST 1210 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1282 If set to "1", the OpenEmbedded build system copies the license 1211 is inherited by the ``archiver`` class.
1283 manifest for the image to 1212
1284 ``/usr/share/common-licenses/license.manifest`` within the image 1213 COPYLEFT_LICENSE_INCLUDE
1285 itself during build time. 1214 A space-separated list of licenses to include in the source archived
1286 1215 by the :ref:`archiver <ref-classes-archiver>` class. In other
1287 .. note:: 1216 words, if a license in a recipe's :term:`LICENSE`
1288 1217 value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its
1289 The 1218 source is archived by the class.
1290 COPY_LIC_MANIFEST 1219
1291 does not offer a path for adding licenses for newly installed 1220 The default value is set by the
1292 packages to an image, which might be most suitable for read-only 1221 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1293 filesystems that cannot be upgraded. See the 1222 is inherited by the ``archiver`` class. The default value includes
1294 LICENSE_CREATE_PACKAGE 1223 "GPL*", "LGPL*", and "AGPL*".
1295 variable for additional information. You can also reference the " 1224
1296 Providing License Text 1225 COPYLEFT_PN_EXCLUDE
1297 " section in the Yocto Project Development Tasks Manual for 1226 A list of recipes to exclude in the source archived by the
1298 information on providing license text. 1227 :ref:`archiver <ref-classes-archiver>` class. The
1299 1228 ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and
1300CORE_IMAGE_EXTRA_INSTALL 1229 exclusion caused through the
1301 Specifies the list of packages to be added to the image. You should 1230 :term:`COPYLEFT_LICENSE_INCLUDE` and
1302 only set this variable in the ``local.conf`` configuration file found 1231 :term:`COPYLEFT_LICENSE_EXCLUDE`
1303 in the `Build Directory <#build-directory>`__. 1232 variables, respectively.
1304 1233
1305 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer 1234 The default value, which is "" indicating to not explicitly exclude
1306 supported. 1235 any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the
1307 1236 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1308COREBASE 1237 is inherited by the ``archiver`` class.
1309 Specifies the parent directory of the OpenEmbedded-Core Metadata 1238
1310 layer (i.e. ``meta``). 1239 COPYLEFT_PN_INCLUDE
1311 1240 A list of recipes to include in the source archived by the
1312 It is an important distinction that ``COREBASE`` points to the parent 1241 :ref:`archiver <ref-classes-archiver>` class. The
1313 of this layer and not the layer itself. Consider an example where you 1242 ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and
1314 have cloned the Poky Git repository and retained the ``poky`` name 1243 exclusion caused through the
1315 for your local copy of the repository. In this case, ``COREBASE`` 1244 :term:`COPYLEFT_LICENSE_INCLUDE` and
1316 points to the ``poky`` folder because it is the parent directory of 1245 :term:`COPYLEFT_LICENSE_EXCLUDE`
1317 the ``poky/meta`` layer. 1246 variables, respectively.
1318 1247
1319COREBASE_FILES 1248 The default value, which is "" indicating to not explicitly include
1320 Lists files from the ```COREBASE`` <#var-COREBASE>`__ directory that 1249 any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the
1321 should be copied other than the layers listed in the 1250 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1322 ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for 1251 is inherited by the ``archiver`` class.
1323 the purpose of copying metadata from the OpenEmbedded build system 1252
1324 into the extensible SDK. 1253 COPYLEFT_RECIPE_TYPES
1325 1254 A space-separated list of recipe types to include in the source
1326 Explicitly listing files in ``COREBASE`` is needed because it 1255 archived by the :ref:`archiver <ref-classes-archiver>` class.
1327 typically contains build directories and other files that should not 1256 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``,
1328 normally be copied into the extensible SDK. Consequently, the value 1257 ``crosssdk``, and ``cross-canadian``.
1329 of ``COREBASE_FILES`` is used in order to only copy the files that 1258
1330 are actually needed. 1259 The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES``
1331 1260 is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>`
1332CPP 1261 class, which is inherited by the ``archiver`` class.
1333 The minimal command and arguments used to run the C preprocessor. 1262
1334 1263 COPY_LIC_DIRS
1335CPPFLAGS 1264 If set to "1" along with the
1336 Specifies the flags to pass to the C pre-processor (i.e. to both the 1265 :term:`COPY_LIC_MANIFEST` variable, the
1337 C and the C++ compilers). This variable is exported to an environment 1266 OpenEmbedded build system copies into the image the license files,
1338 variable and thus made visible to the software being built during the 1267 which are located in ``/usr/share/common-licenses``, for each
1339 compilation step. 1268 package. The license files are placed in directories within the image
1340 1269 itself during build time.
1341 Default initialization for ``CPPFLAGS`` varies depending on what is 1270
1342 being built: 1271 .. note::
1343 1272
1344 - ```TARGET_CPPFLAGS`` <#var-TARGET_CPPFLAGS>`__ when building for 1273 The
1345 the target 1274 COPY_LIC_DIRS
1346 1275 does not offer a path for adding licenses for newly installed
1347 - ```BUILD_CPPFLAGS`` <#var-BUILD_CPPFLAGS>`__ when building for the 1276 packages to an image, which might be most suitable for read-only
1348 build host (i.e. ``-native``) 1277 filesystems that cannot be upgraded. See the
1349 1278 LICENSE_CREATE_PACKAGE
1350 - ```BUILDSDK_CPPFLAGS`` <#var-BUILDSDK_CPPFLAGS>`__ when building 1279 variable for additional information. You can also reference the "
1351 for an SDK (i.e. ``nativesdk-``) 1280 Providing License Text
1352 1281 " section in the Yocto Project Development Tasks Manual for
1353CROSS_COMPILE 1282 information on providing license text.
1354 The toolchain binary prefix for the target tools. The 1283
1355 ``CROSS_COMPILE`` variable is the same as the 1284 COPY_LIC_MANIFEST
1356 ```TARGET_PREFIX`` <#var-TARGET_PREFIX>`__ variable. 1285 If set to "1", the OpenEmbedded build system copies the license
1357 1286 manifest for the image to
1358 .. note:: 1287 ``/usr/share/common-licenses/license.manifest`` within the image
1359 1288 itself during build time.
1360 The OpenEmbedded build system sets the 1289
1361 CROSS_COMPILE 1290 .. note::
1362 variable only in certain contexts (e.g. when building for kernel 1291
1363 and kernel module recipes). 1292 The
1364 1293 COPY_LIC_MANIFEST
1365CVSDIR 1294 does not offer a path for adding licenses for newly installed
1366 The directory in which files checked out under the CVS system are 1295 packages to an image, which might be most suitable for read-only
1367 stored. 1296 filesystems that cannot be upgraded. See the
1368 1297 LICENSE_CREATE_PACKAGE
1369CXX 1298 variable for additional information. You can also reference the "
1370 The minimal command and arguments used to run the C++ compiler. 1299 Providing License Text
1371 1300 " section in the Yocto Project Development Tasks Manual for
1372CXXFLAGS 1301 information on providing license text.
1373 Specifies the flags to pass to the C++ compiler. This variable is 1302
1374 exported to an environment variable and thus made visible to the 1303 CORE_IMAGE_EXTRA_INSTALL
1375 software being built during the compilation step. 1304 Specifies the list of packages to be added to the image. You should
1376 1305 only set this variable in the ``local.conf`` configuration file found
1377 Default initialization for ``CXXFLAGS`` varies depending on what is 1306 in the :term:`Build Directory`.
1378 being built: 1307
1379 1308 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
1380 - ```TARGET_CXXFLAGS`` <#var-TARGET_CXXFLAGS>`__ when building for 1309 supported.
1381 the target 1310
1382 1311 COREBASE
1383 - ```BUILD_CXXFLAGS`` <#var-BUILD_CXXFLAGS>`__ when building for the 1312 Specifies the parent directory of the OpenEmbedded-Core Metadata
1384 build host (i.e. ``-native``) 1313 layer (i.e. ``meta``).
1385 1314
1386 - ```BUILDSDK_CXXFLAGS`` <#var-BUILDSDK_CXXFLAGS>`__ when building 1315 It is an important distinction that ``COREBASE`` points to the parent
1387 for an SDK (i.e. ``nativesdk-``) 1316 of this layer and not the layer itself. Consider an example where you
1388 1317 have cloned the Poky Git repository and retained the ``poky`` name
1389D 1318 for your local copy of the repository. In this case, ``COREBASE``
1390 The destination directory. The location in the `Build 1319 points to the ``poky`` folder because it is the parent directory of
1391 Directory <#build-directory>`__ where components are installed by the 1320 the ``poky/meta`` layer.
1392 ```do_install`` <#ref-tasks-install>`__ task. This location defaults 1321
1393 to: ${WORKDIR}/image 1322 COREBASE_FILES
1394 1323 Lists files from the :term:`COREBASE` directory that
1395 .. note:: 1324 should be copied other than the layers listed in the
1396 1325 ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for
1397 Tasks that read from or write to this directory should run under 1326 the purpose of copying metadata from the OpenEmbedded build system
1398 fakeroot 1327 into the extensible SDK.
1399 . 1328
1400 1329 Explicitly listing files in ``COREBASE`` is needed because it
1401DATE 1330 typically contains build directories and other files that should not
1402 The date the build was started. Dates appear using the year, month, 1331 normally be copied into the extensible SDK. Consequently, the value
1403 and day (YMD) format (e.g. "20150209" for February 9th, 2015). 1332 of ``COREBASE_FILES`` is used in order to only copy the files that
1404 1333 are actually needed.
1405DATETIME 1334
1406 The date and time on which the current build started. The format is 1335 CPP
1407 suitable for timestamps. 1336 The minimal command and arguments used to run the C preprocessor.
1408 1337
1409DEBIAN_NOAUTONAME 1338 CPPFLAGS
1410 When the ```debian`` <#ref-classes-debian>`__ class is inherited, 1339 Specifies the flags to pass to the C pre-processor (i.e. to both the
1411 which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a 1340 C and the C++ compilers). This variable is exported to an environment
1412 particular package should not be renamed according to Debian library 1341 variable and thus made visible to the software being built during the
1413 package naming. You must use the package name as an override when you 1342 compilation step.
1414 set this variable. Here is an example from the ``fontconfig`` recipe: 1343
1415 DEBIAN_NOAUTONAME_fontconfig-utils = "1" 1344 Default initialization for ``CPPFLAGS`` varies depending on what is
1416 1345 being built:
1417DEBIANNAME 1346
1418 When the ```debian`` <#ref-classes-debian>`__ class is inherited, 1347 - :term:`TARGET_CPPFLAGS` when building for
1419 which is the default behavior, ``DEBIANNAME`` allows you to override 1348 the target
1420 the library name for an individual package. Overriding the library 1349
1421 name in these cases is rare. You must use the package name as an 1350 - :term:`BUILD_CPPFLAGS` when building for the
1422 override when you set this variable. Here is an example from the 1351 build host (i.e. ``-native``)
1423 ``dbus`` recipe: DEBIANNAME_${PN} = "dbus-1" 1352
1424 1353 - :term:`BUILDSDK_CPPFLAGS` when building
1425DEBUG_BUILD 1354 for an SDK (i.e. ``nativesdk-``)
1426 Specifies to build packages with debugging information. This 1355
1427 influences the value of the ``SELECTED_OPTIMIZATION`` variable. 1356 CROSS_COMPILE
1428 1357 The toolchain binary prefix for the target tools. The
1429DEBUG_OPTIMIZATION 1358 ``CROSS_COMPILE`` variable is the same as the
1430 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when 1359 :term:`TARGET_PREFIX` variable.
1431 compiling a system for debugging. This variable defaults to "-O 1360
1432 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1361 .. note::
1433 1362
1434DEFAULT_PREFERENCE 1363 The OpenEmbedded build system sets the
1435 Specifies a weak bias for recipe selection priority. 1364 CROSS_COMPILE
1436 1365 variable only in certain contexts (e.g. when building for kernel
1437 The most common usage of this is variable is to set it to "-1" within 1366 and kernel module recipes).
1438 a recipe for a development version of a piece of software. Using the 1367
1439 variable in this way causes the stable version of the recipe to build 1368 CVSDIR
1440 by default in the absence of ``PREFERRED_VERSION`` being used to 1369 The directory in which files checked out under the CVS system are
1441 build the development version. 1370 stored.
1442 1371
1443 .. note:: 1372 CXX
1444 1373 The minimal command and arguments used to run the C++ compiler.
1445 The bias provided by 1374
1446 DEFAULT_PREFERENCE 1375 CXXFLAGS
1447 is weak and is overridden by 1376 Specifies the flags to pass to the C++ compiler. This variable is
1448 BBFILE_PRIORITY 1377 exported to an environment variable and thus made visible to the
1449 if that variable is different between two layers that contain 1378 software being built during the compilation step.
1450 different versions of the same recipe. 1379
1451 1380 Default initialization for ``CXXFLAGS`` varies depending on what is
1452DEFAULTTUNE 1381 being built:
1453 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1382
1454 the "tune") used by the OpenEmbedded build system. The 1383 - :term:`TARGET_CXXFLAGS` when building for
1455 ``DEFAULTTUNE`` helps define 1384 the target
1456 ```TUNE_FEATURES`` <#var-TUNE_FEATURES>`__. 1385
1457 1386 - :term:`BUILD_CXXFLAGS` when building for the
1458 The default tune is either implicitly or explicitly set by the 1387 build host (i.e. ``-native``)
1459 machine (```MACHINE`` <#var-MACHINE>`__). However, you can override 1388
1460 the setting using available tunes as defined with 1389 - :term:`BUILDSDK_CXXFLAGS` when building
1461 ```AVAILTUNES`` <#var-AVAILTUNES>`__. 1390 for an SDK (i.e. ``nativesdk-``)
1462 1391
1463DEPENDS 1392 D
1464 Lists a recipe's build-time dependencies. These are dependencies on 1393 The destination directory. The location in the :term:`Build Directory`
1465 other recipes whose contents (e.g. headers and shared libraries) are 1394 where components are installed by the
1466 needed by the recipe at build time. 1395 :ref:`ref-tasks-install` task. This location defaults
1467 1396 to: ${WORKDIR}/image
1468 As an example, consider a recipe ``foo`` that contains the following 1397
1469 assignment: DEPENDS = "bar" The practical effect of the previous 1398 .. note::
1470 assignment is that all files installed by bar will be available in 1399
1471 the appropriate staging sysroot, given by the 1400 Tasks that read from or write to this directory should run under
1472 ```STAGING_DIR*`` <#var-STAGING_DIR>`__ variables, by the time the 1401 fakeroot
1473 ```do_configure`` <#ref-tasks-configure>`__ task for ``foo`` runs. 1402 .
1474 This mechanism is implemented by having ``do_configure`` depend on 1403
1475 the ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task of 1404 DATE
1476 each recipe listed in ``DEPENDS``, through a 1405 The date the build was started. Dates appear using the year, month,
1477 ``[``\ ```deptask`` <&YOCTO_DOCS_BB_URL;#variable-flags>`__\ ``]`` 1406 and day (YMD) format (e.g. "20150209" for February 9th, 2015).
1478 declaration in the ```base`` <#ref-classes-base>`__ class. 1407
1479 1408 DATETIME
1480 .. note:: 1409 The date and time on which the current build started. The format is
1481 1410 suitable for timestamps.
1482 It seldom is necessary to reference, for example, 1411
1483 STAGING_DIR_HOST 1412 DEBIAN_NOAUTONAME
1484 explicitly. The standard classes and build-related variables are 1413 When the :ref:`debian <ref-classes-debian>` class is inherited,
1485 configured to automatically use the appropriate staging sysroots. 1414 which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a
1486 1415 particular package should not be renamed according to Debian library
1487 As another example, ``DEPENDS`` can also be used to add utilities 1416 package naming. You must use the package name as an override when you
1488 that run on the build machine during the build. For example, a recipe 1417 set this variable. Here is an example from the ``fontconfig`` recipe:
1489 that makes use of a code generator built by the recipe ``codegen`` 1418 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
1490 might have the following: DEPENDS = "codegen-native" For more 1419
1491 information, see the ```native`` <#ref-classes-native>`__ class and 1420 DEBIANNAME
1492 the ```EXTRANATIVEPATH`` <#var-EXTRANATIVEPATH>`__ variable. 1421 When the :ref:`debian <ref-classes-debian>` class is inherited,
1493 1422 which is the default behavior, ``DEBIANNAME`` allows you to override
1494 .. note:: 1423 the library name for an individual package. Overriding the library
1495 1424 name in these cases is rare. You must use the package name as an
1496 - ``DEPENDS`` is a list of recipe names. Or, to be more precise, 1425 override when you set this variable. Here is an example from the
1497 it is a list of ```PROVIDES`` <#var-PROVIDES>`__ names, which 1426 ``dbus`` recipe: DEBIANNAME_${PN} = "dbus-1"
1498 usually match recipe names. Putting a package name such as 1427
1499 "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" 1428 DEBUG_BUILD
1500 instead, as this will put files from all the packages that make 1429 Specifies to build packages with debugging information. This
1501 up ``foo``, which includes those from ``foo-dev``, into the 1430 influences the value of the ``SELECTED_OPTIMIZATION`` variable.
1502 sysroot. 1431
1503 1432 DEBUG_OPTIMIZATION
1504 - One recipe having another recipe in ``DEPENDS`` does not by 1433 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when
1505 itself add any runtime dependencies between the packages 1434 compiling a system for debugging. This variable defaults to "-O
1506 produced by the two recipes. However, as explained in the 1435 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1507 "`Automatically Added Runtime 1436
1508 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 1437 DEFAULT_PREFERENCE
1509 section in the Yocto Project Overview and Concepts Manual, 1438 Specifies a weak bias for recipe selection priority.
1510 runtime dependencies will often be added automatically, meaning 1439
1511 ``DEPENDS`` alone is sufficient for most recipes. 1440 The most common usage of this is variable is to set it to "-1" within
1512 1441 a recipe for a development version of a piece of software. Using the
1513 - Counterintuitively, ``DEPENDS`` is often necessary even for 1442 variable in this way causes the stable version of the recipe to build
1514 recipes that install precompiled components. For example, if 1443 by default in the absence of ``PREFERRED_VERSION`` being used to
1515 ``libfoo`` is a precompiled library that links against 1444 build the development version.
1516 ``libbar``, then linking against ``libfoo`` requires both 1445
1517 ``libfoo`` and ``libbar`` to be available in the sysroot. 1446 .. note::
1518 Without a ``DEPENDS`` from the recipe that installs ``libfoo`` 1447
1519 to the recipe that installs ``libbar``, other recipes might 1448 The bias provided by
1520 fail to link against ``libfoo``. 1449 DEFAULT_PREFERENCE
1521 1450 is weak and is overridden by
1522 For information on runtime dependencies, see the 1451 BBFILE_PRIORITY
1523 ```RDEPENDS`` <#var-RDEPENDS>`__ variable. You can also see the 1452 if that variable is different between two layers that contain
1524 "`Tasks <&YOCTO_DOCS_BB_URL;#tasks>`__" and 1453 different versions of the same recipe.
1525 "`Dependencies <&YOCTO_DOCS_BB_URL;#dependencies>`__" sections in the 1454
1526 BitBake User Manual for additional information on tasks and 1455 DEFAULTTUNE
1527 dependencies. 1456 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1528 1457 the "tune") used by the OpenEmbedded build system. The
1529DEPLOY_DIR 1458 ``DEFAULTTUNE`` helps define
1530 Points to the general area that the OpenEmbedded build system uses to 1459 :term:`TUNE_FEATURES`.
1531 place images, packages, SDKs, and other output files that are ready 1460
1532 to be used outside of the build system. By default, this directory 1461 The default tune is either implicitly or explicitly set by the
1533 resides within the `Build Directory <#build-directory>`__ as 1462 machine (:term:`MACHINE`). However, you can override
1534 ``${TMPDIR}/deploy``. 1463 the setting using available tunes as defined with
1535 1464 :term:`AVAILTUNES`.
1536 For more information on the structure of the Build Directory, see 1465
1537 "`The Build Directory - ``build/`` <#structure-build>`__" section. 1466 DEPENDS
1538 For more detail on the contents of the ``deploy`` directory, see the 1467 Lists a recipe's build-time dependencies. These are dependencies on
1539 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__", "`Package 1468 other recipes whose contents (e.g. headers and shared libraries) are
1540 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__", and 1469 needed by the recipe at build time.
1541 "`Application Development 1470
1542 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections all in the 1471 As an example, consider a recipe ``foo`` that contains the following
1543 Yocto Project Overview and Concepts Manual. 1472 assignment: DEPENDS = "bar" The practical effect of the previous
1544 1473 assignment is that all files installed by bar will be available in
1545DEPLOY_DIR_DEB 1474 the appropriate staging sysroot, given by the
1546 Points to the area that the OpenEmbedded build system uses to place 1475 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the
1547 Debian packages that are ready to be used outside of the build 1476 :ref:`ref-tasks-configure` task for ``foo`` runs.
1548 system. This variable applies only when 1477 This mechanism is implemented by having ``do_configure`` depend on
1549 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__ contains 1478 the :ref:`ref-tasks-populate_sysroot` task of
1550 "package_deb". 1479 each recipe listed in ``DEPENDS``, through a
1551 1480 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1552 The BitBake configuration file initially defines the 1481 declaration in the :ref:`base <ref-classes-base>` class.
1553 ``DEPLOY_DIR_DEB`` variable as a sub-folder of 1482
1554 ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__: DEPLOY_DIR_DEB = 1483 .. note::
1555 "${DEPLOY_DIR}/deb" 1484
1556 1485 It seldom is necessary to reference, for example,
1557 The ```package_deb`` <#ref-classes-package_deb>`__ class uses the 1486 STAGING_DIR_HOST
1558 ``DEPLOY_DIR_DEB`` variable to make sure the 1487 explicitly. The standard classes and build-related variables are
1559 ```do_package_write_deb`` <#ref-tasks-package_write_deb>`__ task 1488 configured to automatically use the appropriate staging sysroots.
1560 writes Debian packages into the appropriate folder. For more 1489
1561 information on how packaging works, see the "`Package 1490 As another example, ``DEPENDS`` can also be used to add utilities
1562 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1491 that run on the build machine during the build. For example, a recipe
1563 in the Yocto Project Overview and Concepts Manual. 1492 that makes use of a code generator built by the recipe ``codegen``
1564 1493 might have the following: DEPENDS = "codegen-native" For more
1565DEPLOY_DIR_IMAGE 1494 information, see the :ref:`native <ref-classes-native>` class and
1566 Points to the area that the OpenEmbedded build system uses to place 1495 the :term:`EXTRANATIVEPATH` variable.
1567 images and other associated output files that are ready to be 1496
1568 deployed onto the target machine. The directory is machine-specific 1497 .. note::
1569 as it contains the ``${MACHINE}`` name. By default, this directory 1498
1570 resides within the `Build Directory <#build-directory>`__ as 1499 - ``DEPENDS`` is a list of recipe names. Or, to be more precise,
1571 ``${DEPLOY_DIR}/images/${MACHINE}/``. 1500 it is a list of :term:`PROVIDES` names, which
1572 1501 usually match recipe names. Putting a package name such as
1573 For more information on the structure of the Build Directory, see 1502 "foo-dev" in ``DEPENDS`` does not make sense. Use "foo"
1574 "`The Build Directory - ``build/`` <#structure-build>`__" section. 1503 instead, as this will put files from all the packages that make
1575 For more detail on the contents of the ``deploy`` directory, see the 1504 up ``foo``, which includes those from ``foo-dev``, into the
1576 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and 1505 sysroot.
1577 "`Application Development 1506
1578 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections both in 1507 - One recipe having another recipe in ``DEPENDS`` does not by
1579 the Yocto Project Overview and Concepts Manual. 1508 itself add any runtime dependencies between the packages
1580 1509 produced by the two recipes. However, as explained in the
1581DEPLOY_DIR_IPK 1510 "`Automatically Added Runtime
1582 Points to the area that the OpenEmbedded build system uses to place 1511 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
1583 IPK packages that are ready to be used outside of the build system. 1512 section in the Yocto Project Overview and Concepts Manual,
1584 This variable applies only when 1513 runtime dependencies will often be added automatically, meaning
1585 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__ contains 1514 ``DEPENDS`` alone is sufficient for most recipes.
1586 "package_ipk". 1515
1587 1516 - Counterintuitively, ``DEPENDS`` is often necessary even for
1588 The BitBake configuration file initially defines this variable as a 1517 recipes that install precompiled components. For example, if
1589 sub-folder of ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__: DEPLOY_DIR_IPK = 1518 ``libfoo`` is a precompiled library that links against
1590 "${DEPLOY_DIR}/ipk" 1519 ``libbar``, then linking against ``libfoo`` requires both
1591 1520 ``libfoo`` and ``libbar`` to be available in the sysroot.
1592 The ```package_ipk`` <#ref-classes-package_ipk>`__ class uses the 1521 Without a ``DEPENDS`` from the recipe that installs ``libfoo``
1593 ``DEPLOY_DIR_IPK`` variable to make sure the 1522 to the recipe that installs ``libbar``, other recipes might
1594 ```do_package_write_ipk`` <#ref-tasks-package_write_ipk>`__ task 1523 fail to link against ``libfoo``.
1595 writes IPK packages into the appropriate folder. For more information 1524
1596 on how packaging works, see the "`Package 1525 For information on runtime dependencies, see the
1597 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1526 :term:`RDEPENDS` variable. You can also see the
1598 in the Yocto Project Overview and Concepts Manual. 1527 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and
1599 1528 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the
1600DEPLOY_DIR_RPM 1529 BitBake User Manual for additional information on tasks and
1601 Points to the area that the OpenEmbedded build system uses to place 1530 dependencies.
1602 RPM packages that are ready to be used outside of the build system. 1531
1603 This variable applies only when 1532 DEPLOY_DIR
1604 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__ contains 1533 Points to the general area that the OpenEmbedded build system uses to
1605 "package_rpm". 1534 place images, packages, SDKs, and other output files that are ready
1606 1535 to be used outside of the build system. By default, this directory
1607 The BitBake configuration file initially defines this variable as a 1536 resides within the :term:`Build Directory` as
1608 sub-folder of ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__: DEPLOY_DIR_RPM = 1537 ``${TMPDIR}/deploy``.
1609 "${DEPLOY_DIR}/rpm" 1538
1610 1539 For more information on the structure of the Build Directory, see
1611 The ```package_rpm`` <#ref-classes-package_rpm>`__ class uses the 1540 "`The Build Directory - ``build/`` <#structure-build>`__" section.
1612 ``DEPLOY_DIR_RPM`` variable to make sure the 1541 For more detail on the contents of the ``deploy`` directory, see the
1613 ```do_package_write_rpm`` <#ref-tasks-package_write_rpm>`__ task 1542 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__", "`Package
1614 writes RPM packages into the appropriate folder. For more information 1543 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__", and
1615 on how packaging works, see the "`Package 1544 "`Application Development
1616 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1545 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections all in the
1617 in the Yocto Project Overview and Concepts Manual. 1546 Yocto Project Overview and Concepts Manual.
1618 1547
1619DEPLOY_DIR_TAR 1548 DEPLOY_DIR_DEB
1620 Points to the area that the OpenEmbedded build system uses to place 1549 Points to the area that the OpenEmbedded build system uses to place
1621 tarballs that are ready to be used outside of the build system. This 1550 Debian packages that are ready to be used outside of the build
1622 variable applies only when 1551 system. This variable applies only when
1623 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__ contains 1552 :term:`PACKAGE_CLASSES` contains
1624 "package_tar". 1553 "package_deb".
1625 1554
1626 The BitBake configuration file initially defines this variable as a 1555 The BitBake configuration file initially defines the
1627 sub-folder of ```DEPLOY_DIR`` <#var-DEPLOY_DIR>`__: DEPLOY_DIR_TAR = 1556 ``DEPLOY_DIR_DEB`` variable as a sub-folder of
1628 "${DEPLOY_DIR}/tar" 1557 :term:`DEPLOY_DIR`: DEPLOY_DIR_DEB =
1629 1558 "${DEPLOY_DIR}/deb"
1630 The ```package_tar`` <#ref-classes-package_tar>`__ class uses the 1559
1631 ``DEPLOY_DIR_TAR`` variable to make sure the 1560 The :ref:`package_deb <ref-classes-package_deb>` class uses the
1632 ```do_package_write_tar`` <#ref-tasks-package_write_tar>`__ task 1561 ``DEPLOY_DIR_DEB`` variable to make sure the
1633 writes TAR packages into the appropriate folder. For more information 1562 :ref:`ref-tasks-package_write_deb` task
1634 on how packaging works, see the "`Package 1563 writes Debian packages into the appropriate folder. For more
1635 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1564 information on how packaging works, see the "`Package
1636 in the Yocto Project Overview and Concepts Manual. 1565 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section
1637 1566 in the Yocto Project Overview and Concepts Manual.
1638DEPLOYDIR 1567
1639 When inheriting the ```deploy`` <#ref-classes-deploy>`__ class, the 1568 DEPLOY_DIR_IMAGE
1640 ``DEPLOYDIR`` points to a temporary work area for deployed files that 1569 Points to the area that the OpenEmbedded build system uses to place
1641 is set in the ``deploy`` class as follows: DEPLOYDIR = 1570 images and other associated output files that are ready to be
1642 "${WORKDIR}/deploy-${```PN`` <#var-PN>`__}" 1571 deployed onto the target machine. The directory is machine-specific
1643 1572 as it contains the ``${MACHINE}`` name. By default, this directory
1644 Recipes inheriting the ``deploy`` class should copy files to be 1573 resides within the :term:`Build Directory` as
1645 deployed into ``DEPLOYDIR``, and the class will take care of copying 1574 ``${DEPLOY_DIR}/images/${MACHINE}/``.
1646 them into ```DEPLOY_DIR_IMAGE`` <#var-DEPLOY_DIR_IMAGE>`__ 1575
1647 afterwards. 1576 For more information on the structure of the Build Directory, see
1648 1577 "`The Build Directory - ``build/`` <#structure-build>`__" section.
1649DESCRIPTION 1578 For more detail on the contents of the ``deploy`` directory, see the
1650 The package description used by package managers. If not set, 1579 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and
1651 ``DESCRIPTION`` takes the value of the ```SUMMARY`` <#var-SUMMARY>`__ 1580 "`Application Development
1652 variable. 1581 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections both in
1653 1582 the Yocto Project Overview and Concepts Manual.
1654DISTRO 1583
1655 The short name of the distribution. For information on the long name 1584 DEPLOY_DIR_IPK
1656 of the distribution, see the ```DISTRO_NAME`` <#var-DISTRO_NAME>`__ 1585 Points to the area that the OpenEmbedded build system uses to place
1657 variable. 1586 IPK packages that are ready to be used outside of the build system.
1658 1587 This variable applies only when
1659 The ``DISTRO`` variable corresponds to a distribution configuration 1588 :term:`PACKAGE_CLASSES` contains
1660 file whose root name is the same as the variable's argument and whose 1589 "package_ipk".
1661 filename extension is ``.conf``. For example, the distribution 1590
1662 configuration file for the Poky distribution is named ``poky.conf`` 1591 The BitBake configuration file initially defines this variable as a
1663 and resides in the ``meta-poky/conf/distro`` directory of the `Source 1592 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_IPK =
1664 Directory <#source-directory>`__. 1593 "${DEPLOY_DIR}/ipk"
1665 1594
1666 Within that ``poky.conf`` file, the ``DISTRO`` variable is set as 1595 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the
1667 follows: DISTRO = "poky" 1596 ``DEPLOY_DIR_IPK`` variable to make sure the
1668 1597 :ref:`ref-tasks-package_write_ipk` task
1669 Distribution configuration files are located in a ``conf/distro`` 1598 writes IPK packages into the appropriate folder. For more information
1670 directory within the `Metadata <#metadata>`__ that contains the 1599 on how packaging works, see the "`Package
1671 distribution configuration. The value for ``DISTRO`` must not contain 1600 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section
1672 spaces, and is typically all lower-case. 1601 in the Yocto Project Overview and Concepts Manual.
1673 1602
1674 .. note:: 1603 DEPLOY_DIR_RPM
1675 1604 Points to the area that the OpenEmbedded build system uses to place
1676 If the 1605 RPM packages that are ready to be used outside of the build system.
1677 DISTRO 1606 This variable applies only when
1678 variable is blank, a set of default configurations are used, which 1607 :term:`PACKAGE_CLASSES` contains
1679 are specified within 1608 "package_rpm".
1680 meta/conf/distro/defaultsetup.conf 1609
1681 also in the Source Directory. 1610 The BitBake configuration file initially defines this variable as a
1682 1611 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_RPM =
1683DISTRO_CODENAME 1612 "${DEPLOY_DIR}/rpm"
1684 Specifies a codename for the distribution being built. 1613
1685 1614 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the
1686DISTRO_EXTRA_RDEPENDS 1615 ``DEPLOY_DIR_RPM`` variable to make sure the
1687 Specifies a list of distro-specific packages to add to all images. 1616 :ref:`ref-tasks-package_write_rpm` task
1688 This variable takes affect through ``packagegroup-base`` so the 1617 writes RPM packages into the appropriate folder. For more information
1689 variable only really applies to the more full-featured images that 1618 on how packaging works, see the "`Package
1690 include ``packagegroup-base``. You can use this variable to keep 1619 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section
1691 distro policy out of generic images. As with all other distro 1620 in the Yocto Project Overview and Concepts Manual.
1692 variables, you set this variable in the distro ``.conf`` file. 1621
1693 1622 DEPLOY_DIR_TAR
1694DISTRO_EXTRA_RRECOMMENDS 1623 Points to the area that the OpenEmbedded build system uses to place
1695 Specifies a list of distro-specific packages to add to all images if 1624 tarballs that are ready to be used outside of the build system. This
1696 the packages exist. The packages might not exist or be empty (e.g. 1625 variable applies only when
1697 kernel modules). The list of packages are automatically installed but 1626 :term:`PACKAGE_CLASSES` contains
1698 you can remove them. 1627 "package_tar".
1699 1628
1700DISTRO_FEATURES 1629 The BitBake configuration file initially defines this variable as a
1701 The software support you want in your distribution for various 1630 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_TAR =
1702 features. You define your distribution features in the distribution 1631 "${DEPLOY_DIR}/tar"
1703 configuration file. 1632
1704 1633 The :ref:`package_tar <ref-classes-package_tar>` class uses the
1705 In most cases, the presence or absence of a feature in 1634 ``DEPLOY_DIR_TAR`` variable to make sure the
1706 ``DISTRO_FEATURES`` is translated to the appropriate option supplied 1635 :ref:`ref-tasks-package_write_tar` task
1707 to the configure script during the 1636 writes TAR packages into the appropriate folder. For more information
1708 ```do_configure`` <#ref-tasks-configure>`__ task for recipes that 1637 on how packaging works, see the "`Package
1709 optionally support the feature. For example, specifying "x11" in 1638 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section
1710 ``DISTRO_FEATURES``, causes every piece of software built for the 1639 in the Yocto Project Overview and Concepts Manual.
1711 target that can optionally support X11 to have its X11 support 1640
1712 enabled. 1641 DEPLOYDIR
1713 1642 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the
1714 Two more examples are Bluetooth and NFS support. For a more complete 1643 ``DEPLOYDIR`` points to a temporary work area for deployed files that
1715 list of features that ships with the Yocto Project and that you can 1644 is set in the ``deploy`` class as follows: DEPLOYDIR =
1716 provide with this variable, see the "`Distro 1645 "${WORKDIR}/deploy-${:term:`PN`}"
1717 Features <#ref-features-distro>`__" section. 1646
1718 1647 Recipes inheriting the ``deploy`` class should copy files to be
1719DISTRO_FEATURES_BACKFILL 1648 deployed into ``DEPLOYDIR``, and the class will take care of copying
1720 Features to be added to ``DISTRO_FEATURES`` if not also present in 1649 them into :term:`DEPLOY_DIR_IMAGE`
1721 ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. 1650 afterwards.
1722 1651
1723 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 1652 DESCRIPTION
1724 not intended to be user-configurable. It is best to just reference 1653 The package description used by package managers. If not set,
1725 the variable to see which distro features are being backfilled for 1654 ``DESCRIPTION`` takes the value of the :term:`SUMMARY`
1726 all distro configurations. See the "`Feature
1727 Backfilling <#ref-features-backfill>`__" section for more
1728 information.
1729
1730DISTRO_FEATURES_BACKFILL_CONSIDERED
1731 Features from ``DISTRO_FEATURES_BACKFILL`` that should not be
1732 backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See
1733 the "`Feature Backfilling <#ref-features-backfill>`__" section for
1734 more information.
1735
1736DISTRO_FEATURES_DEFAULT
1737 A convenience variable that gives you the default list of distro
1738 features with the exception of any features specific to the C library
1739 (``libc``).
1740
1741 When creating a custom distribution, you might find it useful to be
1742 able to reuse the default
1743 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ options without the
1744 need to write out the full set. Here is an example that uses
1745 ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file:
1746 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
1747
1748DISTRO_FEATURES_FILTER_NATIVE
1749 Specifies a list of features that if present in the target
1750 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ value should be
1751 included in ``DISTRO_FEATURES`` when building native recipes. This
1752 variable is used in addition to the features filtered using the
1753 ```DISTRO_FEATURES_NATIVE`` <#var-DISTRO_FEATURES_NATIVE>`__
1754 variable.
1755
1756DISTRO_FEATURES_FILTER_NATIVESDK
1757 Specifies a list of features that if present in the target
1758 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ value should be
1759 included in ``DISTRO_FEATURES`` when building nativesdk recipes. This
1760 variable is used in addition to the features filtered using the
1761 ```DISTRO_FEATURES_NATIVESDK`` <#var-DISTRO_FEATURES_NATIVESDK>`__
1762 variable.
1763
1764DISTRO_FEATURES_NATIVE
1765 Specifies a list of features that should be included in
1766 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ when building native
1767 recipes. This variable is used in addition to the features filtered
1768 using the
1769 ```DISTRO_FEATURES_FILTER_NATIVE`` <#var-DISTRO_FEATURES_FILTER_NATIVE>`__
1770 variable.
1771
1772DISTRO_FEATURES_NATIVESDK
1773 Specifies a list of features that should be included in
1774 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__ when building
1775 nativesdk recipes. This variable is used in addition to the features
1776 filtered using the
1777 ```DISTRO_FEATURES_FILTER_NATIVESDK`` <#var-DISTRO_FEATURES_FILTER_NATIVESDK>`__
1778 variable.
1779
1780DISTRO_NAME
1781 The long name of the distribution. For information on the short name
1782 of the distribution, see the ```DISTRO`` <#var-DISTRO>`__ variable.
1783
1784 The ``DISTRO_NAME`` variable corresponds to a distribution
1785 configuration file whose root name is the same as the variable's
1786 argument and whose filename extension is ``.conf``. For example, the
1787 distribution configuration file for the Poky distribution is named
1788 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
1789 of the `Source Directory <#source-directory>`__.
1790
1791 Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set
1792 as follows: DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
1793
1794 Distribution configuration files are located in a ``conf/distro``
1795 directory within the `Metadata <#metadata>`__ that contains the
1796 distribution configuration.
1797
1798 .. note::
1799
1800 If the
1801 DISTRO_NAME
1802 variable is blank, a set of default configurations are used, which
1803 are specified within
1804 meta/conf/distro/defaultsetup.conf
1805 also in the Source Directory.
1806
1807DISTRO_VERSION
1808 The version of the distribution.
1809
1810DISTROOVERRIDES
1811 A colon-separated list of overrides specific to the current
1812 distribution. By default, this list includes the value of
1813 ```DISTRO`` <#var-DISTRO>`__.
1814
1815 You can extend ``DISTROOVERRIDES`` to add extra overrides that should
1816 apply to the distribution.
1817
1818 The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it
1819 is included in the default value of
1820 ```OVERRIDES`` <#var-OVERRIDES>`__.
1821
1822DL_DIR
1823 The central download directory used by the build process to store
1824 downloads. By default, ``DL_DIR`` gets files suitable for mirroring
1825 for everything except Git repositories. If you want tarballs of Git
1826 repositories, use the
1827 ```BB_GENERATE_MIRROR_TARBALLS`` <#var-BB_GENERATE_MIRROR_TARBALLS>`__
1828 variable.
1829
1830 You can set this directory by defining the ``DL_DIR`` variable in the
1831 ``conf/local.conf`` file. This directory is self-maintaining and you
1832 should not have to touch it. By default, the directory is
1833 ``downloads`` in the `Build Directory <#build-directory>`__. #DL_DIR
1834 ?= "${TOPDIR}/downloads" To specify a different download directory,
1835 simply remove the comment from the line and provide your directory.
1836
1837 During a first build, the system downloads many different source code
1838 tarballs from various upstream projects. Downloading can take a
1839 while, particularly if your network connection is slow. Tarballs are
1840 all stored in the directory defined by ``DL_DIR`` and the build
1841 system looks there first to find source tarballs.
1842
1843 .. note::
1844
1845 When wiping and rebuilding, you can preserve this directory to
1846 speed up this part of subsequent builds.
1847
1848 You can safely share this directory between multiple builds on the
1849 same development machine. For additional information on how the build
1850 process gets source files when working behind a firewall or proxy
1851 server, see this specific question in the
1852 "`FAQ <#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server>`__"
1853 chapter. You can also refer to the "`Working Behind a Network
1854 Proxy <&YOCTO_WIKI_URL;/wiki/Working_Behind_a_Network_Proxy>`__" Wiki
1855 page.
1856
1857DOC_COMPRESS
1858 When inheriting the ```compress_doc`` <#ref-classes-compress_doc>`__
1859 class, this variable sets the compression policy used when the
1860 OpenEmbedded build system compresses man pages and info pages. By
1861 default, the compression method used is gz (gzip). Other policies
1862 available are xz and bz2.
1863
1864 For information on policies and on how to use this variable, see the
1865 comments in the ``meta/classes/compress_doc.bbclass`` file.
1866
1867EFI_PROVIDER
1868 When building bootable images (i.e. where ``hddimg``, ``iso``, or
1869 ``wic.vmdk`` is in ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__), the
1870 ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The
1871 default is "grub-efi", but "systemd-boot" can be used instead.
1872
1873 See the ```systemd-boot`` <#ref-classes-systemd-boot>`__ and
1874 ```image-live`` <#ref-classes-image-live>`__ classes for more
1875 information.
1876
1877ENABLE_BINARY_LOCALE_GENERATION
1878 Variable that controls which locales for ``glibc`` are generated
1879 during the build (useful if the target device has 64Mbytes of RAM or
1880 less).
1881
1882ERR_REPORT_DIR
1883 When used with the ```report-error`` <#ref-classes-report-error>`__
1884 class, specifies the path used for storing the debug files created by
1885 the `error reporting
1886 tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which
1887 allows you to submit build errors you encounter to a central
1888 database. By default, the value of this variable is
1889 ``${``\ ```LOG_DIR`` <#var-LOG_DIR>`__\ ``}/error-report``.
1890
1891 You can set ``ERR_REPORT_DIR`` to the path you want the error
1892 reporting tool to store the debug files as follows in your
1893 ``local.conf`` file: ERR_REPORT_DIR = "path"
1894
1895ERROR_QA
1896 Specifies the quality assurance checks whose failures are reported as
1897 errors by the OpenEmbedded build system. You set this variable in
1898 your distribution configuration file. For a list of the checks you
1899 can control with this variable, see the
1900 "```insane.bbclass`` <#ref-classes-insane>`__" section.
1901
1902EXCLUDE_FROM_SHLIBS
1903 Triggers the OpenEmbedded build system's shared libraries resolver to
1904 exclude an entire package when scanning for shared libraries.
1905
1906 .. note::
1907
1908 The shared libraries resolver's functionality results in part from
1909 the internal function
1910 package_do_shlibs
1911 , which is part of the
1912 do_package
1913 task. You should be aware that the shared libraries resolver might
1914 implicitly define some dependencies between packages.
1915
1916 The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the
1917 ```PRIVATE_LIBS`` <#var-PRIVATE_LIBS>`__ variable, which excludes a
1918 package's particular libraries only and not the whole package.
1919
1920 Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a
1921 particular package: EXCLUDE_FROM_SHLIBS = "1"
1922
1923EXCLUDE_FROM_WORLD
1924 Directs BitBake to exclude a recipe from world builds (i.e.
1925 ``bitbake world``). During world builds, BitBake locates, parses and
1926 builds all recipes found in every layer exposed in the
1927 ``bblayers.conf`` configuration file.
1928
1929 To exclude a recipe from a world build using this variable, set the
1930 variable to "1" in the recipe.
1931
1932 .. note::
1933
1934 Recipes added to
1935 EXCLUDE_FROM_WORLD
1936 may still be built during a world build in order to satisfy
1937 dependencies of other recipes. Adding a recipe to
1938 EXCLUDE_FROM_WORLD
1939 only ensures that the recipe is not explicitly added to the list
1940 of build targets in a world build.
1941
1942EXTENDPE
1943 Used with file and pathnames to create a prefix for a recipe's
1944 version based on the recipe's ```PE`` <#var-PE>`__ value. If ``PE``
1945 is set and greater than zero for a recipe, ``EXTENDPE`` becomes that
1946 value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1_").
1947 If a recipe's ``PE`` is not set (the default) or is equal to zero,
1948 ``EXTENDPE`` becomes "".
1949
1950 See the ```STAMP`` <#var-STAMP>`__ variable for an example.
1951
1952EXTENDPKGV
1953 The full package version specification as it appears on the final
1954 packages produced by a recipe. The variable's value is normally used
1955 to fix a runtime dependency to the exact same version of another
1956 package in the same recipe: RDEPENDS_${PN}-additional-module = "${PN}
1957 (= ${EXTENDPKGV})"
1958
1959 The dependency relationships are intended to force the package
1960 manager to upgrade these types of packages in lock-step.
1961
1962EXTERNAL_KERNEL_TOOLS
1963 When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these
1964 tools are not in the source tree.
1965
1966 When kernel tools are available in the tree, they are preferred over
1967 any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS``
1968 variable tells the OpenEmbedded build system to prefer the installed
1969 external tools. See the
1970 ```kernel-yocto`` <#ref-classes-kernel-yocto>`__ class in
1971 ``meta/classes`` to see how the variable is used.
1972
1973EXTERNALSRC
1974 When inheriting the ```externalsrc`` <#ref-classes-externalsrc>`__
1975 class, this variable points to the source tree, which is outside of
1976 the OpenEmbedded build system. When set, this variable sets the
1977 ```S`` <#var-S>`__ variable, which is what the OpenEmbedded build
1978 system uses to locate unpacked recipe source code.
1979
1980 For more information on ``externalsrc.bbclass``, see the
1981 "```externalsrc.bbclass`` <#ref-classes-externalsrc>`__" section. You
1982 can also find information on how to use this variable in the
1983 "`Building Software from an External
1984 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
1985 section in the Yocto Project Development Tasks Manual.
1986
1987EXTERNALSRC_BUILD
1988 When inheriting the ```externalsrc`` <#ref-classes-externalsrc>`__
1989 class, this variable points to the directory in which the recipe's
1990 source code is built, which is outside of the OpenEmbedded build
1991 system. When set, this variable sets the ```B`` <#var-B>`__ variable,
1992 which is what the OpenEmbedded build system uses to locate the Build
1993 Directory.
1994
1995 For more information on ``externalsrc.bbclass``, see the
1996 "```externalsrc.bbclass`` <#ref-classes-externalsrc>`__" section. You
1997 can also find information on how to use this variable in the
1998 "`Building Software from an External
1999 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
2000 section in the Yocto Project Development Tasks Manual.
2001
2002EXTRA_AUTORECONF
2003 For recipes inheriting the ```autotools`` <#ref-classes-autotools>`__
2004 class, you can use ``EXTRA_AUTORECONF`` to specify extra options to
2005 pass to the ``autoreconf`` command that is executed during the
2006 ```do_configure`` <#ref-tasks-configure>`__ task.
2007
2008 The default value is "--exclude=autopoint".
2009
2010EXTRA_IMAGE_FEATURES
2011 A list of additional features to include in an image. When listing
2012 more than one feature, separate them with a space.
2013
2014 Typically, you configure this variable in your ``local.conf`` file,
2015 which is found in the `Build Directory <#build-directory>`__.
2016 Although you can use this variable from within a recipe, best
2017 practices dictate that you do not.
2018
2019 .. note::
2020
2021 To enable primary features from within the image recipe, use the
2022 IMAGE_FEATURES
2023 variable. 1655 variable.
2024 1656
2025 Here are some examples of features you can add: "dbg-pkgs" - Adds 1657 DISTRO
2026 -dbg packages for all installed packages including symbol information 1658 The short name of the distribution. For information on the long name
2027 for debugging and profiling. "debug-tweaks" - Makes an image suitable 1659 of the distribution, see the :term:`DISTRO_NAME`
2028 for debugging. For example, allows root logins without passwords and
2029 enables post-installation logging. See the 'allow-empty-password' and
2030 'post-install-logging' features in the "`Image
2031 Features <#ref-features-image>`__" section for more information.
2032 "dev-pkgs" - Adds -dev packages for all installed packages. This is
2033 useful if you want to develop against the libraries in the image.
2034 "read-only-rootfs" - Creates an image whose root filesystem is
2035 read-only. See the "`Creating a Read-Only Root
2036 Filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__"
2037 section in the Yocto Project Development Tasks Manual for more
2038 information "tools-debug" - Adds debugging tools such as gdb and
2039 strace. "tools-sdk" - Adds development tools such as gcc, make,
2040 pkgconfig and so forth. "tools-testapps" - Adds useful testing tools
2041 such as ts_print, aplay, arecord and so forth.
2042
2043 For a complete list of image features that ships with the Yocto
2044 Project, see the "`Image Features <#ref-features-image>`__" section.
2045
2046 For an example that shows how to customize your image by using this
2047 variable, see the "`Customizing Images Using Custom
2048 ``IMAGE_FEATURES`` and
2049 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__"
2050 section in the Yocto Project Development Tasks Manual.
2051
2052EXTRA_IMAGECMD
2053 Specifies additional options for the image creation command that has
2054 been specified in ```IMAGE_CMD`` <#var-IMAGE_CMD>`__. When setting
2055 this variable, use an override for the associated image type. Here is
2056 an example: EXTRA_IMAGECMD_ext3 ?= "-i 4096"
2057
2058EXTRA_IMAGEDEPENDS
2059 A list of recipes to build that do not provide packages for
2060 installing into the root filesystem.
2061
2062 Sometimes a recipe is required to build the final image but is not
2063 needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS``
2064 variable to list these recipes and thus specify the dependencies. A
2065 typical example is a required bootloader in a machine configuration.
2066
2067 .. note::
2068
2069 To add packages to the root filesystem, see the various
2070 \*
2071 RDEPENDS
2072 and
2073 \*
2074 RRECOMMENDS
2075 variables.
2076
2077EXTRANATIVEPATH
2078 A list of subdirectories of
2079 ``${``\ ```STAGING_BINDIR_NATIVE`` <#var-STAGING_BINDIR_NATIVE>`__\ ``}``
2080 added to the beginning of the environment variable ``PATH``. As an
2081 example, the following prepends
2082 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2083 ``PATH``: EXTRANATIVEPATH = "foo bar"
2084
2085EXTRA_OECMAKE
2086 Additional `CMake <https://cmake.org/overview/>`__ options. See the
2087 ```cmake`` <#ref-classes-cmake>`__ class for additional information.
2088
2089EXTRA_OECONF
2090 Additional ``configure`` script options. See
2091 ```PACKAGECONFIG_CONFARGS`` <#var-PACKAGECONFIG_CONFARGS>`__ for
2092 additional information on passing configure script options.
2093
2094EXTRA_OEMAKE
2095 Additional GNU ``make`` options.
2096
2097 Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the
2098 variable to specify any required GNU options.
2099
2100 ```PARALLEL_MAKE`` <#var-PARALLEL_MAKE>`__ and
2101 ```PARALLEL_MAKEINST`` <#var-PARALLEL_MAKEINST>`__ also make use of
2102 ``EXTRA_OEMAKE`` to pass the required flags.
2103
2104EXTRA_OESCONS
2105 When inheriting the ```scons`` <#ref-classes-scons>`__ class, this
2106 variable specifies additional configuration options you want to pass
2107 to the ``scons`` command line.
2108
2109EXTRA_USERS_PARAMS
2110 When inheriting the ```extrausers`` <#ref-classes-extrausers>`__
2111 class, this variable provides image level user and group operations.
2112 This is a more global method of providing user and group
2113 configuration as compared to using the
2114 ```useradd`` <#ref-classes-useradd>`__ class, which ties user and
2115 group configurations to a specific recipe.
2116
2117 The set list of commands you can configure using the
2118 ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These
2119 commands map to the normal Unix commands of the same names: #
2120 EXTRA_USERS_PARAMS = "\\ # useradd -p '' tester; \\ # groupadd
2121 developers; \\ # userdel nobody; \\ # groupdel -g video; \\ #
2122 groupmod -g 1020 developers; \\ # usermod -s /bin/sh tester; \\ # "
2123
2124FEATURE_PACKAGES
2125 Defines one or more packages to include in an image when a specific
2126 item is included in ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__.
2127 When setting the value, ``FEATURE_PACKAGES`` should have the name of
2128 the feature item as an override. Here is an example:
2129 FEATURE_PACKAGES_widget = "package1 package2"
2130
2131 In this example, if "widget" were added to ``IMAGE_FEATURES``,
2132 package1 and package2 would be included in the image.
2133
2134 .. note::
2135
2136 Packages installed by features defined through
2137 FEATURE_PACKAGES
2138 are often package groups. While similarly named, you should not
2139 confuse the
2140 FEATURE_PACKAGES
2141 variable with package groups, which are discussed elsewhere in the
2142 documentation.
2143
2144FEED_DEPLOYDIR_BASE_URI
2145 Points to the base URL of the server and location within the
2146 document-root that provides the metadata and packages required by
2147 OPKG to support runtime package management of IPK packages. You set
2148 this variable in your ``local.conf`` file.
2149
2150 Consider the following example: FEED_DEPLOYDIR_BASE_URI =
2151 "http://192.168.7.1/BOARD-dir" This example assumes you are serving
2152 your packages over HTTP and your databases are located in a directory
2153 named ``BOARD-dir``, which is underneath your HTTP server's
2154 document-root. In this case, the OpenEmbedded build system generates
2155 a set of configuration files for you in your target that work with
2156 the feed.
2157
2158FILES
2159 The list of files and directories that are placed in a package. The
2160 ```PACKAGES`` <#var-PACKAGES>`__ variable lists the packages
2161 generated by a recipe.
2162
2163 To use the ``FILES`` variable, provide a package name override that
2164 identifies the resulting package. Then, provide a space-separated
2165 list of files or paths that identify the files you want included as
2166 part of the resulting package. Here is an example: FILES_${PN} +=
2167 "${bindir}/mydir1 ${bindir}/mydir2/myfile"
2168
2169 .. note::
2170
2171 - When specifying files or paths, you can pattern match using
2172 Python's
2173 ```glob`` <https://docs.python.org/2/library/glob.html>`__
2174 syntax. For details on the syntax, see the documentation by
2175 following the previous link.
2176
2177 - When specifying paths as part of the ``FILES`` variable, it is
2178 good practice to use appropriate path variables. For example,
2179 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2180 rather than ``/usr/bin``. You can find a list of these
2181 variables at the top of the ``meta/conf/bitbake.conf`` file in
2182 the `Source Directory <#source-directory>`__. You will also
2183 find the default values of the various ``FILES_*`` variables in
2184 this file.
2185
2186 If some of the files you provide with the ``FILES`` variable are
2187 editable and you know they should not be overwritten during the
2188 package update process by the Package Management System (PMS), you
2189 can identify these files so that the PMS will not overwrite them. See
2190 the ```CONFFILES`` <#var-CONFFILES>`__ variable for information on
2191 how to identify these files to the PMS.
2192
2193FILES_SOLIBSDEV
2194 Defines the file specification to match
2195 ```SOLIBSDEV`` <#var-SOLIBSDEV>`__. In other words,
2196 ``FILES_SOLIBSDEV`` defines the full path name of the development
2197 symbolic link (symlink) for shared libraries on the target platform.
2198
2199 The following statement from the ``bitbake.conf`` shows how it is
2200 set: FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV}
2201 ${libdir}/lib*${SOLIBSDEV}"
2202
2203FILESEXTRAPATHS
2204 Extends the search path the OpenEmbedded build system uses when
2205 looking for files and patches as it processes recipes and append
2206 files. The default directories BitBake uses when it processes recipes
2207 are initially defined by the ```FILESPATH`` <#var-FILESPATH>`__
2208 variable. You can extend ``FILESPATH`` variable by using
2209 ``FILESEXTRAPATHS``.
2210
2211 Best practices dictate that you accomplish this by using
2212 ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you
2213 prepend paths as follows: FILESEXTRAPATHS_prepend :=
2214 "${THISDIR}/${PN}:" In the above example, the build system first
2215 looks for files in a directory that has the same name as the
2216 corresponding append file.
2217
2218 .. note::
2219
2220 When extending ``FILESEXTRAPATHS``, be sure to use the immediate
2221 expansion (``:=``) operator. Immediate expansion makes sure that
2222 BitBake evaluates ```THISDIR`` <#var-THISDIR>`__ at the time the
2223 directive is encountered rather than at some later time when
2224 expansion might result in a directory that does not contain the
2225 files you need.
2226
2227 Also, include the trailing separating colon character if you are
2228 prepending. The trailing colon character is necessary because you
2229 are directing BitBake to extend the path by prepending directories
2230 to the search path.
2231
2232 Here is another common use: FILESEXTRAPATHS_prepend :=
2233 "${THISDIR}/files:" In this example, the build system extends the
2234 ``FILESPATH`` variable to include a directory named ``files`` that is
2235 in the same directory as the corresponding append file.
2236
2237 This next example specifically adds three paths:
2238 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2239
2240 A final example shows how you can extend the search path and include
2241 a ```MACHINE`` <#var-MACHINE>`__-specific override, which is useful
2242 in a BSP layer: FILESEXTRAPATHS_prepend_intel-x86-common :=
2243 "${THISDIR}/${PN}:" The previous statement appears in the
2244 ``linux-yocto-dev.bbappend`` file, which is found in the Yocto
2245 Project `Source
2246 Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ in
2247 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2248 override is a special ```PACKAGE_ARCH`` <#var-PACKAGE_ARCH>`__
2249 definition for multiple ``meta-intel`` machines.
2250
2251 .. note::
2252
2253 For a layer that supports a single BSP, the override could just be
2254 the value of
2255 MACHINE
2256 .
2257
2258 By prepending paths in ``.bbappend`` files, you allow multiple append
2259 files that reside in different layers but are used for the same
2260 recipe to correctly extend the path.
2261
2262FILESOVERRIDES
2263 A subset of ```OVERRIDES`` <#var-OVERRIDES>`__ used by the
2264 OpenEmbedded build system for creating
2265 ```FILESPATH`` <#var-FILESPATH>`__. The ``FILESOVERRIDES`` variable
2266 uses overrides to automatically extend the
2267 ```FILESPATH`` <#var-FILESPATH>`__ variable. For an example of how
2268 that works, see the ```FILESPATH`` <#var-FILESPATH>`__ variable
2269 description. Additionally, you find more information on how overrides
2270 are handled in the "`Conditional Syntax
2271 (Overrides) <&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides>`__"
2272 section of the BitBake User Manual.
2273
2274 By default, the ``FILESOVERRIDES`` variable is defined as:
2275 FILESOVERRIDES =
2276 "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2277
2278 .. note::
2279
2280 Do not hand-edit the
2281 FILESOVERRIDES
2282 variable. The values match up with expected overrides and are used
2283 in an expected manner by the build system.
2284
2285FILESPATH
2286 The default set of directories the OpenEmbedded build system uses
2287 when searching for patches and files.
2288
2289 During the build process, BitBake searches each directory in
2290 ``FILESPATH`` in the specified order when looking for files and
2291 patches specified by each ``file://`` URI in a recipe's
2292 ```SRC_URI`` <#var-SRC_URI>`__ statements.
2293
2294 The default value for the ``FILESPATH`` variable is defined in the
2295 ``base.bbclass`` class found in ``meta/classes`` in the `Source
2296 Directory <#source-directory>`__: FILESPATH =
2297 "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \\
2298 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" The
2299 ``FILESPATH`` variable is automatically extended using the overrides
2300 from the ```FILESOVERRIDES`` <#var-FILESOVERRIDES>`__ variable.
2301
2302 .. note::
2303
2304 - Do not hand-edit the ``FILESPATH`` variable. If you want the
2305 build system to look in directories other than the defaults,
2306 extend the ``FILESPATH`` variable by using the
2307 ```FILESEXTRAPATHS`` <#var-FILESEXTRAPATHS>`__ variable.
2308
2309 - Be aware that the default ``FILESPATH`` directories do not map
2310 to directories in custom layers where append files
2311 (``.bbappend``) are used. If you want the build system to find
2312 patches or files that reside with your append files, you need
2313 to extend the ``FILESPATH`` variable by using the
2314 ``FILESEXTRAPATHS`` variable.
2315
2316 You can take advantage of this searching behavior in useful ways. For
2317 example, consider a case where the following directory structure
2318 exists for general and machine-specific configurations:
2319 files/defconfig files/MACHINEA/defconfig files/MACHINEB/defconfig
2320 Also in the example, the ``SRC_URI`` statement contains
2321 "file://defconfig". Given this scenario, you can set
2322 ```MACHINE`` <#var-MACHINE>`__ to "MACHINEA" and cause the build
2323 system to use files from ``files/MACHINEA``. Set ``MACHINE`` to
2324 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2325 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2326 build system uses files from ``files/defconfig``.
2327
2328 You can find out more about the patching process in the
2329 "`Patching <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__" section
2330 in the Yocto Project Overview and Concepts Manual and the "`Patching
2331 Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in
2332 the Yocto Project Development Tasks Manual. See the
2333 ```do_patch`` <#ref-tasks-patch>`__ task as well.
2334
2335FILESYSTEM_PERMS_TABLES
2336 Allows you to define your own file permissions settings table as part
2337 of your configuration for the packaging process. For example, suppose
2338 you need a consistent set of custom permissions for a set of groups
2339 and users across an entire work project. It is best to do this in the
2340 packages themselves but this is not always possible.
2341
2342 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2343 which is located in the ``meta/files`` folder in the `Source
2344 Directory <#source-directory>`__. If you create your own file
2345 permissions setting table, you should place it in your layer or the
2346 distro's layer.
2347
2348 You define the ``FILESYSTEM_PERMS_TABLES`` variable in the
2349 ``conf/local.conf`` file, which is found in the `Build
2350 Directory <#build-directory>`__, to point to your custom
2351 ``fs-perms.txt``. You can specify more than a single file permissions
2352 setting table. The paths you specify to these files must be defined
2353 within the ```BBPATH`` <#var-BBPATH>`__ variable.
2354
2355 For guidance on how to create your own file permissions settings
2356 table file, examine the existing ``fs-perms.txt``.
2357
2358FIT_HASH_ALG
2359 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
2360
2361FIT_SIGN_ALG</glossterm>
2362 Specifies the signature algorithm used in creating the FIT Image.
2363 For e.g. rsa2048.
2364
2365FONT_EXTRA_RDEPENDS
2366 When inheriting the ```fontcache`` <#ref-classes-fontcache>`__ class,
2367 this variable specifies the runtime dependencies for font packages.
2368 By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils".
2369
2370FONT_PACKAGES
2371 When inheriting the ```fontcache`` <#ref-classes-fontcache>`__ class,
2372 this variable identifies packages containing font files that need to
2373 be cached by Fontconfig. By default, the ``fontcache`` class assumes
2374 that fonts are in the recipe's main package (i.e.
2375 ``${``\ ```PN`` <#var-PN>`__\ ``}``). Use this variable if fonts you
2376 need are in a package other than that main package.
2377
2378FORCE_RO_REMOVE
2379 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
2380 during the generation of the root filesystem.
2381
2382 Set the variable to "1" to force the removal of these packages.
2383
2384FULL_OPTIMIZATION
2385 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when
2386 compiling an optimized system. This variable defaults to "-O2 -pipe
2387 ${DEBUG_FLAGS}".
2388
2389GCCPIE
2390 Enables Position Independent Executables (PIE) within the GNU C
2391 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
2392 Programming (ROP) attacks much more difficult to execute.
2393
2394 By default the ``security_flags.inc`` file enables PIE by setting the
2395 variable as follows: GCCPIE ?= "--enable-default-pie"
2396
2397GCCVERSION
2398 Specifies the default version of the GNU C Compiler (GCC) used for
2399 compilation. By default, ``GCCVERSION`` is set to "8.x" in the
2400 ``meta/conf/distro/include/tcmode-default.inc`` include file:
2401 GCCVERSION ?= "8.%" You can override this value by setting it in a
2402 configuration file such as the ``local.conf``.
2403
2404GDB
2405 The minimal command and arguments to run the GNU Debugger.
2406
2407GITDIR
2408 The directory in which a local copy of a Git repository is stored
2409 when it is cloned.
2410
2411GLIBC_GENERATE_LOCALES
2412 Specifies the list of GLIBC locales to generate should you not wish
2413 to generate all LIBC locals, which can be time consuming.
2414
2415 .. note::
2416
2417 If you specifically remove the locale
2418 en_US.UTF-8
2419 , you must set
2420 IMAGE_LINGUAS
2421 appropriately.
2422
2423 You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file.
2424 By default, all locales are generated. GLIBC_GENERATE_LOCALES =
2425 "en_GB.UTF-8 en_US.UTF-8"
2426
2427GROUPADD_PARAM
2428 When inheriting the ```useradd`` <#ref-classes-useradd>`__ class,
2429 this variable specifies for a package what parameters should be
2430 passed to the ``groupadd`` command if you wish to add a group to the
2431 system when the package is installed.
2432
2433 Here is an example from the ``dbus`` recipe: GROUPADD_PARAM_${PN} =
2434 "-r netdev" For information on the standard Linux shell command
2435 ``groupadd``, see ` <http://linux.die.net/man/8/groupadd>`__.
2436
2437GROUPMEMS_PARAM
2438 When inheriting the ```useradd`` <#ref-classes-useradd>`__ class,
2439 this variable specifies for a package what parameters should be
2440 passed to the ``groupmems`` command if you wish to modify the members
2441 of a group when the package is installed.
2442
2443 For information on the standard Linux shell command ``groupmems``,
2444 see ` <http://linux.die.net/man/8/groupmems>`__.
2445
2446GRUB_GFXSERIAL
2447 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
2448 and serial in the boot menu. Set this variable to "1" in your
2449 ``local.conf`` or distribution configuration file to enable graphics
2450 and serial in the menu.
2451
2452 See the ```grub-efi`` <#ref-classes-grub-efi>`__ class for more
2453 information on how this variable is used.
2454
2455GRUB_OPTS
2456 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
2457 configuration. Use a semi-colon character (``;``) to separate
2458 multiple options.
2459
2460 The ``GRUB_OPTS`` variable is optional. See the
2461 ```grub-efi`` <#ref-classes-grub-efi>`__ class for more information
2462 on how this variable is used.
2463
2464GRUB_TIMEOUT
2465 Specifies the timeout before executing the default ``LABEL`` in the
2466 GNU GRand Unified Bootloader (GRUB).
2467
2468 The ``GRUB_TIMEOUT`` variable is optional. See the
2469 ```grub-efi`` <#ref-classes-grub-efi>`__ class for more information
2470 on how this variable is used.
2471
2472GTKIMMODULES_PACKAGES
2473 When inheriting the
2474 ```gtk-immodules-cache`` <#ref-classes-gtk-immodules-cache>`__ class,
2475 this variable specifies the packages that contain the GTK+ input
2476 method modules being installed when the modules are in packages other
2477 than the main package.
2478
2479HOMEPAGE
2480 Website where more information about the software the recipe is
2481 building can be found.
2482
2483HOST_ARCH
2484 The name of the target architecture, which is normally the same as
2485 ```TARGET_ARCH`` <#var-TARGET_ARCH>`__. The OpenEmbedded build system
2486 supports many architectures. Here is an example list of architectures
2487 supported. This list is by no means complete as the architecture is
2488 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel
2489
2490HOST_CC_ARCH
2491 Specifies architecture-specific compiler flags that are passed to the
2492 C compiler.
2493
2494 Default initialization for ``HOST_CC_ARCH`` varies depending on what
2495 is being built:
2496
2497 - ```TARGET_CC_ARCH`` <#var-TARGET_CC_ARCH>`__ when building for the
2498 target
2499
2500 - ``BUILD_CC_ARCH`` when building for the build host (i.e.
2501 ``-native``)
2502
2503 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
2504 ``nativesdk-``)
2505
2506HOST_OS
2507 Specifies the name of the target operating system, which is normally
2508 the same as the ```TARGET_OS`` <#var-TARGET_OS>`__. The variable can
2509 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
2510 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
2511 "linux-musleabi" values possible.
2512
2513HOST_PREFIX
2514 Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX``
2515 is normally the same as ```TARGET_PREFIX`` <#var-TARGET_PREFIX>`__.
2516
2517HOST_SYS
2518 Specifies the system, including the architecture and the operating
2519 system, for which the build is occurring in the context of the
2520 current recipe.
2521
2522 The OpenEmbedded build system automatically sets this variable based
2523 on ```HOST_ARCH`` <#var-HOST_ARCH>`__,
2524 ```HOST_VENDOR`` <#var-HOST_VENDOR>`__, and
2525 ```HOST_OS`` <#var-HOST_OS>`__ variables.
2526
2527 .. note::
2528
2529 You do not need to set the variable yourself.
2530
2531 Consider these two examples:
2532
2533 - Given a native recipe on a 32-bit x86 machine running Linux, the
2534 value is "i686-linux".
2535
2536 - Given a recipe being built for a little-endian MIPS target running
2537 Linux, the value might be "mipsel-linux".
2538
2539HOSTTOOLS
2540 A space-separated list (filter) of tools on the build host that
2541 should be allowed to be called from within build tasks. Using this
2542 filter helps reduce the possibility of host contamination. If a tool
2543 specified in the value of ``HOSTTOOLS`` is not found on the build
2544 host, the OpenEmbedded build system produces an error and the build
2545 is not started.
2546
2547 For additional information, see
2548 ```HOSTTOOLS_NONFATAL`` <#var-HOSTTOOLS_NONFATAL>`__.
2549
2550HOSTTOOLS_NONFATAL
2551 A space-separated list (filter) of tools on the build host that
2552 should be allowed to be called from within build tasks. Using this
2553 filter helps reduce the possibility of host contamination. Unlike
2554 ```HOSTTOOLS`` <#var-HOSTTOOLS>`__, the OpenEmbedded build system
2555 does not produce an error if a tool specified in the value of
2556 ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can
2557 use ``HOSTTOOLS_NONFATAL`` to filter optional host tools.
2558
2559HOST_VENDOR
2560 Specifies the name of the vendor. ``HOST_VENDOR`` is normally the
2561 same as ```TARGET_VENDOR`` <#var-TARGET_VENDOR>`__.
2562
2563ICECC_DISABLED
2564 Disables or enables the ``icecc`` (Icecream) function. For more
2565 information on this function and best practices for using this
2566 variable, see the "```icecc.bbclass`` <#ref-classes-icecc>`__"
2567 section.
2568
2569 Setting this variable to "1" in your ``local.conf`` disables the
2570 function: ICECC_DISABLED ??= "1" To enable the function, set the
2571 variable as follows: ICECC_DISABLED = ""
2572
2573ICECC_ENV_EXEC
2574 Points to the ``icecc-create-env`` script that you provide. This
2575 variable is used by the ```icecc`` <#ref-classes-icecc>`__ class. You
2576 set this variable in your ``local.conf`` file.
2577
2578 If you do not point to a script that you provide, the OpenEmbedded
2579 build system uses the default script provided by the
2580 ``icecc-create-env.bb`` recipe, which is a modified version and not
2581 the one that comes with ``icecc``.
2582
2583ICECC_PARALLEL_MAKE
2584 Extra options passed to the ``make`` command during the
2585 ```do_compile`` <#ref-tasks-compile>`__ task that specify parallel
2586 compilation. This variable usually takes the form of "-j x", where x
2587 represents the maximum number of parallel threads ``make`` can run.
2588
2589 .. note::
2590
2591 The options passed affect builds on all enabled machines on the
2592 network, which are machines running the
2593 iceccd
2594 daemon.
2595
2596 If your enabled machines support multiple cores, coming up with the
2597 maximum number of parallel threads that gives you the best
2598 performance could take some experimentation since machine speed,
2599 network lag, available memory, and existing machine loads can all
2600 affect build time. Consequently, unlike the
2601 ```PARALLEL_MAKE`` <#var-PARALLEL_MAKE>`__ variable, there is no
2602 rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal
2603 performance.
2604
2605 If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not
2606 use it (i.e. the system does not detect and assign the number of
2607 cores as is done with ``PARALLEL_MAKE``).
2608
2609ICECC_PATH
2610 The location of the ``icecc`` binary. You can set this variable in
2611 your ``local.conf`` file. If your ``local.conf`` file does not define
2612 this variable, the ```icecc`` <#ref-classes-icecc>`__ class attempts
2613 to define it by locating ``icecc`` using ``which``.
2614
2615ICECC_USER_CLASS_BL
2616 Identifies user classes that you do not want the Icecream distributed
2617 compile support to consider. This variable is used by the
2618 ```icecc`` <#ref-classes-icecc>`__ class. You set this variable in
2619 your ``local.conf`` file.
2620
2621 When you list classes using this variable, you are "blacklisting"
2622 them from distributed compilation across remote hosts. Any classes
2623 you list will be distributed and compiled locally.
2624
2625ICECC_USER_PACKAGE_BL
2626 Identifies user recipes that you do not want the Icecream distributed
2627 compile support to consider. This variable is used by the
2628 ```icecc`` <#ref-classes-icecc>`__ class. You set this variable in
2629 your ``local.conf`` file.
2630
2631 When you list packages using this variable, you are "blacklisting"
2632 them from distributed compilation across remote hosts. Any packages
2633 you list will be distributed and compiled locally.
2634
2635ICECC_USER_PACKAGE_WL
2636 Identifies user recipes that use an empty
2637 ```PARALLEL_MAKE`` <#var-PARALLEL_MAKE>`__ variable that you want to
2638 force remote distributed compilation on using the Icecream
2639 distributed compile support. This variable is used by the
2640 ```icecc`` <#ref-classes-icecc>`__ class. You set this variable in
2641 your ``local.conf`` file.
2642
2643IMAGE_BASENAME
2644 The base name of image output files. This variable defaults to the
2645 recipe name (``${``\ ```PN`` <#var-PN>`__\ ``}``).
2646
2647IMAGE_BOOT_FILES
2648 A space-separated list of files installed into the boot partition
2649 when preparing an image using the Wic tool with the
2650 ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default,
2651 the files are
2652 installed under the same name as the source files. To change the
2653 installed name, separate it from the original name with a semi-colon
2654 (;). Source files need to be located in
2655 ```DEPLOY_DIR_IMAGE`` <#var-DEPLOY_DIR_IMAGE>`__. Here are two
2656 examples: IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2657 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
2658
2659 Alternatively, source files can be picked up using a glob pattern. In
2660 this case, the destination file must have the same name as the base
2661 name of the source file path. To install files into a directory
2662 within the target location, pass its name after a semi-colon (;).
2663 Here are two examples: IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2664 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" The first example
2665 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
2666 into the root of the target partition. The second example installs
2667 the same files into a ``boot`` directory within the target partition.
2668
2669 You can find information on how to use the Wic tool in the "`Creating
2670 Partitioned Images Using
2671 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__"
2672 section of the Yocto Project Development Tasks Manual. Reference
2673 material for Wic is located in the "`OpenEmbedded Kickstart (.wks)
2674 Reference <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__" chapter.
2675
2676IMAGE_CLASSES
2677 A list of classes that all images should inherit. You typically use
2678 this variable to specify the list of classes that register the
2679 different types of images the OpenEmbedded build system creates.
2680
2681 The default value for ``IMAGE_CLASSES`` is ``image_types``. You can
2682 set this variable in your ``local.conf`` or in a distribution
2683 configuration file.
2684
2685 For more information, see ``meta/classes/image_types.bbclass`` in the
2686 `Source Directory <#source-directory>`__.
2687
2688IMAGE_CMD
2689 Specifies the command to create the image file for a specific image
2690 type, which corresponds to the value set set in
2691 ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__, (e.g. ``ext3``,
2692 ``btrfs``, and so forth). When setting this variable, you should use
2693 an override for the associated type. Here is an example:
2694 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \\ --faketime
2695 --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \\
2696 ${EXTRA_IMAGECMD}"
2697
2698 You typically do not need to set this variable unless you are adding
2699 support for a new image type. For more examples on how to set this
2700 variable, see the ```image_types`` <#ref-classes-image_types>`__
2701 class file, which is ``meta/classes/image_types.bbclass``.
2702
2703IMAGE_DEVICE_TABLES
2704 Specifies one or more files that contain custom device tables that
2705 are passed to the ``makedevs`` command as part of creating an image.
2706 These files list basic device nodes that should be created under
2707 ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set,
2708 ``files/device_table-minimal.txt`` is used, which is located by
2709 ```BBPATH`` <#var-BBPATH>`__. For details on how you should write
2710 device table files, see ``meta/files/device_table-minimal.txt`` as an
2711 example.
2712
2713IMAGE_FEATURES
2714 The primary list of features to include in an image. Typically, you
2715 configure this variable in an image recipe. Although you can use this
2716 variable from your ``local.conf`` file, which is found in the `Build
2717 Directory <#build-directory>`__, best practices dictate that you do
2718 not.
2719
2720 .. note::
2721
2722 To enable extra features from outside the image recipe, use the
2723 EXTRA_IMAGE_FEATURES
2724 variable. 1660 variable.
2725 1661
2726 For a list of image features that ships with the Yocto Project, see 1662 The ``DISTRO`` variable corresponds to a distribution configuration
2727 the "`Image Features <#ref-features-image>`__" section. 1663 file whose root name is the same as the variable's argument and whose
2728 1664 filename extension is ``.conf``. For example, the distribution
2729 For an example that shows how to customize your image by using this 1665 configuration file for the Poky distribution is named ``poky.conf``
2730 variable, see the "`Customizing Images Using Custom 1666 and resides in the ``meta-poky/conf/distro`` directory of the
2731 ``IMAGE_FEATURES`` and 1667 :term:`Source Directory`.
2732 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__" 1668
2733 section in the Yocto Project Development Tasks Manual. 1669 Within that ``poky.conf`` file, the ``DISTRO`` variable is set as
2734 1670 follows: DISTRO = "poky"
2735IMAGE_FSTYPES 1671
2736 Specifies the formats the OpenEmbedded build system uses during the 1672 Distribution configuration files are located in a ``conf/distro``
2737 build when creating the root filesystem. For example, setting 1673 directory within the :term:`Metadata` that contains the
2738 ``IMAGE_FSTYPES`` as follows causes the build system to create root 1674 distribution configuration. The value for ``DISTRO`` must not contain
2739 filesystems using two formats: ``.ext3`` and ``.tar.bz2``: 1675 spaces, and is typically all lower-case.
2740 IMAGE_FSTYPES = "ext3 tar.bz2" 1676
2741 1677 .. note::
2742 For the complete list of supported image formats from which you can 1678
2743 choose, see ```IMAGE_TYPES`` <#var-IMAGE_TYPES>`__. 1679 If the
2744 1680 DISTRO
2745 .. note:: 1681 variable is blank, a set of default configurations are used, which
2746 1682 are specified within
2747 - If an image recipe uses the "inherit image" line and you are 1683 meta/conf/distro/defaultsetup.conf
2748 setting ``IMAGE_FSTYPES`` inside the recipe, you must set 1684 also in the Source Directory.
2749 ``IMAGE_FSTYPES`` prior to using the "inherit image" line. 1685
2750 1686 DISTRO_CODENAME
2751 - Due to the way the OpenEmbedded build system processes this 1687 Specifies a codename for the distribution being built.
2752 variable, you cannot update its contents by using ``_append`` 1688
2753 or ``_prepend``. You must use the ``+=`` operator to add one or 1689 DISTRO_EXTRA_RDEPENDS
2754 more options to the ``IMAGE_FSTYPES`` variable. 1690 Specifies a list of distro-specific packages to add to all images.
2755 1691 This variable takes affect through ``packagegroup-base`` so the
2756IMAGE_INSTALL 1692 variable only really applies to the more full-featured images that
2757 Used by recipes to specify the packages to install into an image 1693 include ``packagegroup-base``. You can use this variable to keep
2758 through the ```image`` <#ref-classes-image>`__ class. Use the 1694 distro policy out of generic images. As with all other distro
2759 ``IMAGE_INSTALL`` variable with care to avoid ordering issues. 1695 variables, you set this variable in the distro ``.conf`` file.
2760 1696
2761 Image recipes set ``IMAGE_INSTALL`` to specify the packages to 1697 DISTRO_EXTRA_RRECOMMENDS
2762 install into an image through ``image.bbclass``. Additionally, 1698 Specifies a list of distro-specific packages to add to all images if
2763 "helper" classes such as the 1699 the packages exist. The packages might not exist or be empty (e.g.
2764 ```core-image`` <#ref-classes-core-image>`__ class exist that can 1700 kernel modules). The list of packages are automatically installed but
2765 take lists used with ``IMAGE_FEATURES`` and turn them into 1701 you can remove them.
2766 auto-generated entries in ``IMAGE_INSTALL`` in addition to its 1702
2767 default contents. 1703 DISTRO_FEATURES
2768 1704 The software support you want in your distribution for various
2769 When you use this variable, it is best to use it as follows: 1705 features. You define your distribution features in the distribution
2770 IMAGE_INSTALL_append = " package-name" Be sure to include the space 1706 configuration file.
2771 between the quotation character and the start of the package name or 1707
2772 names. 1708 In most cases, the presence or absence of a feature in
2773 1709 ``DISTRO_FEATURES`` is translated to the appropriate option supplied
2774 .. note:: 1710 to the configure script during the
2775 1711 :ref:`ref-tasks-configure` task for recipes that
2776 - When working with a 1712 optionally support the feature. For example, specifying "x11" in
2777 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ 1713 ``DISTRO_FEATURES``, causes every piece of software built for the
2778 image, do not use the ``IMAGE_INSTALL`` variable to specify 1714 target that can optionally support X11 to have its X11 support
2779 packages for installation. Instead, use the 1715 enabled.
2780 ```PACKAGE_INSTALL`` <#var-PACKAGE_INSTALL>`__ variable, which 1716
2781 allows the initial RAM filesystem (initramfs) recipe to use a 1717 Two more examples are Bluetooth and NFS support. For a more complete
2782 fixed set of packages and not be affected by ``IMAGE_INSTALL``. 1718 list of features that ships with the Yocto Project and that you can
2783 For information on creating an initramfs, see the "`Building an 1719 provide with this variable, see the "`Distro
2784 Initial RAM Filesystem (initramfs) 1720 Features <#ref-features-distro>`__" section.
2785 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" 1721
2786 section in the Yocto Project Development Tasks Manual. 1722 DISTRO_FEATURES_BACKFILL
2787 1723 Features to be added to ``DISTRO_FEATURES`` if not also present in
2788 - Using ``IMAGE_INSTALL`` with the 1724 ``DISTRO_FEATURES_BACKFILL_CONSIDERED``.
2789 ```+=`` <&YOCTO_DOCS_BB_URL;#appending-and-prepending>`__ 1725
2790 BitBake operator within the ``/conf/local.conf`` file or from 1726 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
2791 within an image recipe is not recommended. Use of this operator 1727 not intended to be user-configurable. It is best to just reference
2792 in these ways can cause ordering issues. Since 1728 the variable to see which distro features are being backfilled for
2793 ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default 1729 all distro configurations. See the "`Feature
2794 value using the 1730 Backfilling <#ref-features-backfill>`__" section for more
2795 ```?=`` <&YOCTO_DOCS_BB_URL;#setting-a-default-value>`__ 1731 information.
2796 operator, using a ``+=`` operation against ``IMAGE_INSTALL`` 1732
2797 results in unexpected behavior when used within 1733 DISTRO_FEATURES_BACKFILL_CONSIDERED
2798 ``conf/local.conf``. Furthermore, the same operation from 1734 Features from ``DISTRO_FEATURES_BACKFILL`` that should not be
2799 within an image recipe may or may not succeed depending on the 1735 backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See
2800 specific situation. In both these cases, the behavior is 1736 the "`Feature Backfilling <#ref-features-backfill>`__" section for
2801 contrary to how most users expect the ``+=`` operator to work. 1737 more information.
2802 1738
2803IMAGE_LINGUAS 1739 DISTRO_FEATURES_DEFAULT
2804 Specifies the list of locales to install into the image during the 1740 A convenience variable that gives you the default list of distro
2805 root filesystem construction process. The OpenEmbedded build system 1741 features with the exception of any features specific to the C library
2806 automatically splits locale files, which are used for localization, 1742 (``libc``).
2807 into separate packages. Setting the ``IMAGE_LINGUAS`` variable 1743
2808 ensures that any locale packages that correspond to packages already 1744 When creating a custom distribution, you might find it useful to be
2809 selected for installation into the image are also installed. Here is 1745 able to reuse the default
2810 an example: IMAGE_LINGUAS = "pt-br de-de" 1746 :term:`DISTRO_FEATURES` options without the
2811 1747 need to write out the full set. Here is an example that uses
2812 In this example, the build system ensures any Brazilian Portuguese 1748 ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file:
2813 and German locale files that correspond to packages in the image are 1749 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
2814 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as 1750
2815 ``*-locale-pt`` and ``*-locale-de``, since some software packages 1751 DISTRO_FEATURES_FILTER_NATIVE
2816 only provide locale files by language and not by country-specific 1752 Specifies a list of features that if present in the target
2817 language). 1753 :term:`DISTRO_FEATURES` value should be
2818 1754 included in ``DISTRO_FEATURES`` when building native recipes. This
2819 See the ```GLIBC_GENERATE_LOCALES`` <#var-GLIBC_GENERATE_LOCALES>`__ 1755 variable is used in addition to the features filtered using the
2820 variable for information on generating GLIBC locales. 1756 :term:`DISTRO_FEATURES_NATIVE`
2821 1757 variable.
2822IMAGE_MANIFEST 1758
2823 The manifest file for the image. This file lists all the installed 1759 DISTRO_FEATURES_FILTER_NATIVESDK
2824 packages that make up the image. The file contains package 1760 Specifies a list of features that if present in the target
2825 information on a line-per-package basis as follows: packagename 1761 :term:`DISTRO_FEATURES` value should be
2826 packagearch version 1762 included in ``DISTRO_FEATURES`` when building nativesdk recipes. This
2827 1763 variable is used in addition to the features filtered using the
2828 The ```image`` <#ref-classes-image>`__ class defines the manifest 1764 :term:`DISTRO_FEATURES_NATIVESDK`
2829 file as follows: IMAGE_MANIFEST = 1765 variable.
2830 "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" The location is 1766
2831 derived using the ```DEPLOY_DIR_IMAGE`` <#var-DEPLOY_DIR_IMAGE>`__ 1767 DISTRO_FEATURES_NATIVE
2832 and ```IMAGE_NAME`` <#var-IMAGE_NAME>`__ variables. You can find 1768 Specifies a list of features that should be included in
2833 information on how the image is created in the "`Image 1769 :term:`DISTRO_FEATURES` when building native
2834 Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__" 1770 recipes. This variable is used in addition to the features filtered
2835 section in the Yocto Project Overview and Concepts Manual. 1771 using the
2836 1772 :term:`DISTRO_FEATURES_FILTER_NATIVE`
2837IMAGE_NAME 1773 variable.
2838 The name of the output image files minus the extension. This variable 1774
2839 is derived using the ```IMAGE_BASENAME`` <#var-IMAGE_BASENAME>`__, 1775 DISTRO_FEATURES_NATIVESDK
2840 ```MACHINE`` <#var-MACHINE>`__, and ```DATETIME`` <#var-DATETIME>`__ 1776 Specifies a list of features that should be included in
2841 variables: IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" 1777 :term:`DISTRO_FEATURES` when building
2842 1778 nativesdk recipes. This variable is used in addition to the features
2843IMAGE_OVERHEAD_FACTOR 1779 filtered using the
2844 Defines a multiplier that the build system applies to the initial 1780 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
2845 image size for cases when the multiplier times the returned disk 1781 variable.
2846 usage value for the image is greater than the sum of 1782
2847 ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of 1783 DISTRO_NAME
2848 the multiplier applied to the initial image size creates free disk 1784 The long name of the distribution. For information on the short name
2849 space in the image as overhead. By default, the build process uses a 1785 of the distribution, see the :term:`DISTRO` variable.
2850 multiplier of 1.3 for this variable. This default value results in 1786
2851 30% free disk space added to the image when this method is used to 1787 The ``DISTRO_NAME`` variable corresponds to a distribution
2852 determine the final generated image size. You should be aware that 1788 configuration file whose root name is the same as the variable's
2853 post install scripts and the package management system uses disk 1789 argument and whose filename extension is ``.conf``. For example, the
2854 space inside this overhead area. Consequently, the multiplier does 1790 distribution configuration file for the Poky distribution is named
2855 not produce an image with all the theoretical free disk space. See 1791 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
2856 ``IMAGE_ROOTFS_SIZE`` for information on how the build system 1792 of the :term:`Source Directory`.
2857 determines the overall image size. 1793
2858 1794 Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set
2859 The default 30% free disk space typically gives the image enough room 1795 as follows: DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
2860 to boot and allows for basic post installs while still leaving a 1796
2861 small amount of free disk space. If 30% free space is inadequate, you 1797 Distribution configuration files are located in a ``conf/distro``
2862 can increase the default value. For example, the following setting 1798 directory within the :term:`Metadata` that contains the
2863 gives you 50% free space added to the image: IMAGE_OVERHEAD_FACTOR = 1799 distribution configuration.
2864 "1.5" 1800
2865 1801 .. note::
2866 Alternatively, you can ensure a specific amount of free disk space is 1802
2867 added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` 1803 If the
2868 variable. 1804 DISTRO_NAME
2869 1805 variable is blank, a set of default configurations are used, which
2870IMAGE_PKGTYPE 1806 are specified within
2871 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 1807 meta/conf/distro/defaultsetup.conf
2872 OpenEmbedded build system. The variable is defined appropriately by 1808 also in the Source Directory.
2873 the ```package_deb`` <#ref-classes-package_deb>`__, 1809
2874 ```package_rpm`` <#ref-classes-package_rpm>`__, 1810 DISTRO_VERSION
2875 ```package_ipk`` <#ref-classes-package_ipk>`__, or 1811 The version of the distribution.
2876 ```package_tar`` <#ref-classes-package_tar>`__ class. 1812
2877 1813 DISTROOVERRIDES
2878 .. note:: 1814 A colon-separated list of overrides specific to the current
2879 1815 distribution. By default, this list includes the value of
2880 The 1816 :term:`DISTRO`.
2881 package_tar 1817
2882 class is broken and is not supported. It is recommended that you 1818 You can extend ``DISTROOVERRIDES`` to add extra overrides that should
2883 do not use it. 1819 apply to the distribution.
2884 1820
2885 The ```populate_sdk_*`` <#ref-classes-populate-sdk-*>`__ and 1821 The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it
2886 ```image`` <#ref-classes-image>`__ classes use the ``IMAGE_PKGTYPE`` 1822 is included in the default value of
2887 for packaging up images and SDKs. 1823 :term:`OVERRIDES`.
2888 1824
2889 You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the 1825 DL_DIR
2890 variable is set indirectly through the appropriate 1826 The central download directory used by the build process to store
2891 ```package_*`` <#ref-classes-package>`__ class using the 1827 downloads. By default, ``DL_DIR`` gets files suitable for mirroring
2892 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__ variable. The 1828 for everything except Git repositories. If you want tarballs of Git
2893 OpenEmbedded build system uses the first package type (e.g. DEB, RPM, 1829 repositories, use the
2894 or IPK) that appears with the variable 1830 :term:`BB_GENERATE_MIRROR_TARBALLS`
2895 1831 variable.
2896 .. note:: 1832
2897 1833 You can set this directory by defining the ``DL_DIR`` variable in the
2898 Files using the 1834 ``conf/local.conf`` file. This directory is self-maintaining and you
2899 .tar 1835 should not have to touch it. By default, the directory is
2900 format are never used as a substitute packaging format for DEB, 1836 ``downloads`` in the :term:`Build Directory`. #DL_DIR
2901 RPM, and IPK formatted files for your image or SDK. 1837 ?= "${TOPDIR}/downloads" To specify a different download directory,
2902 1838 simply remove the comment from the line and provide your directory.
2903IMAGE_POSTPROCESS_COMMAND 1839
2904 Specifies a list of functions to call once the OpenEmbedded build 1840 During a first build, the system downloads many different source code
2905 system creates the final image output files. You can specify 1841 tarballs from various upstream projects. Downloading can take a
2906 functions separated by semicolons: IMAGE_POSTPROCESS_COMMAND += 1842 while, particularly if your network connection is slow. Tarballs are
2907 "function; ... " 1843 all stored in the directory defined by ``DL_DIR`` and the build
2908 1844 system looks there first to find source tarballs.
2909 If you need to pass the root filesystem path to a command within the 1845
2910 function, you can use ``${IMAGE_ROOTFS}``, which points to the 1846 .. note::
2911 directory that becomes the root filesystem image. See the 1847
2912 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more 1848 When wiping and rebuilding, you can preserve this directory to
2913 information. 1849 speed up this part of subsequent builds.
2914 1850
2915IMAGE_PREPROCESS_COMMAND 1851 You can safely share this directory between multiple builds on the
2916 Specifies a list of functions to call before the OpenEmbedded build 1852 same development machine. For additional information on how the build
2917 system creates the final image output files. You can specify 1853 process gets source files when working behind a firewall or proxy
2918 functions separated by semicolons: IMAGE_PREPROCESS_COMMAND += 1854 server, see this specific question in the
2919 "function; ... " 1855 "`FAQ <#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server>`__"
2920 1856 chapter. You can also refer to the
2921 If you need to pass the root filesystem path to a command within the 1857 ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`"
2922 function, you can use ``${IMAGE_ROOTFS}``, which points to the 1858 Wiki page.
2923 directory that becomes the root filesystem image. See the 1859
2924 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more 1860 DOC_COMPRESS
2925 information. 1861 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>`
2926 1862 class, this variable sets the compression policy used when the
2927IMAGE_ROOTFS 1863 OpenEmbedded build system compresses man pages and info pages. By
2928 The location of the root filesystem while it is under construction 1864 default, the compression method used is gz (gzip). Other policies
2929 (i.e. during the ```do_rootfs`` <#ref-tasks-rootfs>`__ task). This 1865 available are xz and bz2.
2930 variable is not configurable. Do not change it. 1866
2931 1867 For information on policies and on how to use this variable, see the
2932IMAGE_ROOTFS_ALIGNMENT 1868 comments in the ``meta/classes/compress_doc.bbclass`` file.
2933 Specifies the alignment for the output image file in Kbytes. If the 1869
2934 size of the image is not a multiple of this value, then the size is 1870 EFI_PROVIDER
2935 rounded up to the nearest multiple of the value. The default value is 1871 When building bootable images (i.e. where ``hddimg``, ``iso``, or
2936 "1". See ```IMAGE_ROOTFS_SIZE`` <#var-IMAGE_ROOTFS_SIZE>`__ for 1872 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
2937 additional information. 1873 ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The
2938 1874 default is "grub-efi", but "systemd-boot" can be used instead.
2939IMAGE_ROOTFS_EXTRA_SPACE 1875
2940 Defines additional free disk space created in the image in Kbytes. By 1876 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and
2941 default, this variable is set to "0". This free disk space is added 1877 :ref:`image-live <ref-classes-image-live>` classes for more
2942 to the image after the build system determines the image size as 1878 information.
2943 described in ``IMAGE_ROOTFS_SIZE``. 1879
2944 1880 ENABLE_BINARY_LOCALE_GENERATION
2945 This variable is particularly useful when you want to ensure that a 1881 Variable that controls which locales for ``glibc`` are generated
2946 specific amount of free disk space is available on a device after an 1882 during the build (useful if the target device has 64Mbytes of RAM or
2947 image is installed and running. For example, to be sure 5 Gbytes of 1883 less).
2948 free disk space is available, set the variable as follows: 1884
2949 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 1885 ERR_REPORT_DIR
2950 1886 When used with the :ref:`report-error <ref-classes-report-error>`
2951 For example, the Yocto Project Build Appliance specifically requests 1887 class, specifies the path used for storing the debug files created by
2952 40 Gbytes of extra space with the line: IMAGE_ROOTFS_EXTRA_SPACE = 1888 the `error reporting
2953 "41943040" 1889 tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which
2954 1890 allows you to submit build errors you encounter to a central
2955IMAGE_ROOTFS_SIZE 1891 database. By default, the value of this variable is
2956 Defines the size in Kbytes for the generated image. The OpenEmbedded 1892 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
2957 build system determines the final size for the generated image using 1893
2958 an algorithm that takes into account the initial disk space used for 1894 You can set ``ERR_REPORT_DIR`` to the path you want the error
2959 the generated image, a requested size for the image, and requested 1895 reporting tool to store the debug files as follows in your
2960 additional free disk space to be added to the image. Programatically, 1896 ``local.conf`` file: ERR_REPORT_DIR = "path"
2961 the build system determines the final size of the generated image as 1897
2962 follows: if (image-du \* overhead) < rootfs-size: 1898 ERROR_QA
2963 internal-rootfs-size = rootfs-size + xspace else: 1899 Specifies the quality assurance checks whose failures are reported as
2964 internal-rootfs-size = (image-du \* overhead) + xspace where: 1900 errors by the OpenEmbedded build system. You set this variable in
2965 image-du = Returned value of the du command on the image. overhead = 1901 your distribution configuration file. For a list of the checks you
2966 IMAGE_OVERHEAD_FACTOR rootfs-size = IMAGE_ROOTFS_SIZE 1902 can control with this variable, see the
2967 internal-rootfs-size = Initial root filesystem size before any 1903 ":ref:`insane.bbclass <ref-classes-insane>`" section.
2968 modifications. xspace = IMAGE_ROOTFS_EXTRA_SPACE 1904
2969 1905 EXCLUDE_FROM_SHLIBS
2970 See the ```IMAGE_OVERHEAD_FACTOR`` <#var-IMAGE_OVERHEAD_FACTOR>`__ 1906 Triggers the OpenEmbedded build system's shared libraries resolver to
2971 and ```IMAGE_ROOTFS_EXTRA_SPACE`` <#var-IMAGE_ROOTFS_EXTRA_SPACE>`__ 1907 exclude an entire package when scanning for shared libraries.
2972 variables for related information. 1908
2973 1909 .. note::
2974IMAGE_TYPEDEP 1910
2975 Specifies a dependency from one image type on another. Here is an 1911 The shared libraries resolver's functionality results in part from
2976 example from the ```image-live`` <#ref-classes-image-live>`__ class: 1912 the internal function
2977 IMAGE_TYPEDEP_live = "ext3" 1913 package_do_shlibs
2978 1914 , which is part of the
2979 In the previous example, the variable ensures that when "live" is 1915 do_package
2980 listed with the ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ variable, 1916 task. You should be aware that the shared libraries resolver might
2981 the OpenEmbedded build system produces an ``ext3`` image first since 1917 implicitly define some dependencies between packages.
2982 one of the components of the live image is an ``ext3`` formatted 1918
2983 partition containing the root filesystem. 1919 The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the
2984 1920 :term:`PRIVATE_LIBS` variable, which excludes a
2985IMAGE_TYPES 1921 package's particular libraries only and not the whole package.
2986 Specifies the complete list of supported image types by default: 1922
2987 btrfs container cpio cpio.gz cpio.lz4 cpio.lzma cpio.xz cramfs ext2 1923 Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a
2988 ext2.bz2 ext2.gz ext2.lzma ext3 ext3.gz ext4 ext4.gz f2fs hddimg iso 1924 particular package: EXCLUDE_FROM_SHLIBS = "1"
2989 jffs2 jffs2.sum multiubi squashfs squashfs-lz4 squashfs-lzo 1925
2990 squashfs-xz tar tar.bz2 tar.gz tar.lz4 tar.xz tar.zst ubi ubifs wic 1926 EXCLUDE_FROM_WORLD
2991 wic.bz2 wic.gz wic.lzma 1927 Directs BitBake to exclude a recipe from world builds (i.e.
2992 1928 ``bitbake world``). During world builds, BitBake locates, parses and
2993 For more information about these types of images, see 1929 builds all recipes found in every layer exposed in the
2994 ``meta/classes/image_types*.bbclass`` in the `Source 1930 ``bblayers.conf`` configuration file.
2995 Directory <#source-directory>`__. 1931
2996 1932 To exclude a recipe from a world build using this variable, set the
2997INC_PR 1933 variable to "1" in the recipe.
2998 Helps define the recipe revision for recipes that share a common 1934
2999 ``include`` file. You can think of this variable as part of the 1935 .. note::
3000 recipe revision as set from within an include file. 1936
3001 1937 Recipes added to
3002 Suppose, for example, you have a set of recipes that are used across 1938 EXCLUDE_FROM_WORLD
3003 several projects. And, within each of those recipes the revision (its 1939 may still be built during a world build in order to satisfy
3004 ```PR`` <#var-PR>`__ value) is set accordingly. In this case, when 1940 dependencies of other recipes. Adding a recipe to
3005 the revision of those recipes changes, the burden is on you to find 1941 EXCLUDE_FROM_WORLD
3006 all those recipes and be sure that they get changed to reflect the 1942 only ensures that the recipe is not explicitly added to the list
3007 updated version of the recipe. In this scenario, it can get 1943 of build targets in a world build.
3008 complicated when recipes that are used in many places and provide 1944
3009 common functionality are upgraded to a new revision. 1945 EXTENDPE
3010 1946 Used with file and pathnames to create a prefix for a recipe's
3011 A more efficient way of dealing with this situation is to set the 1947 version based on the recipe's :term:`PE` value. If ``PE``
3012 ``INC_PR`` variable inside the ``include`` files that the recipes 1948 is set and greater than zero for a recipe, ``EXTENDPE`` becomes that
3013 share and then expand the ``INC_PR`` variable within the recipes to 1949 value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1_").
3014 help define the recipe revision. 1950 If a recipe's ``PE`` is not set (the default) or is equal to zero,
3015 1951 ``EXTENDPE`` becomes "".
3016 The following provides an example that shows how to use the 1952
3017 ``INC_PR`` variable given a common ``include`` file that defines the 1953 See the :term:`STAMP` variable for an example.
3018 variable. Once the variable is defined in the ``include`` file, you 1954
3019 can use the variable to set the ``PR`` values in each recipe. You 1955 EXTENDPKGV
3020 will notice that when you set a recipe's ``PR`` you can provide more 1956 The full package version specification as it appears on the final
3021 granular revisioning by appending values to the ``INC_PR`` variable: 1957 packages produced by a recipe. The variable's value is normally used
3022 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" 1958 to fix a runtime dependency to the exact same version of another
3023 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" 1959 package in the same recipe: RDEPENDS_${PN}-additional-module = "${PN}
3024 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" 1960 (= ${EXTENDPKGV})"
3025 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The 1961
3026 first line of the example establishes the baseline revision to be 1962 The dependency relationships are intended to force the package
3027 used for all recipes that use the ``include`` file. The remaining 1963 manager to upgrade these types of packages in lock-step.
3028 lines in the example are from individual recipes and show how the 1964
3029 ``PR`` value is set. 1965 EXTERNAL_KERNEL_TOOLS
3030 1966 When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these
3031INCOMPATIBLE_LICENSE 1967 tools are not in the source tree.
3032 Specifies a space-separated list of license names (as they would 1968
3033 appear in ```LICENSE`` <#var-LICENSE>`__) that should be excluded 1969 When kernel tools are available in the tree, they are preferred over
3034 from the build. Recipes that provide no alternatives to listed 1970 any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS``
3035 incompatible licenses are not built. Packages that are individually 1971 variable tells the OpenEmbedded build system to prefer the installed
3036 licensed with the specified incompatible licenses will be deleted. 1972 external tools. See the
3037 1973 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in
3038 .. note:: 1974 ``meta/classes`` to see how the variable is used.
3039 1975
3040 This functionality is only regularly tested using the following 1976 EXTERNALSRC
3041 setting: 1977 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
3042 :: 1978 class, this variable points to the source tree, which is outside of
3043 1979 the OpenEmbedded build system. When set, this variable sets the
3044 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" 1980 :term:`S` variable, which is what the OpenEmbedded build
3045 1981 system uses to locate unpacked recipe source code.
3046 1982
3047 Although you can use other settings, you might be required to 1983 For more information on ``externalsrc.bbclass``, see the
3048 remove dependencies on or provide alternatives to components that 1984 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
3049 are required to produce a functional system image. 1985 can also find information on how to use this variable in the
3050 1986 "`Building Software from an External
3051 .. note:: 1987 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
3052 1988 section in the Yocto Project Development Tasks Manual.
3053 It is possible to define a list of licenses that are allowed to be 1989
3054 used instead of the licenses that are excluded. To do this, define 1990 EXTERNALSRC_BUILD
3055 a variable 1991 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
3056 COMPATIBLE_LICENSES 1992 class, this variable points to the directory in which the recipe's
3057 with the names of the licences that are allowed. Then define 1993 source code is built, which is outside of the OpenEmbedded build
3058 INCOMPATIBLE_LICENSE 1994 system. When set, this variable sets the :term:`B` variable,
3059 as: 1995 which is what the OpenEmbedded build system uses to locate the Build
3060 :: 1996 Directory.
3061 1997
3062 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" 1998 For more information on ``externalsrc.bbclass``, see the
3063 1999 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
3064 2000 can also find information on how to use this variable in the
3065 This will result in 2001 "`Building Software from an External
3066 INCOMPATIBLE_LICENSE 2002 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
3067 containing the names of all licences from 2003 section in the Yocto Project Development Tasks Manual.
3068 AVAILABLE_LICENSES 2004
3069 except the ones specified in 2005 EXTRA_AUTORECONF
3070 COMPATIBLE_LICENSES 2006 For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
3071 , thus only allowing the latter licences to be used. 2007 class, you can use ``EXTRA_AUTORECONF`` to specify extra options to
3072 2008 pass to the ``autoreconf`` command that is executed during the
3073INHERIT 2009 :ref:`ref-tasks-configure` task.
3074 Causes the named class or classes to be inherited globally. Anonymous 2010
3075 functions in the class or classes are not executed for the base 2011 The default value is "--exclude=autopoint".
3076 configuration and in each individual recipe. The OpenEmbedded build 2012
3077 system ignores changes to ``INHERIT`` in individual recipes. 2013 EXTRA_IMAGE_FEATURES
3078 2014 A list of additional features to include in an image. When listing
3079 For more information on ``INHERIT``, see the "```INHERIT`` 2015 more than one feature, separate them with a space.
3080 Configuration 2016
3081 Directive <&YOCTO_DOCS_BB_URL;#inherit-configuration-directive>`__" 2017 Typically, you configure this variable in your ``local.conf`` file,
3082 section in the Bitbake User Manual. 2018 which is found in the :term:`Build Directory`.
3083 2019 Although you can use this variable from within a recipe, best
3084INHERIT_DISTRO 2020 practices dictate that you do not.
3085 Lists classes that will be inherited at the distribution level. It is 2021
3086 unlikely that you want to edit this variable. 2022 .. note::
3087 2023
3088 The default value of the variable is set as follows in the 2024 To enable primary features from within the image recipe, use the
3089 ``meta/conf/distro/defaultsetup.conf`` file: INHERIT_DISTRO ?= 2025 IMAGE_FEATURES
3090 "debian devshell sstate license" 2026 variable.
3091 2027
3092INHIBIT_DEFAULT_DEPS 2028 Here are some examples of features you can add: "dbg-pkgs" - Adds
3093 Prevents the default dependencies, namely the C compiler and standard 2029 -dbg packages for all installed packages including symbol information
3094 C library (libc), from being added to ```DEPENDS`` <#var-DEPENDS>`__. 2030 for debugging and profiling. "debug-tweaks" - Makes an image suitable
3095 This variable is usually used within recipes that do not require any 2031 for debugging. For example, allows root logins without passwords and
3096 compilation using the C compiler. 2032 enables post-installation logging. See the 'allow-empty-password' and
3097 2033 'post-install-logging' features in the "`Image
3098 Set the variable to "1" to prevent the default dependencies from 2034 Features <#ref-features-image>`__" section for more information.
3099 being added. 2035 "dev-pkgs" - Adds -dev packages for all installed packages. This is
3100 2036 useful if you want to develop against the libraries in the image.
3101INHIBIT_PACKAGE_DEBUG_SPLIT 2037 "read-only-rootfs" - Creates an image whose root filesystem is
3102 Prevents the OpenEmbedded build system from splitting out debug 2038 read-only. See the "`Creating a Read-Only Root
3103 information during packaging. By default, the build system splits out 2039 Filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__"
3104 debugging information during the 2040 section in the Yocto Project Development Tasks Manual for more
3105 ```do_package`` <#ref-tasks-package>`__ task. For more information on 2041 information "tools-debug" - Adds debugging tools such as gdb and
3106 how debug information is split out, see the 2042 strace. "tools-sdk" - Adds development tools such as gcc, make,
3107 ```PACKAGE_DEBUG_SPLIT_STYLE`` <#var-PACKAGE_DEBUG_SPLIT_STYLE>`__ 2043 pkgconfig and so forth. "tools-testapps" - Adds useful testing tools
3108 variable. 2044 such as ts_print, aplay, arecord and so forth.
3109 2045
3110 To prevent the build system from splitting out debug information 2046 For a complete list of image features that ships with the Yocto
3111 during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as 2047 Project, see the "`Image Features <#ref-features-image>`__" section.
3112 follows: INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 2048
3113 2049 For an example that shows how to customize your image by using this
3114INHIBIT_PACKAGE_STRIP 2050 variable, see the "`Customizing Images Using Custom
3115 If set to "1", causes the build to not strip binaries in resulting 2051 ``IMAGE_FEATURES`` and
3116 packages and prevents the ``-dbg`` package from containing the source 2052 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__"
3117 files. 2053 section in the Yocto Project Development Tasks Manual.
3118 2054
3119 By default, the OpenEmbedded build system strips binaries and puts 2055 EXTRA_IMAGECMD
3120 the debugging symbols into ``${``\ ```PN`` <#var-PN>`__\ ``}-dbg``. 2056 Specifies additional options for the image creation command that has
3121 Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you 2057 been specified in :term:`IMAGE_CMD`. When setting
3122 plan to debug in general. 2058 this variable, use an override for the associated image type. Here is
3123 2059 an example: EXTRA_IMAGECMD_ext3 ?= "-i 4096"
3124INHIBIT_SYSROOT_STRIP 2060
3125 If set to "1", causes the build to not strip binaries in the 2061 EXTRA_IMAGEDEPENDS
3126 resulting sysroot. 2062 A list of recipes to build that do not provide packages for
3127 2063 installing into the root filesystem.
3128 By default, the OpenEmbedded build system strips binaries in the 2064
3129 resulting sysroot. When you specifically set the 2065 Sometimes a recipe is required to build the final image but is not
3130 ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit 2066 needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS``
3131 this stripping. 2067 variable to list these recipes and thus specify the dependencies. A
3132 2068 typical example is a required bootloader in a machine configuration.
3133 If you want to use this variable, include the 2069
3134 ```staging`` <#ref-classes-staging>`__ class. This class uses a 2070 .. note::
3135 ``sys_strip()`` function to test for the variable and acts 2071
3136 accordingly. 2072 To add packages to the root filesystem, see the various
3137 2073 \*
3138 .. note:: 2074 RDEPENDS
3139 2075 and
3140 Use of the 2076 \*
3141 INHIBIT_SYSROOT_STRIP 2077 RRECOMMENDS
3142 variable occurs in rare and special circumstances. For example, 2078 variables.
3143 suppose you are building bare-metal firmware by using an external 2079
3144 GCC toolchain. Furthermore, even if the toolchain's binaries are 2080 EXTRANATIVEPATH
3145 strippable, other files exist that are needed for the build that 2081 A list of subdirectories of
3146 are not strippable. 2082 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
3147 2083 added to the beginning of the environment variable ``PATH``. As an
3148INITRAMFS_FSTYPES 2084 example, the following prepends
3149 Defines the format for the output image of an initial RAM filesystem 2085 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
3150 (initramfs), which is used during boot. Supported formats are the 2086 ``PATH``: EXTRANATIVEPATH = "foo bar"
3151 same as those supported by the 2087
3152 ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ variable. 2088 EXTRA_OECMAKE
3153 2089 Additional `CMake <https://cmake.org/overview/>`__ options. See the
3154 The default value of this variable, which is set in the 2090 :ref:`cmake <ref-classes-cmake>` class for additional information.
3155 ``meta/conf/bitbake.conf`` configuration file in the `Source 2091
3156 Directory <#source-directory>`__, is "cpio.gz". The Linux kernel's 2092 EXTRA_OECONF
3157 initramfs mechanism, as opposed to the initial RAM filesystem 2093 Additional ``configure`` script options. See
3158 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects 2094 :term:`PACKAGECONFIG_CONFARGS` for
3159 an optionally compressed cpio archive. 2095 additional information on passing configure script options.
3160 2096
3161INITRAMFS_IMAGE 2097 EXTRA_OEMAKE
3162 Specifies the ```PROVIDES`` <#var-PROVIDES>`__ name of an image 2098 Additional GNU ``make`` options.
3163 recipe that is used to build an initial RAM filesystem (initramfs) 2099
3164 image. In other words, the ``INITRAMFS_IMAGE`` variable causes an 2100 Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the
3165 additional recipe to be built as a dependency to whatever root 2101 variable to specify any required GNU options.
3166 filesystem recipe you might be using (e.g. ``core-image-sato``). The 2102
3167 initramfs image recipe you provide should set 2103 :term:`PARALLEL_MAKE` and
3168 ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ to 2104 :term:`PARALLEL_MAKEINST` also make use of
3169 ```INITRAMFS_FSTYPES`` <#var-INITRAMFS_FSTYPES>`__. 2105 ``EXTRA_OEMAKE`` to pass the required flags.
3170 2106
3171 An initramfs image provides a temporary root filesystem used for 2107 EXTRA_OESCONS
3172 early system initialization (e.g. loading of modules needed to locate 2108 When inheriting the :ref:`scons <ref-classes-scons>` class, this
3173 and mount the "real" root filesystem). 2109 variable specifies additional configuration options you want to pass
3174 2110 to the ``scons`` command line.
3175 .. note:: 2111
3176 2112 EXTRA_USERS_PARAMS
2113 When inheriting the :ref:`extrausers <ref-classes-extrausers>`
2114 class, this variable provides image level user and group operations.
2115 This is a more global method of providing user and group
2116 configuration as compared to using the
2117 :ref:`useradd <ref-classes-useradd>` class, which ties user and
2118 group configurations to a specific recipe.
2119
2120 The set list of commands you can configure using the
2121 ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These
2122 commands map to the normal Unix commands of the same names: #
2123 EXTRA_USERS_PARAMS = "\\ # useradd -p '' tester; \\ # groupadd
2124 developers; \\ # userdel nobody; \\ # groupdel -g video; \\ #
2125 groupmod -g 1020 developers; \\ # usermod -s /bin/sh tester; \\ # "
2126
2127 FEATURE_PACKAGES
2128 Defines one or more packages to include in an image when a specific
2129 item is included in :term:`IMAGE_FEATURES`.
2130 When setting the value, ``FEATURE_PACKAGES`` should have the name of
2131 the feature item as an override. Here is an example:
2132 FEATURE_PACKAGES_widget = "package1 package2"
2133
2134 In this example, if "widget" were added to ``IMAGE_FEATURES``,
2135 package1 and package2 would be included in the image.
2136
2137 .. note::
2138
2139 Packages installed by features defined through
2140 FEATURE_PACKAGES
2141 are often package groups. While similarly named, you should not
2142 confuse the
2143 FEATURE_PACKAGES
2144 variable with package groups, which are discussed elsewhere in the
2145 documentation.
2146
2147 FEED_DEPLOYDIR_BASE_URI
2148 Points to the base URL of the server and location within the
2149 document-root that provides the metadata and packages required by
2150 OPKG to support runtime package management of IPK packages. You set
2151 this variable in your ``local.conf`` file.
2152
2153 Consider the following example: FEED_DEPLOYDIR_BASE_URI =
2154 "http://192.168.7.1/BOARD-dir" This example assumes you are serving
2155 your packages over HTTP and your databases are located in a directory
2156 named ``BOARD-dir``, which is underneath your HTTP server's
2157 document-root. In this case, the OpenEmbedded build system generates
2158 a set of configuration files for you in your target that work with
2159 the feed.
2160
2161 FILES
2162 The list of files and directories that are placed in a package. The
2163 :term:`PACKAGES` variable lists the packages
2164 generated by a recipe.
2165
2166 To use the ``FILES`` variable, provide a package name override that
2167 identifies the resulting package. Then, provide a space-separated
2168 list of files or paths that identify the files you want included as
2169 part of the resulting package. Here is an example: FILES_${PN} +=
2170 "${bindir}/mydir1 ${bindir}/mydir2/myfile"
2171
2172 .. note::
2173
2174 - When specifying files or paths, you can pattern match using
2175 Python's
2176 ```glob`https://docs.python.org/2/library/glob.html
2177 syntax. For details on the syntax, see the documentation by
2178 following the previous link.
2179
2180 - When specifying paths as part of the ``FILES`` variable, it is
2181 good practice to use appropriate path variables. For example,
2182 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
2183 rather than ``/usr/bin``. You can find a list of these
2184 variables at the top of the ``meta/conf/bitbake.conf`` file in
2185 the :term:`Source Directory`. You will also
2186 find the default values of the various ``FILES_*`` variables in
2187 this file.
2188
2189 If some of the files you provide with the ``FILES`` variable are
2190 editable and you know they should not be overwritten during the
2191 package update process by the Package Management System (PMS), you
2192 can identify these files so that the PMS will not overwrite them. See
2193 the :term:`CONFFILES` variable for information on
2194 how to identify these files to the PMS.
2195
2196 FILES_SOLIBSDEV
2197 Defines the file specification to match
2198 :term:`SOLIBSDEV`. In other words,
2199 ``FILES_SOLIBSDEV`` defines the full path name of the development
2200 symbolic link (symlink) for shared libraries on the target platform.
2201
2202 The following statement from the ``bitbake.conf`` shows how it is
2203 set: FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV}
2204 ${libdir}/lib*${SOLIBSDEV}"
2205
2206 FILESEXTRAPATHS
2207 Extends the search path the OpenEmbedded build system uses when
2208 looking for files and patches as it processes recipes and append
2209 files. The default directories BitBake uses when it processes recipes
2210 are initially defined by the :term:`FILESPATH`
2211 variable. You can extend ``FILESPATH`` variable by using
2212 ``FILESEXTRAPATHS``.
2213
2214 Best practices dictate that you accomplish this by using
2215 ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you
2216 prepend paths as follows: FILESEXTRAPATHS_prepend :=
2217 "${THISDIR}/${PN}:" In the above example, the build system first
2218 looks for files in a directory that has the same name as the
2219 corresponding append file.
2220
2221 .. note::
2222
2223 When extending ``FILESEXTRAPATHS``, be sure to use the immediate
2224 expansion (``:=``) operator. Immediate expansion makes sure that
2225 BitBake evaluates :term:`THISDIR` at the time the
2226 directive is encountered rather than at some later time when
2227 expansion might result in a directory that does not contain the
2228 files you need.
2229
2230 Also, include the trailing separating colon character if you are
2231 prepending. The trailing colon character is necessary because you
2232 are directing BitBake to extend the path by prepending directories
2233 to the search path.
2234
2235 Here is another common use: FILESEXTRAPATHS_prepend :=
2236 "${THISDIR}/files:" In this example, the build system extends the
2237 ``FILESPATH`` variable to include a directory named ``files`` that is
2238 in the same directory as the corresponding append file.
2239
2240 This next example specifically adds three paths:
2241 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2242
2243 A final example shows how you can extend the search path and include
2244 a :term:`MACHINE`-specific override, which is useful
2245 in a BSP layer: FILESEXTRAPATHS_prepend_intel-x86-common :=
2246 "${THISDIR}/${PN}:" The previous statement appears in the
2247 ``linux-yocto-dev.bbappend`` file, which is found in the Yocto
2248 Project `Source
2249 Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ in
2250 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2251 override is a special :term:`PACKAGE_ARCH`
2252 definition for multiple ``meta-intel`` machines.
2253
2254 .. note::
2255
2256 For a layer that supports a single BSP, the override could just be
2257 the value of
2258 MACHINE
2259 .
2260
2261 By prepending paths in ``.bbappend`` files, you allow multiple append
2262 files that reside in different layers but are used for the same
2263 recipe to correctly extend the path.
2264
2265 FILESOVERRIDES
2266 A subset of :term:`OVERRIDES` used by the
2267 OpenEmbedded build system for creating
2268 :term:`FILESPATH`. The ``FILESOVERRIDES`` variable
2269 uses overrides to automatically extend the
2270 :term:`FILESPATH` variable. For an example of how
2271 that works, see the :term:`FILESPATH` variable
2272 description. Additionally, you find more information on how overrides
2273 are handled in the
2274 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2275 section of the BitBake User Manual.
2276
2277 By default, the ``FILESOVERRIDES`` variable is defined as:
2278 FILESOVERRIDES =
2279 "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2280
2281 .. note::
2282
2283 Do not hand-edit the
2284 FILESOVERRIDES
2285 variable. The values match up with expected overrides and are used
2286 in an expected manner by the build system.
2287
2288 FILESPATH
2289 The default set of directories the OpenEmbedded build system uses
2290 when searching for patches and files.
2291
2292 During the build process, BitBake searches each directory in
2293 ``FILESPATH`` in the specified order when looking for files and
2294 patches specified by each ``file://`` URI in a recipe's
2295 :term:`SRC_URI` statements.
2296
2297 The default value for the ``FILESPATH`` variable is defined in the
2298 ``base.bbclass`` class found in ``meta/classes`` in the
2299 :term:`Source Directory`: FILESPATH =
2300 "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \\
2301 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" The
2302 ``FILESPATH`` variable is automatically extended using the overrides
2303 from the :term:`FILESOVERRIDES` variable.
2304
2305 .. note::
2306
2307 - Do not hand-edit the ``FILESPATH`` variable. If you want the
2308 build system to look in directories other than the defaults,
2309 extend the ``FILESPATH`` variable by using the
2310 :term:`FILESEXTRAPATHS` variable.
2311
2312 - Be aware that the default ``FILESPATH`` directories do not map
2313 to directories in custom layers where append files
2314 (``.bbappend``) are used. If you want the build system to find
2315 patches or files that reside with your append files, you need
2316 to extend the ``FILESPATH`` variable by using the
2317 ``FILESEXTRAPATHS`` variable.
2318
2319 You can take advantage of this searching behavior in useful ways. For
2320 example, consider a case where the following directory structure
2321 exists for general and machine-specific configurations:
2322 files/defconfig files/MACHINEA/defconfig files/MACHINEB/defconfig
2323 Also in the example, the ``SRC_URI`` statement contains
2324 "file://defconfig". Given this scenario, you can set
2325 :term:`MACHINE` to "MACHINEA" and cause the build
2326 system to use files from ``files/MACHINEA``. Set ``MACHINE`` to
2327 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2328 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2329 build system uses files from ``files/defconfig``.
2330
2331 You can find out more about the patching process in the
2332 "`Patching <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__" section
2333 in the Yocto Project Overview and Concepts Manual and the "`Patching
2334 Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in
2335 the Yocto Project Development Tasks Manual. See the
2336 :ref:`ref-tasks-patch` task as well.
2337
2338 FILESYSTEM_PERMS_TABLES
2339 Allows you to define your own file permissions settings table as part
2340 of your configuration for the packaging process. For example, suppose
2341 you need a consistent set of custom permissions for a set of groups
2342 and users across an entire work project. It is best to do this in the
2343 packages themselves but this is not always possible.
2344
2345 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2346 which is located in the ``meta/files`` folder in the :term:`Source Directory`.
2347 If you create your own file
2348 permissions setting table, you should place it in your layer or the
2349 distro's layer.
2350
2351 You define the ``FILESYSTEM_PERMS_TABLES`` variable in the
2352 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2353 to point to your custom
2354 ``fs-perms.txt``. You can specify more than a single file permissions
2355 setting table. The paths you specify to these files must be defined
2356 within the :term:`BBPATH` variable.
2357
2358 For guidance on how to create your own file permissions settings
2359 table file, examine the existing ``fs-perms.txt``.
2360
2361 FIT_HASH_ALG
2362 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
2363
2364 FIT_SIGN_ALG</glossterm>
2365 Specifies the signature algorithm used in creating the FIT Image.
2366 For e.g. rsa2048.
2367
2368 FONT_EXTRA_RDEPENDS
2369 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2370 this variable specifies the runtime dependencies for font packages.
2371 By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils".
2372
2373 FONT_PACKAGES
2374 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2375 this variable identifies packages containing font files that need to
2376 be cached by Fontconfig. By default, the ``fontcache`` class assumes
2377 that fonts are in the recipe's main package (i.e.
2378 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
2379 need are in a package other than that main package.
2380
2381 FORCE_RO_REMOVE
2382 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
2383 during the generation of the root filesystem.
2384
2385 Set the variable to "1" to force the removal of these packages.
2386
2387 FULL_OPTIMIZATION
2388 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when
2389 compiling an optimized system. This variable defaults to "-O2 -pipe
2390 ${DEBUG_FLAGS}".
2391
2392 GCCPIE
2393 Enables Position Independent Executables (PIE) within the GNU C
2394 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
2395 Programming (ROP) attacks much more difficult to execute.
2396
2397 By default the ``security_flags.inc`` file enables PIE by setting the
2398 variable as follows: GCCPIE ?= "--enable-default-pie"
2399
2400 GCCVERSION
2401 Specifies the default version of the GNU C Compiler (GCC) used for
2402 compilation. By default, ``GCCVERSION`` is set to "8.x" in the
2403 ``meta/conf/distro/include/tcmode-default.inc`` include file:
2404 GCCVERSION ?= "8.%" You can override this value by setting it in a
2405 configuration file such as the ``local.conf``.
2406
2407 GDB
2408 The minimal command and arguments to run the GNU Debugger.
2409
2410 GITDIR
2411 The directory in which a local copy of a Git repository is stored
2412 when it is cloned.
2413
2414 GLIBC_GENERATE_LOCALES
2415 Specifies the list of GLIBC locales to generate should you not wish
2416 to generate all LIBC locals, which can be time consuming.
2417
2418 .. note::
2419
2420 If you specifically remove the locale
2421 en_US.UTF-8
2422 , you must set
2423 IMAGE_LINGUAS
2424 appropriately.
2425
2426 You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file.
2427 By default, all locales are generated. GLIBC_GENERATE_LOCALES =
2428 "en_GB.UTF-8 en_US.UTF-8"
2429
2430 GROUPADD_PARAM
2431 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2432 this variable specifies for a package what parameters should be
2433 passed to the ``groupadd`` command if you wish to add a group to the
2434 system when the package is installed.
2435
2436 Here is an example from the ``dbus`` recipe: GROUPADD_PARAM_${PN} =
2437 "-r netdev" For information on the standard Linux shell command
2438 ``groupadd``, see http://linux.die.net/man/8/groupadd.
2439
2440 GROUPMEMS_PARAM
2441 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2442 this variable specifies for a package what parameters should be
2443 passed to the ``groupmems`` command if you wish to modify the members
2444 of a group when the package is installed.
2445
2446 For information on the standard Linux shell command ``groupmems``,
2447 see http://linux.die.net/man/8/groupmems.
2448
2449 GRUB_GFXSERIAL
2450 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
2451 and serial in the boot menu. Set this variable to "1" in your
2452 ``local.conf`` or distribution configuration file to enable graphics
2453 and serial in the menu.
2454
2455 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
2456 information on how this variable is used.
2457
2458 GRUB_OPTS
2459 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
2460 configuration. Use a semi-colon character (``;``) to separate
2461 multiple options.
2462
2463 The ``GRUB_OPTS`` variable is optional. See the
2464 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2465 on how this variable is used.
2466
2467 GRUB_TIMEOUT
2468 Specifies the timeout before executing the default ``LABEL`` in the
2469 GNU GRand Unified Bootloader (GRUB).
2470
2471 The ``GRUB_TIMEOUT`` variable is optional. See the
2472 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2473 on how this variable is used.
2474
2475 GTKIMMODULES_PACKAGES
2476 When inheriting the
2477 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
2478 this variable specifies the packages that contain the GTK+ input
2479 method modules being installed when the modules are in packages other
2480 than the main package.
2481
2482 HOMEPAGE
2483 Website where more information about the software the recipe is
2484 building can be found.
2485
2486 HOST_ARCH
2487 The name of the target architecture, which is normally the same as
2488 :term:`TARGET_ARCH`. The OpenEmbedded build system
2489 supports many architectures. Here is an example list of architectures
2490 supported. This list is by no means complete as the architecture is
2491 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel
2492
2493 HOST_CC_ARCH
2494 Specifies architecture-specific compiler flags that are passed to the
2495 C compiler.
2496
2497 Default initialization for ``HOST_CC_ARCH`` varies depending on what
2498 is being built:
2499
2500 - :term:`TARGET_CC_ARCH` when building for the
2501 target
2502
2503 - ``BUILD_CC_ARCH`` when building for the build host (i.e.
2504 ``-native``)
2505
2506 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
2507 ``nativesdk-``)
2508
2509 HOST_OS
2510 Specifies the name of the target operating system, which is normally
2511 the same as the :term:`TARGET_OS`. The variable can
2512 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
2513 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
2514 "linux-musleabi" values possible.
2515
2516 HOST_PREFIX
2517 Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX``
2518 is normally the same as :term:`TARGET_PREFIX`.
2519
2520 HOST_SYS
2521 Specifies the system, including the architecture and the operating
2522 system, for which the build is occurring in the context of the
2523 current recipe.
2524
2525 The OpenEmbedded build system automatically sets this variable based
2526 on :term:`HOST_ARCH`,
2527 :term:`HOST_VENDOR`, and
2528 :term:`HOST_OS` variables.
2529
2530 .. note::
2531
2532 You do not need to set the variable yourself.
2533
2534 Consider these two examples:
2535
2536 - Given a native recipe on a 32-bit x86 machine running Linux, the
2537 value is "i686-linux".
2538
2539 - Given a recipe being built for a little-endian MIPS target running
2540 Linux, the value might be "mipsel-linux".
2541
2542 HOSTTOOLS
2543 A space-separated list (filter) of tools on the build host that
2544 should be allowed to be called from within build tasks. Using this
2545 filter helps reduce the possibility of host contamination. If a tool
2546 specified in the value of ``HOSTTOOLS`` is not found on the build
2547 host, the OpenEmbedded build system produces an error and the build
2548 is not started.
2549
2550 For additional information, see
2551 :term:`HOSTTOOLS_NONFATAL`.
2552
2553 HOSTTOOLS_NONFATAL
2554 A space-separated list (filter) of tools on the build host that
2555 should be allowed to be called from within build tasks. Using this
2556 filter helps reduce the possibility of host contamination. Unlike
2557 :term:`HOSTTOOLS`, the OpenEmbedded build system
2558 does not produce an error if a tool specified in the value of
2559 ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can
2560 use ``HOSTTOOLS_NONFATAL`` to filter optional host tools.
2561
2562 HOST_VENDOR
2563 Specifies the name of the vendor. ``HOST_VENDOR`` is normally the
2564 same as :term:`TARGET_VENDOR`.
2565
2566 ICECC_DISABLED
2567 Disables or enables the ``icecc`` (Icecream) function. For more
2568 information on this function and best practices for using this
2569 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`"
2570 section.
2571
2572 Setting this variable to "1" in your ``local.conf`` disables the
2573 function: ICECC_DISABLED ??= "1" To enable the function, set the
2574 variable as follows: ICECC_DISABLED = ""
2575
2576 ICECC_ENV_EXEC
2577 Points to the ``icecc-create-env`` script that you provide. This
2578 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You
2579 set this variable in your ``local.conf`` file.
2580
2581 If you do not point to a script that you provide, the OpenEmbedded
2582 build system uses the default script provided by the
2583 ``icecc-create-env.bb`` recipe, which is a modified version and not
2584 the one that comes with ``icecc``.
2585
2586 ICECC_PARALLEL_MAKE
2587 Extra options passed to the ``make`` command during the
2588 :ref:`ref-tasks-compile` task that specify parallel
2589 compilation. This variable usually takes the form of "-j x", where x
2590 represents the maximum number of parallel threads ``make`` can run.
2591
2592 .. note::
2593
2594 The options passed affect builds on all enabled machines on the
2595 network, which are machines running the
2596 iceccd
2597 daemon.
2598
2599 If your enabled machines support multiple cores, coming up with the
2600 maximum number of parallel threads that gives you the best
2601 performance could take some experimentation since machine speed,
2602 network lag, available memory, and existing machine loads can all
2603 affect build time. Consequently, unlike the
2604 :term:`PARALLEL_MAKE` variable, there is no
2605 rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal
2606 performance.
2607
2608 If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not
2609 use it (i.e. the system does not detect and assign the number of
2610 cores as is done with ``PARALLEL_MAKE``).
2611
2612 ICECC_PATH
2613 The location of the ``icecc`` binary. You can set this variable in
2614 your ``local.conf`` file. If your ``local.conf`` file does not define
2615 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts
2616 to define it by locating ``icecc`` using ``which``.
2617
2618 ICECC_USER_CLASS_BL
2619 Identifies user classes that you do not want the Icecream distributed
2620 compile support to consider. This variable is used by the
2621 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2622 your ``local.conf`` file.
2623
2624 When you list classes using this variable, you are "blacklisting"
2625 them from distributed compilation across remote hosts. Any classes
2626 you list will be distributed and compiled locally.
2627
2628 ICECC_USER_PACKAGE_BL
2629 Identifies user recipes that you do not want the Icecream distributed
2630 compile support to consider. This variable is used by the
2631 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2632 your ``local.conf`` file.
2633
2634 When you list packages using this variable, you are "blacklisting"
2635 them from distributed compilation across remote hosts. Any packages
2636 you list will be distributed and compiled locally.
2637
2638 ICECC_USER_PACKAGE_WL
2639 Identifies user recipes that use an empty
2640 :term:`PARALLEL_MAKE` variable that you want to
2641 force remote distributed compilation on using the Icecream
2642 distributed compile support. This variable is used by the
2643 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2644 your ``local.conf`` file.
2645
2646 IMAGE_BASENAME
2647 The base name of image output files. This variable defaults to the
2648 recipe name (``${``\ :term:`PN`\ ``}``).
2649
2650 IMAGE_BOOT_FILES
2651 A space-separated list of files installed into the boot partition
2652 when preparing an image using the Wic tool with the
2653 ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default,
2654 the files are
2655 installed under the same name as the source files. To change the
2656 installed name, separate it from the original name with a semi-colon
2657 (;). Source files need to be located in
2658 :term:`DEPLOY_DIR_IMAGE`. Here are two
2659 examples: IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2660 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
2661
2662 Alternatively, source files can be picked up using a glob pattern. In
2663 this case, the destination file must have the same name as the base
2664 name of the source file path. To install files into a directory
2665 within the target location, pass its name after a semi-colon (;).
2666 Here are two examples: IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2667 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" The first example
2668 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
2669 into the root of the target partition. The second example installs
2670 the same files into a ``boot`` directory within the target partition.
2671
2672 You can find information on how to use the Wic tool in the "`Creating
2673 Partitioned Images Using
2674 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__"
2675 section of the Yocto Project Development Tasks Manual. Reference
2676 material for Wic is located in the "`OpenEmbedded Kickstart (.wks)
2677 Reference <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__" chapter.
2678
2679 IMAGE_CLASSES
2680 A list of classes that all images should inherit. You typically use
2681 this variable to specify the list of classes that register the
2682 different types of images the OpenEmbedded build system creates.
2683
2684 The default value for ``IMAGE_CLASSES`` is ``image_types``. You can
2685 set this variable in your ``local.conf`` or in a distribution
2686 configuration file.
2687
2688 For more information, see ``meta/classes/image_types.bbclass`` in the
2689 :term:`Source Directory`.
2690
2691 IMAGE_CMD
2692 Specifies the command to create the image file for a specific image
2693 type, which corresponds to the value set set in
2694 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
2695 ``btrfs``, and so forth). When setting this variable, you should use
2696 an override for the associated type. Here is an example:
2697 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \\ --faketime
2698 --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \\
2699 ${EXTRA_IMAGECMD}"
2700
2701 You typically do not need to set this variable unless you are adding
2702 support for a new image type. For more examples on how to set this
2703 variable, see the :ref:`image_types <ref-classes-image_types>`
2704 class file, which is ``meta/classes/image_types.bbclass``.
2705
2706 IMAGE_DEVICE_TABLES
2707 Specifies one or more files that contain custom device tables that
2708 are passed to the ``makedevs`` command as part of creating an image.
2709 These files list basic device nodes that should be created under
2710 ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set,
2711 ``files/device_table-minimal.txt`` is used, which is located by
2712 :term:`BBPATH`. For details on how you should write
2713 device table files, see ``meta/files/device_table-minimal.txt`` as an
2714 example.
2715
2716 IMAGE_FEATURES
2717 The primary list of features to include in an image. Typically, you
2718 configure this variable in an image recipe. Although you can use this
2719 variable from your ``local.conf`` file, which is found in the
2720 :term:`Build Directory`, best practices dictate that you do
2721 not.
2722
2723 .. note::
2724
2725 To enable extra features from outside the image recipe, use the
2726 EXTRA_IMAGE_FEATURES
2727 variable.
2728
2729 For a list of image features that ships with the Yocto Project, see
2730 the "`Image Features <#ref-features-image>`__" section.
2731
2732 For an example that shows how to customize your image by using this
2733 variable, see the "`Customizing Images Using Custom
2734 ``IMAGE_FEATURES`` and
2735 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__"
2736 section in the Yocto Project Development Tasks Manual.
2737
2738 IMAGE_FSTYPES
2739 Specifies the formats the OpenEmbedded build system uses during the
2740 build when creating the root filesystem. For example, setting
2741 ``IMAGE_FSTYPES`` as follows causes the build system to create root
2742 filesystems using two formats: ``.ext3`` and ``.tar.bz2``:
2743 IMAGE_FSTYPES = "ext3 tar.bz2"
2744
2745 For the complete list of supported image formats from which you can
2746 choose, see :term:`IMAGE_TYPES`.
2747
2748 .. note::
2749
2750 - If an image recipe uses the "inherit image" line and you are
2751 setting ``IMAGE_FSTYPES`` inside the recipe, you must set
2752 ``IMAGE_FSTYPES`` prior to using the "inherit image" line.
2753
2754 - Due to the way the OpenEmbedded build system processes this
2755 variable, you cannot update its contents by using ``_append``
2756 or ``_prepend``. You must use the ``+=`` operator to add one or
2757 more options to the ``IMAGE_FSTYPES`` variable.
2758
2759 IMAGE_INSTALL
2760 Used by recipes to specify the packages to install into an image
2761 through the :ref:`image <ref-classes-image>` class. Use the
2762 ``IMAGE_INSTALL`` variable with care to avoid ordering issues.
2763
2764 Image recipes set ``IMAGE_INSTALL`` to specify the packages to
2765 install into an image through ``image.bbclass``. Additionally,
2766 "helper" classes such as the
2767 :ref:`core-image <ref-classes-core-image>` class exist that can
2768 take lists used with ``IMAGE_FEATURES`` and turn them into
2769 auto-generated entries in ``IMAGE_INSTALL`` in addition to its
2770 default contents.
2771
2772 When you use this variable, it is best to use it as follows:
2773 IMAGE_INSTALL_append = " package-name" Be sure to include the space
2774 between the quotation character and the start of the package name or
2775 names.
2776
2777 .. note::
2778
2779 - When working with a
2780 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__
2781 image, do not use the ``IMAGE_INSTALL`` variable to specify
2782 packages for installation. Instead, use the
2783 :term:`PACKAGE_INSTALL` variable, which
2784 allows the initial RAM filesystem (initramfs) recipe to use a
2785 fixed set of packages and not be affected by ``IMAGE_INSTALL``.
2786 For information on creating an initramfs, see the "`Building an
2787 Initial RAM Filesystem (initramfs)
2788 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__"
2789 section in the Yocto Project Development Tasks Manual.
2790
2791 - Using ``IMAGE_INSTALL`` with the
2792 :ref:`+= <bitbake:appending-and-prepending>`
2793 BitBake operator within the ``/conf/local.conf`` file or from
2794 within an image recipe is not recommended. Use of this operator
2795 in these ways can cause ordering issues. Since
2796 ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default
2797 value using the
2798 :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>`
2799 operator, using a ``+=`` operation against ``IMAGE_INSTALL``
2800 results in unexpected behavior when used within
2801 ``conf/local.conf``. Furthermore, the same operation from
2802 within an image recipe may or may not succeed depending on the
2803 specific situation. In both these cases, the behavior is
2804 contrary to how most users expect the ``+=`` operator to work.
2805
2806 IMAGE_LINGUAS
2807 Specifies the list of locales to install into the image during the
2808 root filesystem construction process. The OpenEmbedded build system
2809 automatically splits locale files, which are used for localization,
2810 into separate packages. Setting the ``IMAGE_LINGUAS`` variable
2811 ensures that any locale packages that correspond to packages already
2812 selected for installation into the image are also installed. Here is
2813 an example: IMAGE_LINGUAS = "pt-br de-de"
2814
2815 In this example, the build system ensures any Brazilian Portuguese
2816 and German locale files that correspond to packages in the image are
2817 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
2818 ``*-locale-pt`` and ``*-locale-de``, since some software packages
2819 only provide locale files by language and not by country-specific
2820 language).
2821
2822 See the :term:`GLIBC_GENERATE_LOCALES`
2823 variable for information on generating GLIBC locales.
2824
2825 IMAGE_MANIFEST
2826 The manifest file for the image. This file lists all the installed
2827 packages that make up the image. The file contains package
2828 information on a line-per-package basis as follows: packagename
2829 packagearch version
2830
2831 The :ref:`image <ref-classes-image>` class defines the manifest
2832 file as follows: IMAGE_MANIFEST =
2833 "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" The location is
2834 derived using the :term:`DEPLOY_DIR_IMAGE`
2835 and :term:`IMAGE_NAME` variables. You can find
2836 information on how the image is created in the "`Image
2837 Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
2838 section in the Yocto Project Overview and Concepts Manual.
2839
2840 IMAGE_NAME
2841 The name of the output image files minus the extension. This variable
2842 is derived using the :term:`IMAGE_BASENAME`,
2843 :term:`MACHINE`, and :term:`DATETIME`
2844 variables: IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
2845
2846 IMAGE_OVERHEAD_FACTOR
2847 Defines a multiplier that the build system applies to the initial
2848 image size for cases when the multiplier times the returned disk
2849 usage value for the image is greater than the sum of
2850 ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of
2851 the multiplier applied to the initial image size creates free disk
2852 space in the image as overhead. By default, the build process uses a
2853 multiplier of 1.3 for this variable. This default value results in
2854 30% free disk space added to the image when this method is used to
2855 determine the final generated image size. You should be aware that
2856 post install scripts and the package management system uses disk
2857 space inside this overhead area. Consequently, the multiplier does
2858 not produce an image with all the theoretical free disk space. See
2859 ``IMAGE_ROOTFS_SIZE`` for information on how the build system
2860 determines the overall image size.
2861
2862 The default 30% free disk space typically gives the image enough room
2863 to boot and allows for basic post installs while still leaving a
2864 small amount of free disk space. If 30% free space is inadequate, you
2865 can increase the default value. For example, the following setting
2866 gives you 50% free space added to the image: IMAGE_OVERHEAD_FACTOR =
2867 "1.5"
2868
2869 Alternatively, you can ensure a specific amount of free disk space is
2870 added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE``
2871 variable.
2872
2873 IMAGE_PKGTYPE
2874 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
2875 OpenEmbedded build system. The variable is defined appropriately by
2876 the :ref:`package_deb <ref-classes-package_deb>`,
2877 :ref:`package_rpm <ref-classes-package_rpm>`,
2878 :ref:`package_ipk <ref-classes-package_ipk>`, or
2879 :ref:`package_tar <ref-classes-package_tar>` class.
2880
2881 .. note::
2882
2883 The
2884 package_tar
2885 class is broken and is not supported. It is recommended that you
2886 do not use it.
2887
2888 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
2889 :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE``
2890 for packaging up images and SDKs.
2891
2892 You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the
2893 variable is set indirectly through the appropriate
2894 :ref:`package_* <ref-classes-package>` class using the
2895 :term:`PACKAGE_CLASSES` variable. The
2896 OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
2897 or IPK) that appears with the variable
2898
2899 .. note::
2900
2901 Files using the
2902 .tar
2903 format are never used as a substitute packaging format for DEB,
2904 RPM, and IPK formatted files for your image or SDK.
2905
2906 IMAGE_POSTPROCESS_COMMAND
2907 Specifies a list of functions to call once the OpenEmbedded build
2908 system creates the final image output files. You can specify
2909 functions separated by semicolons: IMAGE_POSTPROCESS_COMMAND +=
2910 "function; ... "
2911
2912 If you need to pass the root filesystem path to a command within the
2913 function, you can use ``${IMAGE_ROOTFS}``, which points to the
2914 directory that becomes the root filesystem image. See the
2915 :term:`IMAGE_ROOTFS` variable for more
2916 information.
2917
2918 IMAGE_PREPROCESS_COMMAND
2919 Specifies a list of functions to call before the OpenEmbedded build
2920 system creates the final image output files. You can specify
2921 functions separated by semicolons: IMAGE_PREPROCESS_COMMAND +=
2922 "function; ... "
2923
2924 If you need to pass the root filesystem path to a command within the
2925 function, you can use ``${IMAGE_ROOTFS}``, which points to the
2926 directory that becomes the root filesystem image. See the
2927 :term:`IMAGE_ROOTFS` variable for more
2928 information.
2929
2930 IMAGE_ROOTFS
2931 The location of the root filesystem while it is under construction
2932 (i.e. during the :ref:`ref-tasks-rootfs` task). This
2933 variable is not configurable. Do not change it.
2934
2935 IMAGE_ROOTFS_ALIGNMENT
2936 Specifies the alignment for the output image file in Kbytes. If the
2937 size of the image is not a multiple of this value, then the size is
2938 rounded up to the nearest multiple of the value. The default value is
2939 "1". See :term:`IMAGE_ROOTFS_SIZE` for
2940 additional information.
2941
2942 IMAGE_ROOTFS_EXTRA_SPACE
2943 Defines additional free disk space created in the image in Kbytes. By
2944 default, this variable is set to "0". This free disk space is added
2945 to the image after the build system determines the image size as
2946 described in ``IMAGE_ROOTFS_SIZE``.
2947
2948 This variable is particularly useful when you want to ensure that a
2949 specific amount of free disk space is available on a device after an
2950 image is installed and running. For example, to be sure 5 Gbytes of
2951 free disk space is available, set the variable as follows:
2952 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
2953
2954 For example, the Yocto Project Build Appliance specifically requests
2955 40 Gbytes of extra space with the line: IMAGE_ROOTFS_EXTRA_SPACE =
2956 "41943040"
2957
2958 IMAGE_ROOTFS_SIZE
2959 Defines the size in Kbytes for the generated image. The OpenEmbedded
2960 build system determines the final size for the generated image using
2961 an algorithm that takes into account the initial disk space used for
2962 the generated image, a requested size for the image, and requested
2963 additional free disk space to be added to the image. Programatically,
2964 the build system determines the final size of the generated image as
2965 follows: if (image-du \* overhead) < rootfs-size:
2966 internal-rootfs-size = rootfs-size + xspace else:
2967 internal-rootfs-size = (image-du \* overhead) + xspace where:
2968 image-du = Returned value of the du command on the image. overhead =
2969 IMAGE_OVERHEAD_FACTOR rootfs-size = IMAGE_ROOTFS_SIZE
2970 internal-rootfs-size = Initial root filesystem size before any
2971 modifications. xspace = IMAGE_ROOTFS_EXTRA_SPACE
2972
2973 See the :term:`IMAGE_OVERHEAD_FACTOR`
2974 and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
2975 variables for related information.
2976
2977 IMAGE_TYPEDEP
2978 Specifies a dependency from one image type on another. Here is an
2979 example from the :ref:`image-live <ref-classes-image-live>` class:
2980 IMAGE_TYPEDEP_live = "ext3"
2981
2982 In the previous example, the variable ensures that when "live" is
2983 listed with the :term:`IMAGE_FSTYPES` variable,
2984 the OpenEmbedded build system produces an ``ext3`` image first since
2985 one of the components of the live image is an ``ext3`` formatted
2986 partition containing the root filesystem.
2987
2988 IMAGE_TYPES
2989 Specifies the complete list of supported image types by default:
2990 btrfs container cpio cpio.gz cpio.lz4 cpio.lzma cpio.xz cramfs ext2
2991 ext2.bz2 ext2.gz ext2.lzma ext3 ext3.gz ext4 ext4.gz f2fs hddimg iso
2992 jffs2 jffs2.sum multiubi squashfs squashfs-lz4 squashfs-lzo
2993 squashfs-xz tar tar.bz2 tar.gz tar.lz4 tar.xz tar.zst ubi ubifs wic
2994 wic.bz2 wic.gz wic.lzma
2995
2996 For more information about these types of images, see
2997 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`.
2998
2999 INC_PR
3000 Helps define the recipe revision for recipes that share a common
3001 ``include`` file. You can think of this variable as part of the
3002 recipe revision as set from within an include file.
3003
3004 Suppose, for example, you have a set of recipes that are used across
3005 several projects. And, within each of those recipes the revision (its
3006 :term:`PR` value) is set accordingly. In this case, when
3007 the revision of those recipes changes, the burden is on you to find
3008 all those recipes and be sure that they get changed to reflect the
3009 updated version of the recipe. In this scenario, it can get
3010 complicated when recipes that are used in many places and provide
3011 common functionality are upgraded to a new revision.
3012
3013 A more efficient way of dealing with this situation is to set the
3014 ``INC_PR`` variable inside the ``include`` files that the recipes
3015 share and then expand the ``INC_PR`` variable within the recipes to
3016 help define the recipe revision.
3017
3018 The following provides an example that shows how to use the
3019 ``INC_PR`` variable given a common ``include`` file that defines the
3020 variable. Once the variable is defined in the ``include`` file, you
3021 can use the variable to set the ``PR`` values in each recipe. You
3022 will notice that when you set a recipe's ``PR`` you can provide more
3023 granular revisioning by appending values to the ``INC_PR`` variable:
3024 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3025 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3026 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3027 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The
3028 first line of the example establishes the baseline revision to be
3029 used for all recipes that use the ``include`` file. The remaining
3030 lines in the example are from individual recipes and show how the
3031 ``PR`` value is set.
3032
3033 INCOMPATIBLE_LICENSE
3034 Specifies a space-separated list of license names (as they would
3035 appear in :term:`LICENSE`) that should be excluded
3036 from the build. Recipes that provide no alternatives to listed
3037 incompatible licenses are not built. Packages that are individually
3038 licensed with the specified incompatible licenses will be deleted.
3039
3040 .. note::
3041
3042 This functionality is only regularly tested using the following
3043 setting:
3044 ::
3045
3046 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
3047
3048
3049 Although you can use other settings, you might be required to
3050 remove dependencies on or provide alternatives to components that
3051 are required to produce a functional system image.
3052
3053 .. note::
3054
3055 It is possible to define a list of licenses that are allowed to be
3056 used instead of the licenses that are excluded. To do this, define
3057 a variable
3058 COMPATIBLE_LICENSES
3059 with the names of the licences that are allowed. Then define
3060 INCOMPATIBLE_LICENSE
3061 as:
3062 ::
3063
3064 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
3065
3066
3067 This will result in
3068 INCOMPATIBLE_LICENSE
3069 containing the names of all licences from
3070 AVAILABLE_LICENSES
3071 except the ones specified in
3072 COMPATIBLE_LICENSES
3073 , thus only allowing the latter licences to be used.
3074
3075 INHERIT
3076 Causes the named class or classes to be inherited globally. Anonymous
3077 functions in the class or classes are not executed for the base
3078 configuration and in each individual recipe. The OpenEmbedded build
3079 system ignores changes to ``INHERIT`` in individual recipes.
3080
3081 For more information on ``INHERIT``, see the
3082 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
3083 section in the Bitbake User Manual.
3084
3085 INHERIT_DISTRO
3086 Lists classes that will be inherited at the distribution level. It is
3087 unlikely that you want to edit this variable.
3088
3089 The default value of the variable is set as follows in the
3090 ``meta/conf/distro/defaultsetup.conf`` file: INHERIT_DISTRO ?=
3091 "debian devshell sstate license"
3092
3093 INHIBIT_DEFAULT_DEPS
3094 Prevents the default dependencies, namely the C compiler and standard
3095 C library (libc), from being added to :term:`DEPENDS`.
3096 This variable is usually used within recipes that do not require any
3097 compilation using the C compiler.
3098
3099 Set the variable to "1" to prevent the default dependencies from
3100 being added.
3101
3102 INHIBIT_PACKAGE_DEBUG_SPLIT
3103 Prevents the OpenEmbedded build system from splitting out debug
3104 information during packaging. By default, the build system splits out
3105 debugging information during the
3106 :ref:`ref-tasks-package` task. For more information on
3107 how debug information is split out, see the
3108 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
3109 variable.
3110
3111 To prevent the build system from splitting out debug information
3112 during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as
3113 follows: INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
3114
3115 INHIBIT_PACKAGE_STRIP
3116 If set to "1", causes the build to not strip binaries in resulting
3117 packages and prevents the ``-dbg`` package from containing the source
3118 files.
3119
3120 By default, the OpenEmbedded build system strips binaries and puts
3121 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
3122 Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you
3123 plan to debug in general.
3124
3125 INHIBIT_SYSROOT_STRIP
3126 If set to "1", causes the build to not strip binaries in the
3127 resulting sysroot.
3128
3129 By default, the OpenEmbedded build system strips binaries in the
3130 resulting sysroot. When you specifically set the
3131 ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit
3132 this stripping.
3133
3134 If you want to use this variable, include the
3135 :ref:`staging <ref-classes-staging>` class. This class uses a
3136 ``sys_strip()`` function to test for the variable and acts
3137 accordingly.
3138
3139 .. note::
3140
3141 Use of the
3142 INHIBIT_SYSROOT_STRIP
3143 variable occurs in rare and special circumstances. For example,
3144 suppose you are building bare-metal firmware by using an external
3145 GCC toolchain. Furthermore, even if the toolchain's binaries are
3146 strippable, other files exist that are needed for the build that
3147 are not strippable.
3148
3149 INITRAMFS_FSTYPES
3150 Defines the format for the output image of an initial RAM filesystem
3151 (initramfs), which is used during boot. Supported formats are the
3152 same as those supported by the
3153 :term:`IMAGE_FSTYPES` variable.
3154
3155 The default value of this variable, which is set in the
3156 ``meta/conf/bitbake.conf`` configuration file in the
3157 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
3158 initramfs mechanism, as opposed to the initial RAM filesystem
3159 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
3160 an optionally compressed cpio archive.
3161
3162 INITRAMFS_IMAGE
3163 Specifies the :term:`PROVIDES` name of an image
3164 recipe that is used to build an initial RAM filesystem (initramfs)
3165 image. In other words, the ``INITRAMFS_IMAGE`` variable causes an
3166 additional recipe to be built as a dependency to whatever root
3167 filesystem recipe you might be using (e.g. ``core-image-sato``). The
3168 initramfs image recipe you provide should set
3169 :term:`IMAGE_FSTYPES` to
3170 :term:`INITRAMFS_FSTYPES`.
3171
3172 An initramfs image provides a temporary root filesystem used for
3173 early system initialization (e.g. loading of modules needed to locate
3174 and mount the "real" root filesystem).
3175
3176 .. note::
3177
3178 See the
3179 meta/recipes-core/images/core-image-minimal-initramfs.bb
3180 recipe in the
3181 Source Directory
3182 for an example initramfs recipe. To select this sample recipe as
3183 the one built to provide the initramfs image, set
3184 INITRAMFS_IMAGE
3185 to "core-image-minimal-initramfs".
3186
3187 You can also find more information by referencing the
3188 ``meta-poky/conf/local.conf.sample.extended`` configuration file in
3189 the Source Directory, the :ref:`image <ref-classes-image>` class,
3190 and the :ref:`kernel <ref-classes-kernel>` class to see how to use
3191 the ``INITRAMFS_IMAGE`` variable.
3192
3193 If ``INITRAMFS_IMAGE`` is empty, which is the default, then no
3194 initramfs image is built.
3195
3196 For more information, you can also see the
3197 :term:`INITRAMFS_IMAGE_BUNDLE`
3198 variable, which allows the generated image to be bundled inside the
3199 kernel image. Additionally, for information on creating an initramfs
3200 image, see the "`Building an Initial RAM Filesystem (initramfs)
3201 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
3202 in the Yocto Project Development Tasks Manual.
3203
3204 INITRAMFS_IMAGE_BUNDLE
3205 Controls whether or not the image recipe specified by
3206 :term:`INITRAMFS_IMAGE` is run through an
3207 extra pass
3208 (:ref:`ref-tasks-bundle_initramfs`) during
3209 kernel compilation in order to build a single binary that contains
3210 both the kernel image and the initial RAM filesystem (initramfs)
3211 image. This makes use of the
3212 :term:`CONFIG_INITRAMFS_SOURCE` kernel
3213 feature.
3214
3215 .. note::
3216
3217 Using an extra compilation pass to bundle the initramfs avoids a
3218 circular dependency between the kernel recipe and the initramfs
3219 recipe should the initramfs include kernel modules. Should that be
3220 the case, the initramfs recipe depends on the kernel for the
3221 kernel modules, and the kernel depends on the initramfs recipe
3222 since the initramfs is bundled inside the kernel image.
3223
3224 The combined binary is deposited into the ``tmp/deploy`` directory,
3225 which is part of the :term:`Build Directory`.
3226
3227 Setting the variable to "1" in a configuration file causes the
3228 OpenEmbedded build system to generate a kernel image with the
3229 initramfs specified in ``INITRAMFS_IMAGE`` bundled within:
3230 INITRAMFS_IMAGE_BUNDLE = "1" By default, the
3231 :ref:`kernel <ref-classes-kernel>` class sets this variable to a
3232 null string as follows: INITRAMFS_IMAGE_BUNDLE ?= ""
3233
3234 .. note::
3235
3236 You must set the
3237 INITRAMFS_IMAGE_BUNDLE
3238 variable in a configuration file. You cannot set the variable in a
3239 recipe file.
3240
3177 See the 3241 See the
3178 meta/recipes-core/images/core-image-minimal-initramfs.bb 3242 :yocto_git:`local.conf.sample.extended </cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>`
3179 recipe in the 3243 file for additional information. Also, for information on creating an
3180 Source Directory 3244 initramfs, see the "`Building an Initial RAM Filesystem (initramfs)
3181 for an example initramfs recipe. To select this sample recipe as 3245 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
3182 the one built to provide the initramfs image, set 3246 in the Yocto Project Development Tasks Manual.
3183 INITRAMFS_IMAGE 3247
3184 to "core-image-minimal-initramfs". 3248 INITRAMFS_LINK_NAME
3185 3249 The link name of the initial RAM filesystem image. This variable is
3186 You can also find more information by referencing the 3250 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3187 ``meta-poky/conf/local.conf.sample.extended`` configuration file in 3251 follows: INITRAMFS_LINK_NAME ?=
3188 the Source Directory, the ```image`` <#ref-classes-image>`__ class, 3252 "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" The value of the
3189 and the ```kernel`` <#ref-classes-kernel>`__ class to see how to use 3253 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3190 the ``INITRAMFS_IMAGE`` variable. 3254 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
3191 3255 "${MACHINE}"
3192 If ``INITRAMFS_IMAGE`` is empty, which is the default, then no 3256
3193 initramfs image is built. 3257 See the :term:`MACHINE` variable for additional
3194 3258 information.
3195 For more information, you can also see the 3259
3196 ```INITRAMFS_IMAGE_BUNDLE`` <#var-INITRAMFS_IMAGE_BUNDLE>`__ 3260 INITRAMFS_NAME
3197 variable, which allows the generated image to be bundled inside the 3261 The base name of the initial RAM filesystem image. This variable is
3198 kernel image. Additionally, for information on creating an initramfs 3262 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3199 image, see the "`Building an Initial RAM Filesystem (initramfs) 3263 follows: INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" The
3200 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section 3264 value of the :term:`KERNEL_ARTIFACT_NAME`
3201 in the Yocto Project Development Tasks Manual. 3265 variable, which is set in the same file, has the following value:
3202 3266 KERNEL_ARTIFACT_NAME ?=
3203INITRAMFS_IMAGE_BUNDLE 3267 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3204 Controls whether or not the image recipe specified by 3268
3205 ```INITRAMFS_IMAGE`` <#var-INITRAMFS_IMAGE>`__ is run through an 3269 INITRD
3206 extra pass 3270 Indicates list of filesystem images to concatenate and use as an
3207 (```do_bundle_initramfs`` <#ref-tasks-bundle_initramfs>`__) during 3271 initial RAM disk (``initrd``).
3208 kernel compilation in order to build a single binary that contains 3272
3209 both the kernel image and the initial RAM filesystem (initramfs) 3273 The ``INITRD`` variable is an optional variable used with the
3210 image. This makes use of the 3274 :ref:`image-live <ref-classes-image-live>` class.
3211 ```CONFIG_INITRAMFS_SOURCE`` <#var-CONFIG_INITRAMFS_SOURCE>`__ kernel 3275
3212 feature. 3276 INITRD_IMAGE
3213 3277 When building a "live" bootable image (i.e. when
3214 .. note:: 3278 :term:`IMAGE_FSTYPES` contains "live"),
3215 3279 ``INITRD_IMAGE`` specifies the image recipe that should be built to
3216 Using an extra compilation pass to bundle the initramfs avoids a 3280 provide the initial RAM disk image. The default value is
3217 circular dependency between the kernel recipe and the initramfs 3281 "core-image-minimal-initramfs".
3218 recipe should the initramfs include kernel modules. Should that be 3282
3219 the case, the initramfs recipe depends on the kernel for the 3283 See the :ref:`image-live <ref-classes-image-live>` class for more
3220 kernel modules, and the kernel depends on the initramfs recipe 3284 information.
3221 since the initramfs is bundled inside the kernel image. 3285
3222 3286 INITSCRIPT_NAME
3223 The combined binary is deposited into the ``tmp/deploy`` directory, 3287 The filename of the initialization script as installed to
3224 which is part of the `Build Directory <#build-directory>`__. 3288 ``${sysconfdir}/init.d``.
3225 3289
3226 Setting the variable to "1" in a configuration file causes the 3290 This variable is used in recipes when using ``update-rc.d.bbclass``.
3227 OpenEmbedded build system to generate a kernel image with the 3291 The variable is mandatory.
3228 initramfs specified in ``INITRAMFS_IMAGE`` bundled within: 3292
3229 INITRAMFS_IMAGE_BUNDLE = "1" By default, the 3293 INITSCRIPT_PACKAGES
3230 ```kernel`` <#ref-classes-kernel>`__ class sets this variable to a 3294 A list of the packages that contain initscripts. If multiple packages
3231 null string as follows: INITRAMFS_IMAGE_BUNDLE ?= "" 3295 are specified, you need to append the package name to the other
3232 3296 ``INITSCRIPT_*`` as an override.
3233 .. note:: 3297
3234 3298 This variable is used in recipes when using ``update-rc.d.bbclass``.
3235 You must set the 3299 The variable is optional and defaults to the :term:`PN`
3236 INITRAMFS_IMAGE_BUNDLE
3237 variable in a configuration file. You cannot set the variable in a
3238 recipe file.
3239
3240 See the
3241 ```local.conf.sample.extended`` <&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>`__
3242 file for additional information. Also, for information on creating an
3243 initramfs, see the "`Building an Initial RAM Filesystem (initramfs)
3244 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
3245 in the Yocto Project Development Tasks Manual.
3246
3247INITRAMFS_LINK_NAME
3248 The link name of the initial RAM filesystem image. This variable is
3249 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3250 follows: INITRAMFS_LINK_NAME ?=
3251 "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" The value of the
3252 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3253 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
3254 "${MACHINE}"
3255
3256 See the ```MACHINE`` <#var-MACHINE>`__ variable for additional
3257 information.
3258
3259INITRAMFS_NAME
3260 The base name of the initial RAM filesystem image. This variable is
3261 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3262 follows: INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" The
3263 value of the ```KERNEL_ARTIFACT_NAME`` <#var-KERNEL_ARTIFACT_NAME>`__
3264 variable, which is set in the same file, has the following value:
3265 KERNEL_ARTIFACT_NAME ?=
3266 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3267
3268INITRD
3269 Indicates list of filesystem images to concatenate and use as an
3270 initial RAM disk (``initrd``).
3271
3272 The ``INITRD`` variable is an optional variable used with the
3273 ```image-live`` <#ref-classes-image-live>`__ class.
3274
3275INITRD_IMAGE
3276 When building a "live" bootable image (i.e. when
3277 ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ contains "live"),
3278 ``INITRD_IMAGE`` specifies the image recipe that should be built to
3279 provide the initial RAM disk image. The default value is
3280 "core-image-minimal-initramfs".
3281
3282 See the ```image-live`` <#ref-classes-image-live>`__ class for more
3283 information.
3284
3285INITSCRIPT_NAME
3286 The filename of the initialization script as installed to
3287 ``${sysconfdir}/init.d``.
3288
3289 This variable is used in recipes when using ``update-rc.d.bbclass``.
3290 The variable is mandatory.
3291
3292INITSCRIPT_PACKAGES
3293 A list of the packages that contain initscripts. If multiple packages
3294 are specified, you need to append the package name to the other
3295 ``INITSCRIPT_*`` as an override.
3296
3297 This variable is used in recipes when using ``update-rc.d.bbclass``.
3298 The variable is optional and defaults to the ```PN`` <#var-PN>`__
3299 variable.
3300
3301INITSCRIPT_PARAMS
3302 Specifies the options to pass to ``update-rc.d``. Here is an example:
3303 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3304
3305 In this example, the script has a runlevel of 99, starts the script
3306 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3307
3308 The variable's default value is "defaults", which is set in the
3309 ```update-rc.d`` <#ref-classes-update-rc.d>`__ class.
3310
3311 The value in ``INITSCRIPT_PARAMS`` is passed through to the
3312 ``update-rc.d`` command. For more information on valid parameters,
3313 please see the ``update-rc.d`` manual page at
3314 ` <http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d>`__.
3315
3316INSANE_SKIP
3317 Specifies the QA checks to skip for a specific package within a
3318 recipe. For example, to skip the check for symbolic link ``.so``
3319 files in the main package of a recipe, add the following to the
3320 recipe. The package name override must be used, which in this example
3321 is ``${PN}``: INSANE_SKIP_${PN} += "dev-so"
3322
3323 See the "```insane.bbclass`` <#ref-classes-insane>`__" section for a
3324 list of the valid QA checks you can specify using this variable.
3325
3326INSTALL_TIMEZONE_FILE
3327 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
3328 Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the
3329 configuration level to disable this behavior.
3330
3331IPK_FEED_URIS
3332 When the IPK backend is in use and package management is enabled on
3333 the target, you can use this variable to set up ``opkg`` in the
3334 target image to point to package feeds on a nominated server. Once
3335 the feed is established, you can perform installations or upgrades
3336 using the package manager at runtime.
3337
3338KARCH
3339 Defines the kernel architecture used when assembling the
3340 configuration. Architectures supported for this release are: powerpc
3341 i386 x86_64 arm qemu mips
3342
3343 You define the ``KARCH`` variable in the `BSP
3344 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__.
3345
3346KBRANCH
3347 A regular expression used by the build process to explicitly identify
3348 the kernel branch that is validated, patched, and configured during a
3349 build. You must set this variable to ensure the exact kernel branch
3350 you want is being used by the build process.
3351
3352 Values for this variable are set in the kernel's recipe file and the
3353 kernel's append file. For example, if you are using the
3354 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
3355 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH``
3356 is set as follows in that kernel recipe file: KBRANCH ?=
3357 "standard/base"
3358
3359 This variable is also used from the kernel's append file to identify
3360 the kernel branch specific to a particular machine or target
3361 hardware. Continuing with the previous kernel example, the kernel's
3362 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the
3363 BSP layer for a given machine. For example, the append file for the
3364 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA
3365 machines (``meta-yocto-bsp``) is named
3366 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
3367 Here are the related statements from that append file:
3368 KBRANCH_genericx86 = "standard/base" KBRANCH_genericx86-64 =
3369 "standard/base" KBRANCH_edgerouter = "standard/edgerouter"
3370 KBRANCH_beaglebone = "standard/beaglebone" The ``KBRANCH`` statements
3371 identify the kernel branch to use when building for each supported
3372 BSP.
3373
3374KBUILD_DEFCONFIG
3375 When used with the ```kernel-yocto`` <#ref-classes-kernel-yocto>`__
3376 class, specifies an "in-tree" kernel configuration file for use
3377 during a kernel build.
3378
3379 Typically, when using a ``defconfig`` to configure a kernel during a
3380 build, you place the file in your layer in the same manner as you
3381 would place patch files and configuration fragment files (i.e.
3382 "out-of-tree"). However, if you want to use a ``defconfig`` file that
3383 is part of the kernel tree (i.e. "in-tree"), you can use the
3384 ``KBUILD_DEFCONFIG`` variable and append the
3385 ```KMACHINE`` <#var-KMACHINE>`__ variable to point to the
3386 ``defconfig`` file.
3387
3388 To use the variable, set it in the append file for your kernel recipe
3389 using the following form: KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
3390 Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses
3391 a ``defconfig`` file named "bcm2709_defconfig":
3392 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" As an
3393 alternative, you can use the following within your append file:
3394 KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file For more
3395 information on how to use the ``KBUILD_DEFCONFIG`` variable, see the
3396 "`Using an "In-Tree" ``defconfig``
3397 File <&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file>`__"
3398 section in the Yocto Project Linux Kernel Development Manual.
3399
3400KERNEL_ALT_IMAGETYPE
3401 Specifies an alternate kernel image type for creation in addition to
3402 the kernel image type specified using the
3403 ```KERNEL_IMAGETYPE`` <#var-KERNEL_IMAGETYPE>`__ variable.
3404
3405KERNEL_ARTIFACT_NAME
3406 Specifies the name of all of the build artifacts. You can change the
3407 name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME``
3408 variable.
3409
3410 The value of ``KERNEL_ARTIFACT_NAME``, which is set in the
3411 ``meta/classes/kernel-artifact-names.bbclass`` file, has the
3412 following default value: KERNEL_ARTIFACT_NAME ?=
3413 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3414
3415 See the ```PKGE`` <#var-PKGE>`__, ```PKGV`` <#var-PKGV>`__,
3416 ```PKGR`` <#var-PKGR>`__, and ```MACHINE`` <#var-MACHINE>`__
3417 variables for additional information.
3418
3419 .. note::
3420
3421 The
3422 IMAGE_VERSION_SUFFIX
3423 variable is set to
3424 DATETIME
3425 .
3426
3427KERNEL_CLASSES
3428 A list of classes defining kernel image types that the
3429 ```kernel`` <#ref-classes-kernel>`__ class should inherit. You
3430 typically append this variable to enable extended image types. An
3431 example is the "kernel-fitimage", which enables fitImage support and
3432 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register
3433 custom kernel image types with the ``kernel`` class using this
3434 variable.
3435
3436KERNEL_DEVICETREE
3437 Specifies the name of the generated Linux kernel device tree (i.e.
3438 the ``.dtb``) file.
3439
3440 .. note::
3441
3442 Legacy support exists for specifying the full path to the device
3443 tree. However, providing just the
3444 .dtb
3445 file is preferred.
3446
3447 In order to use this variable, the
3448 ```kernel-devicetree`` <#ref-classes-kernel-devicetree>`__ class must
3449 be inherited.
3450
3451KERNEL_DTB_LINK_NAME
3452 The link name of the kernel device tree binary (DTB). This variable
3453 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3454 follows: KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The
3455 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
3456 the same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
3457 "${MACHINE}"
3458
3459 See the ```MACHINE`` <#var-MACHINE>`__ variable for additional
3460 information.
3461
3462KERNEL_DTB_NAME
3463 The base name of the kernel device tree binary (DTB). This variable
3464 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3465 follows: KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of
3466 the ```KERNEL_ARTIFACT_NAME`` <#var-KERNEL_ARTIFACT_NAME>`__
3467 variable, which is set in the same file, has the following value:
3468 KERNEL_ARTIFACT_NAME ?=
3469 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3470
3471KERNEL_EXTRA_ARGS
3472 Specifies additional ``make`` command-line arguments the OpenEmbedded
3473 build system passes on when compiling the kernel.
3474
3475KERNEL_FEATURES
3476 Includes additional kernel metadata. In the OpenEmbedded build
3477 system, the default Board Support Packages (BSPs)
3478 `Metadata <#metadata>`__ is provided through the
3479 ```KMACHINE`` <#var-KMACHINE>`__ and ```KBRANCH`` <#var-KBRANCH>`__
3480 variables. You can use the ``KERNEL_FEATURES`` variable from within
3481 the kernel recipe or kernel append file to further add metadata for
3482 all BSPs or specific BSPs.
3483
3484 The metadata you add through this variable includes config fragments
3485 and features descriptions, which usually includes patches as well as
3486 config fragments. You typically override the ``KERNEL_FEATURES``
3487 variable for a specific machine. In this way, you can provide
3488 validated, but optional, sets of kernel configurations and features.
3489
3490 For example, the following example from the ``linux-yocto-rt_4.12``
3491 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
3492 as well as "virtio" configurations to all QEMU machines. The last two
3493 statements add specific configurations to targeted machine types:
3494 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc
3495 features/taskstats/taskstats.scc" KERNEL_FEATURES_append = "
3496 ${KERNEL_EXTRA_FEATURES}" KERNEL_FEATURES_append_qemuall = "
3497 cfg/virtio.scc" KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc
3498 cfg/paravirt_kvm.scc" KERNEL_FEATURES_append_qemux86-64 = "
3499 cfg/sound.scc"
3500
3501KERNEL_FIT_LINK_NAME
3502 The link name of the kernel flattened image tree (FIT) image. This
3503 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
3504 file as follows: KERNEL_FIT_LINK_NAME ?=
3505 "${KERNEL_ARTIFACT_LINK_NAME}" The value of the
3506 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3507 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
3508 "${MACHINE}"
3509
3510 See the ```MACHINE`` <#var-MACHINE>`__ variable for additional
3511 information.
3512
3513KERNEL_FIT_NAME
3514 The base name of the kernel flattened image tree (FIT) image. This
3515 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
3516 file as follows: KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" The
3517 value of the ```KERNEL_ARTIFACT_NAME`` <#var-KERNEL_ARTIFACT_NAME>`__
3518 variable, which is set in the same file, has the following value:
3519 KERNEL_ARTIFACT_NAME ?=
3520 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3521
3522KERNEL_IMAGE_LINK_NAME
3523 The link name for the kernel image. This variable is set in the
3524 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
3525 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of
3526 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3527 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
3528 "${MACHINE}"
3529
3530 See the ```MACHINE`` <#var-MACHINE>`__ variable for additional
3531 information.
3532
3533KERNEL_IMAGE_MAXSIZE
3534 Specifies the maximum size of the kernel image file in kilobytes. If
3535 ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is
3536 checked against the set value during the
3537 ```do_sizecheck`` <#ref-tasks-sizecheck>`__ task. The task fails if
3538 the kernel image file is larger than the setting.
3539
3540 ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a
3541 limited amount of space in which the kernel image must be stored.
3542
3543 By default, this variable is not set, which means the size of the
3544 kernel image is not checked.
3545
3546KERNEL_IMAGE_NAME
3547 The base name of the kernel image. This variable is set in the
3548 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
3549 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the
3550 ```KERNEL_ARTIFACT_NAME`` <#var-KERNEL_ARTIFACT_NAME>`__ variable,
3551 which is set in the same file, has the following value:
3552 KERNEL_ARTIFACT_NAME ?=
3553 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3554
3555KERNEL_IMAGETYPE
3556 The type of kernel to build for a device, usually set by the machine
3557 configuration files and defaults to "zImage". This variable is used
3558 when building the kernel and is passed to ``make`` as the target to
3559 build.
3560
3561 If you want to build an alternate kernel image type, use the
3562 ```KERNEL_ALT_IMAGETYPE`` <#var-KERNEL_ALT_IMAGETYPE>`__ variable.
3563
3564KERNEL_MODULE_AUTOLOAD
3565 Lists kernel modules that need to be auto-loaded during boot.
3566
3567 .. note::
3568
3569 This variable replaces the deprecated
3570 module_autoload
3571 variable. 3300 variable.
3572 3301
3573 You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it 3302 INITSCRIPT_PARAMS
3574 can be recognized by the kernel recipe or by an out-of-tree kernel 3303 Specifies the options to pass to ``update-rc.d``. Here is an example:
3575 module recipe (e.g. a machine configuration file, a distribution 3304 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3576 configuration file, an append file for the recipe, or the recipe 3305
3577 itself). 3306 In this example, the script has a runlevel of 99, starts the script
3578 3307 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3579 Specify it as follows: KERNEL_MODULE_AUTOLOAD += "module_name1 3308
3580 module_name2 module_name3" 3309 The variable's default value is "defaults", which is set in the
3581 3310 :ref:`update-rc.d <ref-classes-update-rc.d>` class.
3582 Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build 3311
3583 system to populate the ``/etc/modules-load.d/modname.conf`` file with 3312 The value in ``INITSCRIPT_PARAMS`` is passed through to the
3584 the list of modules to be auto-loaded on boot. The modules appear 3313 ``update-rc.d`` command. For more information on valid parameters,
3585 one-per-line in the file. Here is an example of the most common use 3314 please see the ``update-rc.d`` manual page at
3586 case: KERNEL_MODULE_AUTOLOAD += "module_name" 3315 http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d.
3587 3316
3588 For information on how to populate the ``modname.conf`` file with 3317 INSANE_SKIP
3589 ``modprobe.d`` syntax lines, see the 3318 Specifies the QA checks to skip for a specific package within a
3590 ```KERNEL_MODULE_PROBECONF`` <#var-KERNEL_MODULE_PROBECONF>`__ 3319 recipe. For example, to skip the check for symbolic link ``.so``
3591 variable. 3320 files in the main package of a recipe, add the following to the
3592 3321 recipe. The package name override must be used, which in this example
3593KERNEL_MODULE_PROBECONF 3322 is ``${PN}``: INSANE_SKIP_${PN} += "dev-so"
3594 Provides a list of modules for which the OpenEmbedded build system 3323
3595 expects to find ``module_conf_``\ modname values that specify 3324 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a
3596 configuration for each of the modules. For information on how to 3325 list of the valid QA checks you can specify using this variable.
3597 provide those module configurations, see the 3326
3598 ```module_conf_*`` <#var-module_conf>`__ variable. 3327 INSTALL_TIMEZONE_FILE
3599 3328 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
3600KERNEL_PATH 3329 Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the
3601 The location of the kernel sources. This variable is set to the value 3330 configuration level to disable this behavior.
3602 of the ```STAGING_KERNEL_DIR`` <#var-STAGING_KERNEL_DIR>`__ within 3331
3603 the ```module`` <#ref-classes-module>`__ class. For information on 3332 IPK_FEED_URIS
3604 how this variable is used, see the "`Incorporating Out-of-Tree 3333 When the IPK backend is in use and package management is enabled on
3605 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__" 3334 the target, you can use this variable to set up ``opkg`` in the
3606 section in the Yocto Project Linux Kernel Development Manual. 3335 target image to point to package feeds on a nominated server. Once
3607 3336 the feed is established, you can perform installations or upgrades
3608 To help maximize compatibility with out-of-tree drivers used to build 3337 using the package manager at runtime.
3609 modules, the OpenEmbedded build system also recognizes and uses the 3338
3610 ```KERNEL_SRC`` <#var-KERNEL_SRC>`__ variable, which is identical to 3339 KARCH
3611 the ``KERNEL_PATH`` variable. Both variables are common variables 3340 Defines the kernel architecture used when assembling the
3612 used by external Makefiles to point to the kernel source directory. 3341 configuration. Architectures supported for this release are: powerpc
3613 3342 i386 x86_64 arm qemu mips
3614KERNEL_SRC 3343
3615 The location of the kernel sources. This variable is set to the value 3344 You define the ``KARCH`` variable in the `BSP
3616 of the ```STAGING_KERNEL_DIR`` <#var-STAGING_KERNEL_DIR>`__ within 3345 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__.
3617 the ```module`` <#ref-classes-module>`__ class. For information on 3346
3618 how this variable is used, see the "`Incorporating Out-of-Tree 3347 KBRANCH
3619 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__" 3348 A regular expression used by the build process to explicitly identify
3620 section in the Yocto Project Linux Kernel Development Manual. 3349 the kernel branch that is validated, patched, and configured during a
3621 3350 build. You must set this variable to ensure the exact kernel branch
3622 To help maximize compatibility with out-of-tree drivers used to build 3351 you want is being used by the build process.
3623 modules, the OpenEmbedded build system also recognizes and uses the 3352
3624 ```KERNEL_PATH`` <#var-KERNEL_PATH>`__ variable, which is identical 3353 Values for this variable are set in the kernel's recipe file and the
3625 to the ``KERNEL_SRC`` variable. Both variables are common variables 3354 kernel's append file. For example, if you are using the
3626 used by external Makefiles to point to the kernel source directory. 3355 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
3627 3356 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH``
3628KERNEL_VERSION 3357 is set as follows in that kernel recipe file: KBRANCH ?=
3629 Specifies the version of the kernel as extracted from ``version.h`` 3358 "standard/base"
3630 or ``utsrelease.h`` within the kernel sources. Effects of setting 3359
3631 this variable do not take affect until the kernel has been 3360 This variable is also used from the kernel's append file to identify
3632 configured. Consequently, attempting to refer to this variable in 3361 the kernel branch specific to a particular machine or target
3633 contexts prior to configuration will not work. 3362 hardware. Continuing with the previous kernel example, the kernel's
3634 3363 append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the
3635KERNELDEPMODDEPEND 3364 BSP layer for a given machine. For example, the append file for the
3636 Specifies whether the data referenced through 3365 Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA
3637 ```PKGDATA_DIR`` <#var-PKGDATA_DIR>`__ is needed or not. The 3366 machines (``meta-yocto-bsp``) is named
3638 ``KERNELDEPMODDEPEND`` does not control whether or not that data 3367 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
3639 exists, but simply whether or not it is used. If you do not need to 3368 Here are the related statements from that append file:
3640 use the data, set the ``KERNELDEPMODDEPEND`` variable in your 3369 KBRANCH_genericx86 = "standard/base" KBRANCH_genericx86-64 =
3641 ``initramfs`` recipe. Setting the variable there when the data is not 3370 "standard/base" KBRANCH_edgerouter = "standard/edgerouter"
3642 needed avoids a potential dependency loop. 3371 KBRANCH_beaglebone = "standard/beaglebone" The ``KBRANCH`` statements
3643 3372 identify the kernel branch to use when building for each supported
3644KFEATURE_DESCRIPTION 3373 BSP.
3645 Provides a short description of a configuration fragment. You use 3374
3646 this variable in the ``.scc`` file that describes a configuration 3375 KBUILD_DEFCONFIG
3647 fragment file. Here is the variable used in a file named ``smp.scc`` 3376 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3648 to describe SMP being enabled: define KFEATURE_DESCRIPTION "Enable 3377 class, specifies an "in-tree" kernel configuration file for use
3649 SMP" 3378 during a kernel build.
3650 3379
3651KMACHINE 3380 Typically, when using a ``defconfig`` to configure a kernel during a
3652 The machine as known by the kernel. Sometimes the machine name used 3381 build, you place the file in your layer in the same manner as you
3653 by the kernel does not match the machine name used by the 3382 would place patch files and configuration fragment files (i.e.
3654 OpenEmbedded build system. For example, the machine name that the 3383 "out-of-tree"). However, if you want to use a ``defconfig`` file that
3655 OpenEmbedded build system understands as ``core2-32-intel-common`` 3384 is part of the kernel tree (i.e. "in-tree"), you can use the
3656 goes by a different name in the Linux Yocto kernel. The kernel 3385 ``KBUILD_DEFCONFIG`` variable and append the
3657 understands that machine as ``intel-core2-32``. For cases like these, 3386 :term:`KMACHINE` variable to point to the
3658 the ``KMACHINE`` variable maps the kernel machine name to the 3387 ``defconfig`` file.
3659 OpenEmbedded build system machine name. 3388
3660 3389 To use the variable, set it in the append file for your kernel recipe
3661 These mappings between different names occur in the Yocto Linux 3390 using the following form: KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
3662 Kernel's ``meta`` branch. As an example take a look in the 3391 Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses
3663 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: 3392 a ``defconfig`` file named "bcm2709_defconfig":
3664 LINUX_VERSION_core2-32-intel-common = "3.19.0" 3393 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" As an
3665 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" 3394 alternative, you can use the following within your append file:
3666 SRCREV_meta_core2-32-intel-common = 3395 KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file For more
3667 "8897ef68b30e7426bc1d39895e71fb155d694974" 3396 information on how to use the ``KBUILD_DEFCONFIG`` variable, see the
3668 SRCREV_machine_core2-32-intel-common = 3397 "`Using an "In-Tree" ``defconfig``
3669 "43b9eced9ba8a57add36af07736344dcc383f711" 3398 File <&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file>`__"
3670 KMACHINE_core2-32-intel-common = "intel-core2-32" 3399 section in the Yocto Project Linux Kernel Development Manual.
3671 KBRANCH_core2-32-intel-common = "standard/base" 3400
3672 KERNEL_FEATURES_append_core2-32-intel-common = 3401 KERNEL_ALT_IMAGETYPE
3673 "${KERNEL_FEATURES_INTEL_COMMON}" The ``KMACHINE`` statement says 3402 Specifies an alternate kernel image type for creation in addition to
3674 that the kernel understands the machine name as "intel-core2-32". 3403 the kernel image type specified using the
3675 However, the OpenEmbedded build system understands the machine as 3404 :term:`KERNEL_IMAGETYPE` variable.
3676 "core2-32-intel-common". 3405
3677 3406 KERNEL_ARTIFACT_NAME
3678KTYPE 3407 Specifies the name of all of the build artifacts. You can change the
3679 Defines the kernel type to be used in assembling the configuration. 3408 name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME``
3680 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
3681 kernel types. See the "`Kernel
3682 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the
3683 Yocto Project Linux Kernel Development Manual for more information on
3684 kernel types.
3685
3686 You define the ``KTYPE`` variable in the `BSP
3687 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__. The
3688 value you use must match the value used for the
3689 ```LINUX_KERNEL_TYPE`` <#var-LINUX_KERNEL_TYPE>`__ value used by the
3690 kernel recipe.
3691
3692LABELS
3693 Provides a list of targets for automatic configuration.
3694
3695 See the ```grub-efi`` <#ref-classes-grub-efi>`__ class for more
3696 information on how this variable is used.
3697
3698LAYERDEPENDS
3699 Lists the layers, separated by spaces, on which this recipe depends.
3700 Optionally, you can specify a specific layer version for a dependency
3701 by adding it to the end of the layer name. Here is an example:
3702 LAYERDEPENDS_mylayer = "anotherlayer (=3)" In this previous example,
3703 version 3 of "anotherlayer" is compared against
3704 ```LAYERVERSION`` <#var-LAYERVERSION>`__\ ``_anotherlayer``.
3705
3706 An error is produced if any dependency is missing or the version
3707 numbers (if specified) do not match exactly. This variable is used in
3708 the ``conf/layer.conf`` file and must be suffixed with the name of
3709 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
3710
3711LAYERDIR
3712 When used inside the ``layer.conf`` configuration file, this variable
3713 provides the path of the current layer. This variable is not
3714 available outside of ``layer.conf`` and references are expanded
3715 immediately when parsing of the file completes.
3716
3717LAYERRECOMMENDS
3718 Lists the layers, separated by spaces, recommended for use with this
3719 layer.
3720
3721 Optionally, you can specify a specific layer version for a
3722 recommendation by adding the version to the end of the layer name.
3723 Here is an example: LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" In
3724 this previous example, version 3 of "anotherlayer" is compared
3725 against ``LAYERVERSION_anotherlayer``.
3726
3727 This variable is used in the ``conf/layer.conf`` file and must be
3728 suffixed with the name of the specific layer (e.g.
3729 ``LAYERRECOMMENDS_mylayer``).
3730
3731LAYERSERIES_COMPAT
3732 Lists the versions of the `OpenEmbedded-Core <#oe-core>`__ for which
3733 a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable
3734 allows the layer maintainer to indicate which combinations of the
3735 layer and OE-Core can be expected to work. The variable gives the
3736 system a way to detect when a layer has not been tested with new
3737 releases of OE-Core (e.g. the layer is not maintained).
3738
3739 To specify the OE-Core versions for which a layer is compatible, use
3740 this variable in your layer's ``conf/layer.conf`` configuration file.
3741 For the list, use the Yocto Project `Release
3742 Name <https://wiki.yoctoproject.org/wiki/Releases>`__ (e.g.
3743 DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the
3744 layer, use a space-separated list: LAYERSERIES_COMPAT_layer_root_name
3745 = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE"
3746
3747 .. note::
3748
3749 Setting
3750 LAYERSERIES_COMPAT
3751 is required by the Yocto Project Compatible version 2 standard.
3752 The OpenEmbedded build system produces a warning if the variable
3753 is not set for any given layer.
3754
3755 See the "`Creating Your Own
3756 Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in
3757 the Yocto Project Development Tasks Manual.
3758
3759LAYERVERSION
3760 Optionally specifies the version of a layer as a single number. You
3761 can use this within ```LAYERDEPENDS`` <#var-LAYERDEPENDS>`__ for
3762 another layer in order to depend on a specific version of the layer.
3763 This variable is used in the ``conf/layer.conf`` file and must be
3764 suffixed with the name of the specific layer (e.g.
3765 ``LAYERVERSION_mylayer``).
3766
3767LD
3768 The minimal command and arguments used to run the linker.
3769
3770LDFLAGS
3771 Specifies the flags to pass to the linker. This variable is exported
3772 to an environment variable and thus made visible to the software
3773 being built during the compilation step.
3774
3775 Default initialization for ``LDFLAGS`` varies depending on what is
3776 being built:
3777
3778 - ```TARGET_LDFLAGS`` <#var-TARGET_LDFLAGS>`__ when building for the
3779 target
3780
3781 - ```BUILD_LDFLAGS`` <#var-BUILD_LDFLAGS>`__ when building for the
3782 build host (i.e. ``-native``)
3783
3784 - ```BUILDSDK_LDFLAGS`` <#var-BUILDSDK_LDFLAGS>`__ when building for
3785 an SDK (i.e. ``nativesdk-``)
3786
3787LEAD_SONAME
3788 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
3789 that the ```debian`` <#ref-classes-debian>`__ class applies its
3790 naming policy to given a recipe that packages multiple libraries.
3791
3792 This variable works in conjunction with the ``debian`` class.
3793
3794LIC_FILES_CHKSUM
3795 Checksums of the license text in the recipe source code.
3796
3797 This variable tracks changes in license text of the source code
3798 files. If the license text is changed, it will trigger a build
3799 failure, which gives the developer an opportunity to review any
3800 license change.
3801
3802 This variable must be defined for all recipes (unless
3803 ```LICENSE`` <#var-LICENSE>`__ is set to "CLOSED").
3804
3805 For more information, see the "`Tracking License
3806 Changes <&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM>`__"
3807 section in the Yocto Project Development Tasks Manual.
3808
3809LICENSE
3810 The list of source licenses for the recipe. Follow these rules:
3811
3812 - Do not use spaces within individual license names.
3813
3814 - Separate license names using \| (pipe) when there is a choice
3815 between licenses.
3816
3817 - Separate license names using & (ampersand) when multiple licenses
3818 exist that cover different parts of the source.
3819
3820 - You can use spaces between license names.
3821
3822 - For standard licenses, use the names of the files in
3823 ``meta/files/common-licenses/`` or the
3824 ```SPDXLICENSEMAP`` <#var-SPDXLICENSEMAP>`__ flag names defined in
3825 ``meta/conf/licenses.conf``.
3826
3827 Here are some examples: LICENSE = "LGPLv2.1 \| GPLv3" LICENSE =
3828 "MPL-1 & LGPLv2.1" LICENSE = "GPLv2+" The first example is from the
3829 recipes for Qt, which the user may choose to distribute under either
3830 the LGPL version 2.1 or GPL version 3. The second example is from
3831 Cairo where two licenses cover different parts of the source code.
3832 The final example is from ``sysstat``, which presents a single
3833 license.
3834
3835 You can also specify licenses on a per-package basis to handle
3836 situations where components of the output have different licenses.
3837 For example, a piece of software whose code is licensed under GPLv2
3838 but has accompanying documentation licensed under the GNU Free
3839 Documentation License 1.2 could be specified as follows: LICENSE =
3840 "GFDL-1.2 & GPLv2" LICENSE_${PN} = "GPLv2" LICENSE_${PN}-doc =
3841 "GFDL-1.2"
3842
3843LICENSE_CREATE_PACKAGE
3844 Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded
3845 build system to create an extra package (i.e.
3846 ``${``\ ```PN`` <#var-PN>`__\ ``}-lic``) for each recipe and to add
3847 those packages to the
3848 ```RRECOMMENDS`` <#var-RRECOMMENDS>`__\ ``_${PN}``.
3849
3850 The ``${PN}-lic`` package installs a directory in
3851 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
3852 name, and installs files in that directory that contain license and
3853 copyright information (i.e. copies of the appropriate license files
3854 from ``meta/common-licenses`` that match the licenses specified in
3855 the ```LICENSE`` <#var-LICENSE>`__ variable of the recipe metadata
3856 and copies of files marked in
3857 ```LIC_FILES_CHKSUM`` <#var-LIC_FILES_CHKSUM>`__ as containing
3858 license text).
3859
3860 For related information on providing license text, see the
3861 ```COPY_LIC_DIRS`` <#var-COPY_LIC_DIRS>`__ variable, the
3862 ```COPY_LIC_MANIFEST`` <#var-COPY_LIC_MANIFEST>`__ variable, and the
3863 "`Providing License
3864 Text <&YOCTO_DOCS_DEV_URL;#providing-license-text>`__" section in the
3865 Yocto Project Development Tasks Manual.
3866
3867LICENSE_FLAGS
3868 Specifies additional flags for a recipe you must whitelist through
3869 ```LICENSE_FLAGS_WHITELIST`` <#var-LICENSE_FLAGS_WHITELIST>`__ in
3870 order to allow the recipe to be built. When providing multiple flags,
3871 separate them with spaces.
3872
3873 This value is independent of ```LICENSE`` <#var-LICENSE>`__ and is
3874 typically used to mark recipes that might require additional licenses
3875 in order to be used in a commercial product. For more information,
3876 see the "`Enabling Commercially Licensed
3877 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__"
3878 section in the Yocto Project Development Tasks Manual.
3879
3880LICENSE_FLAGS_WHITELIST
3881 Lists license flags that when specified in
3882 ```LICENSE_FLAGS`` <#var-LICENSE_FLAGS>`__ within a recipe should not
3883 prevent that recipe from being built. This practice is otherwise
3884 known as "whitelisting" license flags. For more information, see the
3885 "`Enabling Commercially Licensed
3886 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__"
3887 section in the Yocto Project Development Tasks Manual.
3888
3889LICENSE_PATH
3890 Path to additional licenses used during the build. By default, the
3891 OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the
3892 directory that holds common license text used during the build. The
3893 ``LICENSE_PATH`` variable allows you to extend that location to other
3894 areas that have additional licenses: LICENSE_PATH +=
3895 "path-to-additional-common-licenses"
3896
3897LINUX_KERNEL_TYPE
3898 Defines the kernel type to be used in assembling the configuration.
3899 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
3900 kernel types. See the "`Kernel
3901 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the
3902 Yocto Project Linux Kernel Development Manual for more information on
3903 kernel types.
3904
3905 If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to
3906 "standard". Together with ```KMACHINE`` <#var-KMACHINE>`__, the
3907 ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by
3908 the kernel tools to find the appropriate description within the
3909 kernel `Metadata <#metadata>`__ with which to build out the sources
3910 and configuration.
3911
3912LINUX_VERSION
3913 The Linux version from ``kernel.org`` on which the Linux kernel image
3914 being built using the OpenEmbedded build system is based. You define
3915 this variable in the kernel recipe. For example, the
3916 ``linux-yocto-3.4.bb`` kernel recipe found in
3917 ``meta/recipes-kernel/linux`` defines the variables as follows:
3918 LINUX_VERSION ?= "3.4.24"
3919
3920 The ``LINUX_VERSION`` variable is used to define ```PV`` <#var-PV>`__
3921 for the recipe: PV = "${LINUX_VERSION}+git${SRCPV}"
3922
3923LINUX_VERSION_EXTENSION
3924 A string extension compiled into the version string of the Linux
3925 kernel built with the OpenEmbedded build system. You define this
3926 variable in the kernel recipe. For example, the linux-yocto kernel
3927 recipes all define the variable as follows: LINUX_VERSION_EXTENSION
3928 ?= "-yocto-${`LINUX_KERNEL_TYPE <#var-LINUX_KERNEL_TYPE>`__}"
3929
3930 Defining this variable essentially sets the Linux kernel
3931 configuration item ``CONFIG_LOCALVERSION``, which is visible through
3932 the ``uname`` command. Here is an example that shows the extension
3933 assuming it was set as previously shown: $ uname -r 3.7.0-rc8-custom
3934
3935LOG_DIR
3936 Specifies the directory to which the OpenEmbedded build system writes
3937 overall log files. The default directory is ``${TMPDIR}/log``.
3938
3939 For the directory containing logs specific to each task, see the
3940 ```T`` <#var-T>`__ variable.
3941
3942MACHINE
3943 Specifies the target device for which the image is built. You define
3944 ``MACHINE`` in the ``local.conf`` file found in the `Build
3945 Directory <#build-directory>`__. By default, ``MACHINE`` is set to
3946 "qemux86", which is an x86-based architecture machine to be emulated
3947 using QEMU: MACHINE ?= "qemux86"
3948
3949 The variable corresponds to a machine configuration file of the same
3950 name, through which machine-specific configurations are set. Thus,
3951 when ``MACHINE`` is set to "qemux86" there exists the corresponding
3952 ``qemux86.conf`` machine configuration file, which can be found in
3953 the `Source Directory <#source-directory>`__ in
3954 ``meta/conf/machine``.
3955
3956 The list of machines supported by the Yocto Project as shipped
3957 include the following: MACHINE ?= "qemuarm" MACHINE ?= "qemuarm64"
3958 MACHINE ?= "qemumips" MACHINE ?= "qemumips64" MACHINE ?= "qemuppc"
3959 MACHINE ?= "qemux86" MACHINE ?= "qemux86-64" MACHINE ?= "genericx86"
3960 MACHINE ?= "genericx86-64" MACHINE ?= "beaglebone" MACHINE ?=
3961 "edgerouter" The last five are Yocto Project reference hardware
3962 boards, which are provided in the ``meta-yocto-bsp`` layer.
3963
3964 .. note::
3965
3966 Adding additional Board Support Package (BSP) layers to your
3967 configuration adds new possible settings for
3968 MACHINE
3969 .
3970
3971MACHINE_ARCH
3972 Specifies the name of the machine-specific architecture. This
3973 variable is set automatically from ```MACHINE`` <#var-MACHINE>`__ or
3974 ```TUNE_PKGARCH`` <#var-TUNE_PKGARCH>`__. You should not hand-edit
3975 the ``MACHINE_ARCH`` variable.
3976
3977MACHINE_ESSENTIAL_EXTRA_RDEPENDS
3978 A list of required machine-specific packages to install as part of
3979 the image being built. The build process depends on these packages
3980 being present. Furthermore, because this is a "machine-essential"
3981 variable, the list of packages are essential for the machine to boot.
3982 The impact of this variable affects images based on
3983 ``packagegroup-core-boot``, including the ``core-image-minimal``
3984 image.
3985
3986 This variable is similar to the
3987 ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception
3988 that the image being built has a build dependency on the variable's
3989 list of packages. In other words, the image will not build if a file
3990 in this list is not found.
3991
3992 As an example, suppose the machine for which you are building
3993 requires ``example-init`` to be run during boot to initialize the
3994 hardware. In this case, you would use the following in the machine's
3995 ``.conf`` configuration file: MACHINE_ESSENTIAL_EXTRA_RDEPENDS +=
3996 "example-init"
3997
3998MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
3999 A list of recommended machine-specific packages to install as part of
4000 the image being built. The build process does not depend on these
4001 packages being present. However, because this is a
4002 "machine-essential" variable, the list of packages are essential for
4003 the machine to boot. The impact of this variable affects images based
4004 on ``packagegroup-core-boot``, including the ``core-image-minimal``
4005 image.
4006
4007 This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS``
4008 variable with the exception that the image being built does not have
4009 a build dependency on the variable's list of packages. In other
4010 words, the image will still build if a package in this list is not
4011 found. Typically, this variable is used to handle essential kernel
4012 modules, whose functionality may be selected to be built into the
4013 kernel rather than as a module, in which case a package will not be
4014 produced.
4015
4016 Consider an example where you have a custom kernel where a specific
4017 touchscreen driver is required for the machine to be usable. However,
4018 the driver can be built as a module or into the kernel depending on
4019 the kernel configuration. If the driver is built as a module, you
4020 want it to be installed. But, when the driver is built into the
4021 kernel, you still want the build to succeed. This variable sets up a
4022 "recommends" relationship so that in the latter case, the build will
4023 not fail due to the missing package. To accomplish this, assuming the
4024 package for the module was called ``kernel-module-ab123``, you would
4025 use the following in the machine's ``.conf`` configuration file:
4026 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4027
4028 .. note::
4029
4030 In this example, the
4031 kernel-module-ab123
4032 recipe needs to explicitly set its
4033 PACKAGES
4034 variable to ensure that BitBake does not use the kernel recipe's
4035 PACKAGES_DYNAMIC
4036 variable to satisfy the dependency.
4037
4038 Some examples of these machine essentials are flash, screen,
4039 keyboard, mouse, or touchscreen drivers (depending on the machine).
4040
4041MACHINE_EXTRA_RDEPENDS
4042 A list of machine-specific packages to install as part of the image
4043 being built that are not essential for the machine to boot. However,
4044 the build process for more fully-featured images depends on the
4045 packages being present.
4046
4047 This variable affects all images based on ``packagegroup-base``,
4048 which does not include the ``core-image-minimal`` or
4049 ``core-image-full-cmdline`` images.
4050
4051 The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable
4052 with the exception that the image being built has a build dependency
4053 on the variable's list of packages. In other words, the image will
4054 not build if a file in this list is not found.
4055
4056 An example is a machine that has WiFi capability but is not essential
4057 for the machine to boot the image. However, if you are building a
4058 more fully-featured image, you want to enable the WiFi. The package
4059 containing the firmware for the WiFi hardware is always expected to
4060 exist, so it is acceptable for the build process to depend upon
4061 finding the package. In this case, assuming the package for the
4062 firmware was called ``wifidriver-firmware``, you would use the
4063 following in the ``.conf`` file for the machine:
4064 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4065
4066MACHINE_EXTRA_RRECOMMENDS
4067 A list of machine-specific packages to install as part of the image
4068 being built that are not essential for booting the machine. The image
4069 being built has no build dependency on this list of packages.
4070
4071 This variable affects only images based on ``packagegroup-base``,
4072 which does not include the ``core-image-minimal`` or
4073 ``core-image-full-cmdline`` images.
4074
4075 This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable
4076 with the exception that the image being built does not have a build
4077 dependency on the variable's list of packages. In other words, the
4078 image will build if a file in this list is not found.
4079
4080 An example is a machine that has WiFi capability but is not essential
4081 For the machine to boot the image. However, if you are building a
4082 more fully-featured image, you want to enable WiFi. In this case, the
4083 package containing the WiFi kernel module will not be produced if the
4084 WiFi driver is built into the kernel, in which case you still want
4085 the build to succeed instead of failing as a result of the package
4086 not being found. To accomplish this, assuming the package for the
4087 module was called ``kernel-module-examplewifi``, you would use the
4088 following in the ``.conf`` file for the machine:
4089 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4090
4091MACHINE_FEATURES
4092 Specifies the list of hardware features the
4093 ```MACHINE`` <#var-MACHINE>`__ is capable of supporting. For related
4094 information on enabling features, see the
4095 ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__,
4096 ```COMBINED_FEATURES`` <#var-COMBINED_FEATURES>`__, and
4097 ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ variables.
4098
4099 For a list of hardware features supported by the Yocto Project as
4100 shipped, see the "`Machine Features <#ref-features-machine>`__"
4101 section.
4102
4103MACHINE_FEATURES_BACKFILL
4104 Features to be added to ``MACHINE_FEATURES`` if not also present in
4105 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``.
4106
4107 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
4108 not intended to be user-configurable. It is best to just reference
4109 the variable to see which machine features are being backfilled for
4110 all machine configurations. See the "`Feature
4111 Backfilling <#ref-features-backfill>`__" section for more
4112 information.
4113
4114MACHINE_FEATURES_BACKFILL_CONSIDERED
4115 Features from ``MACHINE_FEATURES_BACKFILL`` that should not be
4116 backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See
4117 the "`Feature Backfilling <#ref-features-backfill>`__" section for
4118 more information.
4119
4120MACHINEOVERRIDES
4121 A colon-separated list of overrides that apply to the current
4122 machine. By default, this list includes the value of
4123 ```MACHINE`` <#var-MACHINE>`__.
4124
4125 You can extend ``MACHINEOVERRIDES`` to add extra overrides that
4126 should apply to a machine. For example, all machines emulated in QEMU
4127 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
4128 ``meta/conf/machine/include/qemu.inc`` that prepends the following
4129 override to ``MACHINEOVERRIDES``: MACHINEOVERRIDES =. "qemuall:" This
4130 override allows variables to be overriden for all machines emulated
4131 in QEMU, like in the following example from the ``connman-conf``
4132 recipe: SRC_URI_append_qemuall = "file://wired.config \\
4133 file://wired-setup \\ " The underlying mechanism behind
4134 ``MACHINEOVERRIDES`` is simply that it is included in the default
4135 value of ```OVERRIDES`` <#var-OVERRIDES>`__.
4136
4137MAINTAINER
4138 The email address of the distribution maintainer.
4139
4140MIRRORS
4141 Specifies additional paths from which the OpenEmbedded build system
4142 gets source code. When the build system searches for source code, it
4143 first tries the local download directory. If that location fails, the
4144 build system tries locations defined by
4145 ```PREMIRRORS`` <#var-PREMIRRORS>`__, the upstream source, and then
4146 locations specified by ``MIRRORS`` in that order.
4147
4148 Assuming your distribution (```DISTRO`` <#var-DISTRO>`__) is "poky",
4149 the default value for ``MIRRORS`` is defined in the
4150 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
4151
4152MLPREFIX
4153 Specifies a prefix has been added to ```PN`` <#var-PN>`__ to create a
4154 special version of a recipe or package (i.e. a Multilib version). The
4155 variable is used in places where the prefix needs to be added to or
4156 removed from a the name (e.g. the ```BPN`` <#var-BPN>`__ variable).
4157 ``MLPREFIX`` gets set when a prefix has been added to ``PN``.
4158
4159 .. note::
4160
4161 The "ML" in
4162 MLPREFIX
4163 stands for "MultiLib". This representation is historical and comes
4164 from a time when
4165 nativesdk
4166 was a suffix rather than a prefix on the recipe name. When
4167 nativesdk
4168 was turned into a prefix, it made sense to set
4169 MLPREFIX
4170 for it as well.
4171
4172 To help understand when ``MLPREFIX`` might be needed, consider when
4173 ```BBCLASSEXTEND`` <#var-BBCLASSEXTEND>`__ is used to provide a
4174 ``nativesdk`` version of a recipe in addition to the target version.
4175 If that recipe declares build-time dependencies on tasks in other
4176 recipes by using ```DEPENDS`` <#var-DEPENDS>`__, then a dependency on
4177 "foo" will automatically get rewritten to a dependency on
4178 "nativesdk-foo". However, dependencies like the following will not
4179 get rewritten automatically: do_foo[depends] += "recipe:do_foo" If
4180 you want such a dependency to also get transformed, you can do the
4181 following: do_foo[depends] += "${MLPREFIX}recipe:do_foo"
4182
4183module_autoload
4184 This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD``
4185 variable. You should replace all occurrences of ``module_autoload``
4186 with additions to ``KERNEL_MODULE_AUTOLOAD``, for example:
4187 module_autoload_rfcomm = "rfcomm"
4188
4189 should now be replaced with: KERNEL_MODULE_AUTOLOAD += "rfcomm" See
4190 the ```KERNEL_MODULE_AUTOLOAD`` <#var-KERNEL_MODULE_AUTOLOAD>`__
4191 variable for more information.
4192
4193module_conf
4194 Specifies ```modprobe.d`` <http://linux.die.net/man/5/modprobe.d>`__
4195 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
4196 file.
4197
4198 You can use this variable anywhere that it can be recognized by the
4199 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
4200 configuration file, a distribution configuration file, an append file
4201 for the recipe, or the recipe itself). If you use this variable, you
4202 must also be sure to list the module name in the
4203 ```KERNEL_MODULE_AUTOLOAD`` <#var-KERNEL_MODULE_AUTOLOAD>`__
4204 variable.
4205
4206 Here is the general syntax: module_conf_module_name =
4207 "modprobe.d-syntax" You must use the kernel module name override.
4208
4209 Run ``man modprobe.d`` in the shell to find out more information on
4210 the exact syntax you want to provide with ``module_conf``.
4211
4212 Including ``module_conf`` causes the OpenEmbedded build system to
4213 populate the ``/etc/modprobe.d/modname.conf`` file with
4214 ``modprobe.d`` syntax lines. Here is an example that adds the options
4215 ``arg1`` and ``arg2`` to a module named ``mymodule``:
4216 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
4217
4218 For information on how to specify kernel modules to auto-load on
4219 boot, see the
4220 ```KERNEL_MODULE_AUTOLOAD`` <#var-KERNEL_MODULE_AUTOLOAD>`__
4221 variable.
4222
4223MODULE_TARBALL_DEPLOY
4224 Controls creation of the ``modules-*.tgz`` file. Set this variable to
4225 "0" to disable creation of this file, which contains all of the
4226 kernel modules resulting from a kernel build.
4227
4228MODULE_TARBALL_LINK_NAME
4229 The link name of the kernel module tarball. This variable is set in
4230 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4231 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value
4232 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
4233 same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
4234 "${MACHINE}"
4235
4236 See the ```MACHINE`` <#var-MACHINE>`__ variable for additional
4237 information.
4238
4239MODULE_TARBALL_NAME
4240 The base name of the kernel module tarball. This variable is set in
4241 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4242 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the
4243 ```KERNEL_ARTIFACT_NAME`` <#var-KERNEL_ARTIFACT_NAME>`__ variable,
4244 which is set in the same file, has the following value:
4245 KERNEL_ARTIFACT_NAME ?=
4246 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4247
4248MULTIMACH_TARGET_SYS
4249 Uniquely identifies the type of the target system for which packages
4250 are being built. This variable allows output for different types of
4251 target systems to be put into different subdirectories of the same
4252 output directory.
4253
4254 The default value of this variable is:
4255 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} Some classes (e.g.
4256 ```cross-canadian`` <#ref-classes-cross-canadian>`__) modify the
4257 ``MULTIMACH_TARGET_SYS`` value.
4258
4259 See the ```STAMP`` <#var-STAMP>`__ variable for an example. See the
4260 ```STAGING_DIR_TARGET`` <#var-STAGING_DIR_TARGET>`__ variable for
4261 more information.
4262
4263NATIVELSBSTRING
4264 A string identifying the host distribution. Strings consist of the
4265 host distributor ID followed by the release, as reported by the
4266 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
4267 example, when running a build on Ubuntu 12.10, the value is
4268 "Ubuntu-12.10". If this information is unable to be determined, the
4269 value resolves to "Unknown".
4270
4271 This variable is used by default to isolate native shared state
4272 packages for different distributions (e.g. to avoid problems with
4273 ``glibc`` version incompatibilities). Additionally, the variable is
4274 checked against
4275 ```SANITY_TESTED_DISTROS`` <#var-SANITY_TESTED_DISTROS>`__ if that
4276 variable is set.
4277
4278NM
4279 The minimal command and arguments to run ``nm``.
4280
4281NO_GENERIC_LICENSE
4282 Avoids QA errors when you use a non-common, non-CLOSED license in a
4283 recipe. Packages exist, such as the linux-firmware package, with many
4284 licenses that are not in any way common. Also, new licenses are added
4285 occasionally to avoid introducing a lot of common license files,
4286 which are only applicable to a specific package.
4287 ``NO_GENERIC_LICENSE`` is used to allow copying a license that does
4288 not exist in common licenses.
4289
4290 The following example shows how to add ``NO_GENERIC_LICENSE`` to a
4291 recipe: NO_GENERIC_LICENSE[license_name] =
4292 "license_file_in_fetched_source" The following is an example that
4293 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
4294 source: NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
4295
4296NO_RECOMMENDATIONS
4297 Prevents installation of all "recommended-only" packages.
4298 Recommended-only packages are packages installed only through the
4299 ```RRECOMMENDS`` <#var-RRECOMMENDS>`__ variable). Setting the
4300 ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on:
4301 NO_RECOMMENDATIONS = "1"
4302
4303 You can set this variable globally in your ``local.conf`` file or you
4304 can attach it to a specific image recipe by using the recipe name
4305 override: NO_RECOMMENDATIONS_pn-target_image = "1"
4306
4307 It is important to realize that if you choose to not install packages
4308 using this variable and some other packages are dependent on them
4309 (i.e. listed in a recipe's ```RDEPENDS`` <#var-RDEPENDS>`__
4310 variable), the OpenEmbedded build system ignores your request and
4311 will install the packages to avoid dependency errors.
4312
4313 .. note::
4314
4315 Some recommended packages might be required for certain system
4316 functionality, such as kernel modules. It is up to you to add
4317 packages with the
4318 IMAGE_INSTALL
4319 variable. 3409 variable.
4320 3410
4321 Support for this variable exists only when using the IPK and RPM 3411 The value of ``KERNEL_ARTIFACT_NAME``, which is set in the
4322 packaging backend. Support does not exist for DEB. 3412 ``meta/classes/kernel-artifact-names.bbclass`` file, has the
4323 3413 following default value: KERNEL_ARTIFACT_NAME ?=
4324 See the ```BAD_RECOMMENDATIONS`` <#var-BAD_RECOMMENDATIONS>`__ and 3414 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4325 the ```PACKAGE_EXCLUDE`` <#var-PACKAGE_EXCLUDE>`__ variables for 3415
4326 related information. 3416 See the :term:`PKGE`, :term:`PKGV`,
4327 3417 :term:`PKGR`, and :term:`MACHINE`
4328NOAUTOPACKAGEDEBUG 3418 variables for additional information.
4329 Disables auto package from splitting ``.debug`` files. If a recipe 3419
4330 requires ``FILES_${PN}-dbg`` to be set manually, the 3420 .. note::
4331 ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the 3421
4332 content of the debug package. For example: NOAUTOPACKAGEDEBUG = "1" 3422 The
4333 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" FILES_${PN}-dbg 3423 IMAGE_VERSION_SUFFIX
4334 = "/usr/src/debug/" FILES_${QT_BASE_NAME}-demos-doc = 3424 variable is set to
4335 "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 3425 DATETIME
4336 3426 .
4337OBJCOPY 3427
4338 The minimal command and arguments to run ``objcopy``. 3428 KERNEL_CLASSES
4339 3429 A list of classes defining kernel image types that the
4340OBJDUMP 3430 :ref:`kernel <ref-classes-kernel>` class should inherit. You
4341 The minimal command and arguments to run ``objdump``. 3431 typically append this variable to enable extended image types. An
4342 3432 example is the "kernel-fitimage", which enables fitImage support and
4343OE_BINCONFIG_EXTRA_MANGLE 3433 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register
4344 When inheriting the ```binconfig`` <#ref-classes-binconfig>`__ class, 3434 custom kernel image types with the ``kernel`` class using this
4345 this variable specifies additional arguments passed to the "sed" 3435 variable.
4346 command. The sed command alters any paths in configuration scripts 3436
4347 that have been set up during compilation. Inheriting this class 3437 KERNEL_DEVICETREE
4348 results in all paths in these scripts being changed to point into the 3438 Specifies the name of the generated Linux kernel device tree (i.e.
4349 ``sysroots/`` directory so that all builds that use the script will 3439 the ``.dtb``) file.
4350 use the correct directories for the cross compiling layout. 3440
4351 3441 .. note::
4352 See the ``meta/classes/binconfig.bbclass`` in the `Source 3442
4353 Directory <#source-directory>`__ for details on how this class 3443 Legacy support exists for specifying the full path to the device
4354 applies these additional sed command arguments. For general 3444 tree. However, providing just the
4355 information on the ``binconfig`` class, see the 3445 .dtb
4356 "```binconfig.bbclass`` <#ref-classes-binconfig>`__" section. 3446 file is preferred.
4357 3447
4358OE_IMPORTS 3448 In order to use this variable, the
4359 An internal variable used to tell the OpenEmbedded build system what 3449 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
4360 Python modules to import for every Python function run by the system. 3450 be inherited.
4361 3451
4362 .. note:: 3452 KERNEL_DTB_LINK_NAME
4363 3453 The link name of the kernel device tree binary (DTB). This variable
4364 Do not set this variable. It is for internal use only. 3454 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
4365 3455 follows: KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The
4366OE_INIT_ENV_SCRIPT 3456 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
4367 The name of the build environment setup script for the purposes of 3457 the same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
4368 setting up the environment within the extensible SDK. The default 3458 "${MACHINE}"
4369 value is "oe-init-build-env". 3459
4370 3460 See the :term:`MACHINE` variable for additional
4371 If you use a custom script to set up your build environment, set the
4372 ``OE_INIT_ENV_SCRIPT`` variable to its name.
4373
4374OE_TERMINAL
4375 Controls how the OpenEmbedded build system spawns interactive
4376 terminals on the host development system (e.g. using the BitBake
4377 command with the ``-c devshell`` command-line option). For more
4378 information, see the "`Using a Development
4379 Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" section in
4380 the Yocto Project Development Tasks Manual.
4381
4382 You can use the following values for the ``OE_TERMINAL`` variable:
4383 auto gnome xfce rxvt screen konsole none
4384
4385OEROOT
4386 The directory from which the top-level build environment setup script
4387 is sourced. The Yocto Project provides a top-level build environment
4388 setup script: ````` <#structure-core-script>`__. When you run this
4389 script, the ``OEROOT`` variable resolves to the directory that
4390 contains the script.
4391
4392 For additional information on how this variable is used, see the
4393 initialization script.
4394
4395OLDEST_KERNEL
4396 Declares the oldest version of the Linux kernel that the produced
4397 binaries must support. This variable is passed into the build of the
4398 Embedded GNU C Library (``glibc``).
4399
4400 The default for this variable comes from the
4401 ``meta/conf/bitbake.conf`` configuration file. You can override this
4402 default by setting the variable in a custom distribution
4403 configuration file.
4404
4405OVERRIDES
4406 A colon-separated list of overrides that currently apply. Overrides
4407 are a BitBake mechanism that allows variables to be selectively
4408 overridden at the end of parsing. The set of overrides in
4409 ``OVERRIDES`` represents the "state" during building, which includes
4410 the current recipe being built, the machine for which it is being
4411 built, and so forth.
4412
4413 As an example, if the string "an-override" appears as an element in
4414 the colon-separated list in ``OVERRIDES``, then the following
4415 assignment will override ``FOO`` with the value "overridden" at the
4416 end of parsing: FOO_an-override = "overridden" See the "`Conditional
4417 Syntax
4418 (Overrides) <&YOCTO_DOCS_BB_URL;#conditional-syntax-overrides>`__"
4419 section in the BitBake User Manual for more information on the
4420 overrides mechanism.
4421
4422 The default value of ``OVERRIDES`` includes the values of the
4423 ```CLASSOVERRIDE`` <#var-CLASSOVERRIDE>`__,
4424 ```MACHINEOVERRIDES`` <#var-MACHINEOVERRIDES>`__, and
4425 ```DISTROOVERRIDES`` <#var-DISTROOVERRIDES>`__ variables. Another
4426 important override included by default is ``pn-${PN}``. This override
4427 allows variables to be set for a single recipe within configuration
4428 (``.conf``) files. Here is an example: FOO_pn-myrecipe =
4429 "myrecipe-specific value"
4430
4431 .. note::
4432
4433 An easy way to see what overrides apply is to search for
4434 OVERRIDES
4435 in the output of the
4436 bitbake -e
4437 command. See the "
4438 Viewing Variable Values
4439 " section in the Yocto Project Development Tasks Manual for more
4440 information. 3461 information.
4441 3462
4442P 3463 KERNEL_DTB_NAME
4443 The recipe name and version. ``P`` is comprised of the following: 3464 The base name of the kernel device tree binary (DTB). This variable
4444 ${PN}-${PV} 3465 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
4445 3466 follows: KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of
4446PACKAGE_ADD_METADATA 3467 the :term:`KERNEL_ARTIFACT_NAME`
4447 This variable defines additional metdata to add to packages. 3468 variable, which is set in the same file, has the following value:
4448 3469 KERNEL_ARTIFACT_NAME ?=
4449 You may find you need to inject additional metadata into packages. 3470 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4450 This variable allows you to do that by setting the injected data as 3471
4451 the value. Multiple fields can be added by splitting the content with 3472 KERNEL_EXTRA_ARGS
4452 the literal separator "\n". 3473 Specifies additional ``make`` command-line arguments the OpenEmbedded
4453 3474 build system passes on when compiling the kernel.
4454 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable 3475
4455 to do package type specific settings. It can also be made package 3476 KERNEL_FEATURES
4456 specific by using the package name as a suffix. 3477 Includes additional kernel metadata. In the OpenEmbedded build
4457 3478 system, the default Board Support Packages (BSPs)
4458 You can find out more about applying this variable in the "`Adding 3479 :term:`Metadata` is provided through the
4459 custom metadata to 3480 :term:`KMACHINE` and :term:`KBRANCH`
4460 packages <&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages>`__" 3481 variables. You can use the ``KERNEL_FEATURES`` variable from within
4461 section in the Yocto Project Development Tasks Manual. 3482 the kernel recipe or kernel append file to further add metadata for
4462 3483 all BSPs or specific BSPs.
4463PACKAGE_ARCH 3484
4464 The architecture of the resulting package or packages. 3485 The metadata you add through this variable includes config fragments
4465 3486 and features descriptions, which usually includes patches as well as
4466 By default, the value of this variable is set to 3487 config fragments. You typically override the ``KERNEL_FEATURES``
4467 ```TUNE_PKGARCH`` <#var-TUNE_PKGARCH>`__ when building for the 3488 variable for a specific machine. In this way, you can provide
4468 target, ```BUILD_ARCH`` <#var-BUILD_ARCH>`__ when building for the 3489 validated, but optional, sets of kernel configurations and features.
4469 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the 3490
4470 SDK. 3491 For example, the following example from the ``linux-yocto-rt_4.12``
4471 3492 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
4472 .. note:: 3493 as well as "virtio" configurations to all QEMU machines. The last two
4473 3494 statements add specific configurations to targeted machine types:
4474 See 3495 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc
4475 SDK_ARCH 3496 features/taskstats/taskstats.scc" KERNEL_FEATURES_append = "
4476 for more information. 3497 ${KERNEL_EXTRA_FEATURES}" KERNEL_FEATURES_append_qemuall = "
4477 3498 cfg/virtio.scc" KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc
4478 However, if your recipe's output packages are built specific to the 3499 cfg/paravirt_kvm.scc" KERNEL_FEATURES_append_qemux86-64 = "
4479 target machine rather than generally for the architecture of the 3500 cfg/sound.scc"
4480 machine, you should set ``PACKAGE_ARCH`` to the value of 3501
4481 ```MACHINE_ARCH`` <#var-MACHINE_ARCH>`__ in the recipe as follows: 3502 KERNEL_FIT_LINK_NAME
4482 PACKAGE_ARCH = "${MACHINE_ARCH}" 3503 The link name of the kernel flattened image tree (FIT) image. This
4483 3504 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
4484PACKAGE_ARCHS 3505 file as follows: KERNEL_FIT_LINK_NAME ?=
4485 Specifies a list of architectures compatible with the target machine. 3506 "${KERNEL_ARTIFACT_LINK_NAME}" The value of the
4486 This variable is set automatically and should not normally be 3507 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
4487 hand-edited. Entries are separated using spaces and listed in order 3508 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
4488 of priority. The default value for ``PACKAGE_ARCHS`` is "all any 3509 "${MACHINE}"
4489 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 3510
4490 3511 See the :term:`MACHINE` variable for additional
4491PACKAGE_BEFORE_PN 3512 information.
4492 Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so 3513
4493 that those added packages can pick up files that would normally be 3514 KERNEL_FIT_NAME
4494 included in the default package. 3515 The base name of the kernel flattened image tree (FIT) image. This
4495 3516 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
4496PACKAGE_CLASSES 3517 file as follows: KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" The
4497 This variable, which is set in the ``local.conf`` configuration file 3518 value of the :term:`KERNEL_ARTIFACT_NAME`
4498 found in the ``conf`` folder of the `Build 3519 variable, which is set in the same file, has the following value:
4499 Directory <#build-directory>`__, specifies the package manager the 3520 KERNEL_ARTIFACT_NAME ?=
4500 OpenEmbedded build system uses when packaging data. 3521 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4501 3522
4502 You can provide one or more of the following arguments for the 3523 KERNEL_IMAGE_LINK_NAME
4503 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk 3524 The link name for the kernel image. This variable is set in the
4504 package_tar" 3525 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4505 3526 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of
4506 .. note:: 3527 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
4507 3528 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
4508 While it is a legal option, the 3529 "${MACHINE}"
4509 package_tar 3530
4510 class has limited functionality due to no support for package 3531 See the :term:`MACHINE` variable for additional
4511 dependencies by that backend. Therefore, it is recommended that 3532 information.
4512 you do not use it. 3533
4513 3534 KERNEL_IMAGE_MAXSIZE
4514 The build system uses only the first argument in the list as the 3535 Specifies the maximum size of the kernel image file in kilobytes. If
4515 package manager when creating your image or SDK. However, packages 3536 ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is
4516 will be created using any additional packaging classes you specify. 3537 checked against the set value during the
4517 For example, if you use the following in your ``local.conf`` file: 3538 :ref:`ref-tasks-sizecheck` task. The task fails if
4518 PACKAGE_CLASSES ?= "package_ipk" The OpenEmbedded build system uses 3539 the kernel image file is larger than the setting.
4519 the IPK package manager to create your image or SDK. 3540
4520 3541 ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a
4521 For information on packaging and build performance effects as a 3542 limited amount of space in which the kernel image must be stored.
4522 result of the package manager in use, see the 3543
4523 "```package.bbclass`` <#ref-classes-package>`__" section. 3544 By default, this variable is not set, which means the size of the
4524 3545 kernel image is not checked.
4525PACKAGE_DEBUG_SPLIT_STYLE 3546
4526 Determines how to split up the binary and debug information when 3547 KERNEL_IMAGE_NAME
4527 creating ``*-dbg`` packages to be used with the GNU Project Debugger 3548 The base name of the kernel image. This variable is set in the
4528 (GDB). 3549 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4529 3550 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the
4530 With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control 3551 :term:`KERNEL_ARTIFACT_NAME` variable,
4531 where debug information, which can include or exclude source files, 3552 which is set in the same file, has the following value:
4532 is stored: 3553 KERNEL_ARTIFACT_NAME ?=
4533 3554 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4534 - ".debug": Debug symbol files are placed next to the binary in a 3555
4535 ``.debug`` directory on the target. For example, if a binary is 3556 KERNEL_IMAGETYPE
4536 installed into ``/bin``, the corresponding debug symbol files are 3557 The type of kernel to build for a device, usually set by the machine
4537 installed in ``/bin/.debug``. Source files are placed in 3558 configuration files and defaults to "zImage". This variable is used
4538 ``/usr/src/debug``. 3559 when building the kernel and is passed to ``make`` as the target to
4539 3560 build.
4540 - "debug-file-directory": Debug symbol files are placed under 3561
4541 ``/usr/lib/debug`` on the target, and separated by the path from 3562 If you want to build an alternate kernel image type, use the
4542 where the binary is installed. For example, if a binary is 3563 :term:`KERNEL_ALT_IMAGETYPE` variable.
4543 installed in ``/bin``, the corresponding debug symbols are 3564
4544 installed in ``/usr/lib/debug/bin``. Source files are placed in 3565 KERNEL_MODULE_AUTOLOAD
4545 ``/usr/src/debug``. 3566 Lists kernel modules that need to be auto-loaded during boot.
4546 3567
4547 - "debug-without-src": The same behavior as ".debug" previously 3568 .. note::
4548 described with the exception that no source files are installed. 3569
4549 3570 This variable replaces the deprecated
4550 - "debug-with-srcpkg": The same behavior as ".debug" previously 3571 module_autoload
4551 described with the exception that all source files are placed in a 3572 variable.
4552 separate ``*-src`` pkg. This is the default behavior. 3573
4553 3574 You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it
4554 You can find out more about debugging using GDB by reading the 3575 can be recognized by the kernel recipe or by an out-of-tree kernel
4555 "`Debugging With the GNU Project Debugger (GDB) 3576 module recipe (e.g. a machine configuration file, a distribution
4556 Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section 3577 configuration file, an append file for the recipe, or the recipe
4557 in the Yocto Project Development Tasks Manual. 3578 itself).
4558 3579
4559PACKAGE_EXCLUDE_COMPLEMENTARY 3580 Specify it as follows: KERNEL_MODULE_AUTOLOAD += "module_name1
4560 Prevents specific packages from being installed when you are 3581 module_name2 module_name3"
4561 installing complementary packages. 3582
4562 3583 Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build
4563 You might find that you want to prevent installing certain packages 3584 system to populate the ``/etc/modules-load.d/modname.conf`` file with
4564 when you are installing complementary packages. For example, if you 3585 the list of modules to be auto-loaded on boot. The modules appear
4565 are using ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__ to install 3586 one-per-line in the file. Here is an example of the most common use
4566 ``dev-pkgs``, you might not want to install all packages from a 3587 case: KERNEL_MODULE_AUTOLOAD += "module_name"
4567 particular multilib. If you find yourself in this situation, you can 3588
4568 use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular 3589 For information on how to populate the ``modname.conf`` file with
4569 expressions to match the packages you want to exclude. 3590 ``modprobe.d`` syntax lines, see the
4570 3591 :term:`KERNEL_MODULE_PROBECONF`
4571PACKAGE_EXCLUDE 3592 variable.
4572 Lists packages that should not be installed into an image. For 3593
4573 example: PACKAGE_EXCLUDE = "package_name package_name package_name 3594 KERNEL_MODULE_PROBECONF
4574 ..." 3595 Provides a list of modules for which the OpenEmbedded build system
4575 3596 expects to find ``module_conf_``\ modname values that specify
4576 You can set this variable globally in your ``local.conf`` file or you 3597 configuration for each of the modules. For information on how to
4577 can attach it to a specific image recipe by using the recipe name 3598 provide those module configurations, see the
4578 override: PACKAGE_EXCLUDE_pn-target_image = "package_name" 3599 :term:`module_conf_* <module_conf>` variable.
4579 3600
4580 If you choose to not install a package using this variable and some 3601 KERNEL_PATH
4581 other package is dependent on it (i.e. listed in a recipe's 3602 The location of the kernel sources. This variable is set to the value
4582 ```RDEPENDS`` <#var-RDEPENDS>`__ variable), the OpenEmbedded build 3603 of the :term:`STAGING_KERNEL_DIR` within
4583 system generates a fatal installation error. Because the build system 3604 the :ref:`module <ref-classes-module>` class. For information on
4584 halts the process with a fatal error, you can use the variable with 3605 how this variable is used, see the "`Incorporating Out-of-Tree
4585 an iterative development process to remove specific components from a 3606 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__"
4586 system. 3607 section in the Yocto Project Linux Kernel Development Manual.
4587 3608
4588 Support for this variable exists only when using the IPK and RPM 3609 To help maximize compatibility with out-of-tree drivers used to build
4589 packaging backend. Support does not exist for DEB. 3610 modules, the OpenEmbedded build system also recognizes and uses the
4590 3611 :term:`KERNEL_SRC` variable, which is identical to
4591 See the ```NO_RECOMMENDATIONS`` <#var-NO_RECOMMENDATIONS>`__ and the 3612 the ``KERNEL_PATH`` variable. Both variables are common variables
4592 ```BAD_RECOMMENDATIONS`` <#var-BAD_RECOMMENDATIONS>`__ variables for 3613 used by external Makefiles to point to the kernel source directory.
4593 related information. 3614
4594 3615 KERNEL_SRC
4595PACKAGE_EXTRA_ARCHS 3616 The location of the kernel sources. This variable is set to the value
4596 Specifies the list of architectures compatible with the device CPU. 3617 of the :term:`STAGING_KERNEL_DIR` within
4597 This variable is useful when you build for several different devices 3618 the :ref:`module <ref-classes-module>` class. For information on
4598 that use miscellaneous processors such as XScale and ARM926-EJS. 3619 how this variable is used, see the "`Incorporating Out-of-Tree
4599 3620 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__"
4600PACKAGE_FEED_ARCHS 3621 section in the Yocto Project Linux Kernel Development Manual.
4601 Optionally specifies the package architectures used as part of the 3622
4602 package feed URIs during the build. When used, the 3623 To help maximize compatibility with out-of-tree drivers used to build
4603 ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed 3624 modules, the OpenEmbedded build system also recognizes and uses the
4604 URI, which is constructed using the 3625 :term:`KERNEL_PATH` variable, which is identical
4605 ```PACKAGE_FEED_URIS`` <#var-PACKAGE_FEED_URIS>`__ and 3626 to the ``KERNEL_SRC`` variable. Both variables are common variables
4606 ```PACKAGE_FEED_BASE_PATHS`` <#var-PACKAGE_FEED_BASE_PATHS>`__ 3627 used by external Makefiles to point to the kernel source directory.
4607 variables. 3628
4608 3629 KERNEL_VERSION
4609 .. note:: 3630 Specifies the version of the kernel as extracted from ``version.h``
4610 3631 or ``utsrelease.h`` within the kernel sources. Effects of setting
4611 You can use the 3632 this variable do not take affect until the kernel has been
4612 PACKAGE_FEEDS_ARCHS 3633 configured. Consequently, attempting to refer to this variable in
4613 variable to whitelist specific package architectures. If you do 3634 contexts prior to configuration will not work.
4614 not need to whitelist specific architectures, which is a common 3635
4615 case, you can omit this variable. Omitting the variable results in 3636 KERNELDEPMODDEPEND
4616 all available architectures for the current machine being included 3637 Specifies whether the data referenced through
4617 into remote package feeds. 3638 :term:`PKGDATA_DIR` is needed or not. The
4618 3639 ``KERNELDEPMODDEPEND`` does not control whether or not that data
4619 Consider the following example where the ``PACKAGE_FEED_URIS``, 3640 exists, but simply whether or not it is used. If you do not need to
4620 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 3641 use the data, set the ``KERNELDEPMODDEPEND`` variable in your
4621 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 3642 ``initramfs`` recipe. Setting the variable there when the data is not
4622 "https://example.com/packagerepos/release \\ 3643 needed avoids a potential dependency loop.
4623 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 3644
4624 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 3645 KFEATURE_DESCRIPTION
4625 settings, the resulting package feeds are as follows: 3646 Provides a short description of a configuration fragment. You use
4626 https://example.com/packagerepos/release/rpm/all 3647 this variable in the ``.scc`` file that describes a configuration
4627 https://example.com/packagerepos/release/rpm/core2-64 3648 fragment file. Here is the variable used in a file named ``smp.scc``
4628 https://example.com/packagerepos/release/rpm-dev/all 3649 to describe SMP being enabled: define KFEATURE_DESCRIPTION "Enable
4629 https://example.com/packagerepos/release/rpm-dev/core2-64 3650 SMP"
4630 https://example.com/packagerepos/updates/rpm/all 3651
4631 https://example.com/packagerepos/updates/rpm/core2-64 3652 KMACHINE
4632 https://example.com/packagerepos/updates/rpm-dev/all 3653 The machine as known by the kernel. Sometimes the machine name used
4633 https://example.com/packagerepos/updates/rpm-dev/core2-64 3654 by the kernel does not match the machine name used by the
4634 3655 OpenEmbedded build system. For example, the machine name that the
4635PACKAGE_FEED_BASE_PATHS 3656 OpenEmbedded build system understands as ``core2-32-intel-common``
4636 Specifies the base path used when constructing package feed URIs. The 3657 goes by a different name in the Linux Yocto kernel. The kernel
4637 ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a 3658 understands that machine as ``intel-core2-32``. For cases like these,
4638 package feed URI used by the OpenEmbedded build system. The base path 3659 the ``KMACHINE`` variable maps the kernel machine name to the
4639 lies between the ```PACKAGE_FEED_URIS`` <#var-PACKAGE_FEED_URIS>`__ 3660 OpenEmbedded build system machine name.
4640 and ```PACKAGE_FEED_ARCHS`` <#var-PACKAGE_FEED_ARCHS>`__ variables. 3661
4641 3662 These mappings between different names occur in the Yocto Linux
4642 Consider the following example where the ``PACKAGE_FEED_URIS``, 3663 Kernel's ``meta`` branch. As an example take a look in the
4643 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 3664 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:
4644 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 3665 LINUX_VERSION_core2-32-intel-common = "3.19.0"
4645 "https://example.com/packagerepos/release \\ 3666 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
4646 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 3667 SRCREV_meta_core2-32-intel-common =
4647 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 3668 "8897ef68b30e7426bc1d39895e71fb155d694974"
4648 settings, the resulting package feeds are as follows: 3669 SRCREV_machine_core2-32-intel-common =
4649 https://example.com/packagerepos/release/rpm/all 3670 "43b9eced9ba8a57add36af07736344dcc383f711"
4650 https://example.com/packagerepos/release/rpm/core2-64 3671 KMACHINE_core2-32-intel-common = "intel-core2-32"
4651 https://example.com/packagerepos/release/rpm-dev/all 3672 KBRANCH_core2-32-intel-common = "standard/base"
4652 https://example.com/packagerepos/release/rpm-dev/core2-64 3673 KERNEL_FEATURES_append_core2-32-intel-common =
4653 https://example.com/packagerepos/updates/rpm/all 3674 "${KERNEL_FEATURES_INTEL_COMMON}" The ``KMACHINE`` statement says
4654 https://example.com/packagerepos/updates/rpm/core2-64 3675 that the kernel understands the machine name as "intel-core2-32".
4655 https://example.com/packagerepos/updates/rpm-dev/all 3676 However, the OpenEmbedded build system understands the machine as
4656 https://example.com/packagerepos/updates/rpm-dev/core2-64 3677 "core2-32-intel-common".
4657 3678
4658PACKAGE_FEED_URIS 3679 KTYPE
4659 Specifies the front portion of the package feed URI used by the 3680 Defines the kernel type to be used in assembling the configuration.
4660 OpenEmbedded build system. Each final package feed URI is comprised 3681 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
4661 of ``PACKAGE_FEED_URIS``, 3682 kernel types. See the "`Kernel
4662 ```PACKAGE_FEED_BASE_PATHS`` <#var-PACKAGE_FEED_BASE_PATHS>`__, and 3683 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the
4663 ```PACKAGE_FEED_ARCHS`` <#var-PACKAGE_FEED_ARCHS>`__ variables. 3684 Yocto Project Linux Kernel Development Manual for more information on
4664 3685 kernel types.
4665 Consider the following example where the ``PACKAGE_FEED_URIS``, 3686
4666 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 3687 You define the ``KTYPE`` variable in the `BSP
4667 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 3688 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__. The
4668 "https://example.com/packagerepos/release \\ 3689 value you use must match the value used for the
4669 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 3690 :term:`LINUX_KERNEL_TYPE` value used by the
4670 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 3691 kernel recipe.
4671 settings, the resulting package feeds are as follows: 3692
4672 https://example.com/packagerepos/release/rpm/all 3693 LABELS
4673 https://example.com/packagerepos/release/rpm/core2-64 3694 Provides a list of targets for automatic configuration.
4674 https://example.com/packagerepos/release/rpm-dev/all 3695
4675 https://example.com/packagerepos/release/rpm-dev/core2-64 3696 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
4676 https://example.com/packagerepos/updates/rpm/all 3697 information on how this variable is used.
4677 https://example.com/packagerepos/updates/rpm/core2-64 3698
4678 https://example.com/packagerepos/updates/rpm-dev/all 3699 LAYERDEPENDS
4679 https://example.com/packagerepos/updates/rpm-dev/core2-64 3700 Lists the layers, separated by spaces, on which this recipe depends.
4680 3701 Optionally, you can specify a specific layer version for a dependency
4681PACKAGE_INSTALL 3702 by adding it to the end of the layer name. Here is an example:
4682 The final list of packages passed to the package manager for 3703 LAYERDEPENDS_mylayer = "anotherlayer (=3)" In this previous example,
4683 installation into the image. 3704 version 3 of "anotherlayer" is compared against
4684 3705 :term:`LAYERVERSION`\ ``_anotherlayer``.
4685 Because the package manager controls actual installation of all 3706
4686 packages, the list of packages passed using ``PACKAGE_INSTALL`` is 3707 An error is produced if any dependency is missing or the version
4687 not the final list of packages that are actually installed. This 3708 numbers (if specified) do not match exactly. This variable is used in
4688 variable is internal to the image construction code. Consequently, in 3709 the ``conf/layer.conf`` file and must be suffixed with the name of
4689 general, you should use the 3710 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
4690 ```IMAGE_INSTALL`` <#var-IMAGE_INSTALL>`__ variable to specify 3711
4691 packages for installation. The exception to this is when working with 3712 LAYERDIR
4692 the 3713 When used inside the ``layer.conf`` configuration file, this variable
4693 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ 3714 provides the path of the current layer. This variable is not
4694 image. When working with an initial RAM filesystem (initramfs) image, 3715 available outside of ``layer.conf`` and references are expanded
4695 use the ``PACKAGE_INSTALL`` variable. For information on creating an 3716 immediately when parsing of the file completes.
4696 initramfs, see the "`Building an Initial RAM Filesystem (initramfs) 3717
4697 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section 3718 LAYERRECOMMENDS
4698 in the Yocto Project Development Tasks Manual. 3719 Lists the layers, separated by spaces, recommended for use with this
4699 3720 layer.
4700PACKAGE_INSTALL_ATTEMPTONLY 3721
4701 Specifies a list of packages the OpenEmbedded build system attempts 3722 Optionally, you can specify a specific layer version for a
4702 to install when creating an image. If a listed package fails to 3723 recommendation by adding the version to the end of the layer name.
4703 install, the build system does not generate an error. This variable 3724 Here is an example: LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" In
4704 is generally not user-defined. 3725 this previous example, version 3 of "anotherlayer" is compared
4705 3726 against ``LAYERVERSION_anotherlayer``.
4706PACKAGE_PREPROCESS_FUNCS 3727
4707 Specifies a list of functions run to pre-process the 3728 This variable is used in the ``conf/layer.conf`` file and must be
4708 ```PKGD`` <#var-PKGD>`__ directory prior to splitting the files out 3729 suffixed with the name of the specific layer (e.g.
4709 to individual packages. 3730 ``LAYERRECOMMENDS_mylayer``).
4710 3731
4711PACKAGE_WRITE_DEPS 3732 LAYERSERIES_COMPAT
4712 Specifies a list of dependencies for post-installation and 3733 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which
4713 pre-installation scripts on native/cross tools. If your 3734 a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable
4714 post-installation or pre-installation script can execute at rootfs 3735 allows the layer maintainer to indicate which combinations of the
4715 creation time rather than on the target but depends on a native tool 3736 layer and OE-Core can be expected to work. The variable gives the
4716 in order to execute, you need to list the tools in 3737 system a way to detect when a layer has not been tested with new
4717 ``PACKAGE_WRITE_DEPS``. 3738 releases of OE-Core (e.g. the layer is not maintained).
4718 3739
4719 For information on running post-installation scripts, see the 3740 To specify the OE-Core versions for which a layer is compatible, use
4720 "`Post-Installation 3741 this variable in your layer's ``conf/layer.conf`` configuration file.
4721 Scripts <&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts>`__" 3742 For the list, use the Yocto Project
4722 section in the Yocto Project Development Tasks Manual. 3743 :yocto_wiki:`Release Name </wiki/Releases>` (e.g.
4723 3744 DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the
4724PACKAGECONFIG 3745 layer, use a space-separated list: LAYERSERIES_COMPAT_layer_root_name
4725 This variable provides a means of enabling or disabling features of a 3746 = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE"
4726 recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in 3747
4727 recipes when you specify features and then arguments that define 3748 .. note::
4728 feature behaviors. Here is the basic block structure (broken over 3749
4729 multiple lines for readability): PACKAGECONFIG ??= "f1 f2 f3 ..." 3750 Setting
4730 PACKAGECONFIG[f1] = "\\ --with-f1, \\ --without-f1, \\ 3751 LAYERSERIES_COMPAT
4731 build-deps-for-f1, \\ runtime-deps-for-f1, \\ 3752 is required by the Yocto Project Compatible version 2 standard.
4732 runtime-recommends-for-f1, \\ packageconfig-conflicts-for-f1 \\ " 3753 The OpenEmbedded build system produces a warning if the variable
4733 PACKAGECONFIG[f2] = "\\ ... and so on and so on ... 3754 is not set for any given layer.
4734 3755
4735 The ``PACKAGECONFIG`` variable itself specifies a space-separated 3756 See the "`Creating Your Own
4736 list of the features to enable. Following the features, you can 3757 Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in
4737 determine the behavior of each feature by providing up to six 3758 the Yocto Project Development Tasks Manual.
4738 order-dependent arguments, which are separated by commas. You can 3759
4739 omit any argument you like but must retain the separating commas. The 3760 LAYERVERSION
4740 order is important and specifies the following: 3761 Optionally specifies the version of a layer as a single number. You
4741 3762 can use this within :term:`LAYERDEPENDS` for
4742 1. Extra arguments that should be added to the configure script 3763 another layer in order to depend on a specific version of the layer.
4743 argument list (```EXTRA_OECONF`` <#var-EXTRA_OECONF>`__ or 3764 This variable is used in the ``conf/layer.conf`` file and must be
4744 ```PACKAGECONFIG_CONFARGS`` <#var-PACKAGECONFIG_CONFARGS>`__) if 3765 suffixed with the name of the specific layer (e.g.
4745 the feature is enabled. 3766 ``LAYERVERSION_mylayer``).
4746 3767
4747 2. Extra arguments that should be added to ``EXTRA_OECONF`` or 3768 LD
4748 ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. 3769 The minimal command and arguments used to run the linker.
4749 3770
4750 3. Additional build dependencies (```DEPENDS`` <#var-DEPENDS>`__) 3771 LDFLAGS
4751 that should be added if the feature is enabled. 3772 Specifies the flags to pass to the linker. This variable is exported
4752 3773 to an environment variable and thus made visible to the software
4753 4. Additional runtime dependencies (```RDEPENDS`` <#var-RDEPENDS>`__) 3774 being built during the compilation step.
4754 that should be added if the feature is enabled. 3775
4755 3776 Default initialization for ``LDFLAGS`` varies depending on what is
4756 5. Additional runtime recommendations 3777 being built:
4757 (```RRECOMMENDS`` <#var-RRECOMMENDS>`__) that should be added if 3778
4758 the feature is enabled. 3779 - :term:`TARGET_LDFLAGS` when building for the
4759 3780 target
4760 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` 3781
4761 settings for this feature. 3782 - :term:`BUILD_LDFLAGS` when building for the
4762 3783 build host (i.e. ``-native``)
4763 Consider the following ``PACKAGECONFIG`` block taken from the 3784
4764 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 3785 - :term:`BUILDSDK_LDFLAGS` when building for
4765 three arguments that determine the feature's behavior. 3786 an SDK (i.e. ``nativesdk-``)
4766 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" The 3787
4767 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 3788 LEAD_SONAME
4768 enabled. In this case, ``--with-gtk3`` is added to the configure 3789 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
4769 script argument list and ``gtk+3`` is added to ``DEPENDS``. On the 3790 that the :ref:`debian <ref-classes-debian>` class applies its
4770 other hand, if the feature is disabled say through a ``.bbappend`` 3791 naming policy to given a recipe that packages multiple libraries.
4771 file in another layer, then the second argument ``--without-gtk3`` is 3792
4772 added to the configure script instead. 3793 This variable works in conjunction with the ``debian`` class.
4773 3794
4774 The basic ``PACKAGECONFIG`` structure previously described holds true 3795 LIC_FILES_CHKSUM
4775 regardless of whether you are creating a block or changing a block. 3796 Checksums of the license text in the recipe source code.
4776 When creating a block, use the structure inside your recipe. 3797
4777 3798 This variable tracks changes in license text of the source code
4778 If you want to change an existing ``PACKAGECONFIG`` block, you can do 3799 files. If the license text is changed, it will trigger a build
4779 so one of two ways: 3800 failure, which gives the developer an opportunity to review any
4780 3801 license change.
4781 - *Append file:* Create an append file named 3802
4782 recipename\ ``.bbappend`` in your layer and override the value of 3803 This variable must be defined for all recipes (unless
4783 ``PACKAGECONFIG``. You can either completely override the 3804 :term:`LICENSE` is set to "CLOSED").
4784 variable: PACKAGECONFIG = "f4 f5" Or, you can just append the 3805
4785 variable: PACKAGECONFIG_append = " f4" 3806 For more information, see the "`Tracking License
4786 3807 Changes <&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM>`__"
4787 - *Configuration file:* This method is identical to changing the
4788 block through an append file except you edit your ``local.conf``
4789 or ``mydistro.conf`` file. As with append files previously
4790 described, you can either completely override the variable:
4791 PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the
4792 variable: PACKAGECONFIG_append_pn-recipename = " f4"
4793
4794PACKAGECONFIG_CONFARGS
4795 A space-separated list of configuration options generated from the
4796 ```PACKAGECONFIG`` <#var-PACKAGECONFIG>`__ setting.
4797
4798 Classes such as ```autotools`` <#ref-classes-autotools>`__ and
4799 ```cmake`` <#ref-classes-cmake>`__ use ``PACKAGECONFIG_CONFARGS`` to
4800 pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``,
4801 respectively. If you are using ``PACKAGECONFIG`` but not a class that
4802 handles the ``do_configure`` task, then you need to use
4803 ``PACKAGECONFIG_CONFARGS`` appropriately.
4804
4805PACKAGEGROUP_DISABLE_COMPLEMENTARY
4806 For recipes inheriting the
4807 ```packagegroup`` <#ref-classes-packagegroup>`__ class, setting
4808 ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the
4809 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
4810 should not be automatically created by the ``packagegroup`` recipe,
4811 which is the default behavior.
4812
4813PACKAGES
4814 The list of packages the recipe creates. The default value is the
4815 following: ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale
4816 ${PACKAGE_BEFORE_PN} ${PN}
4817
4818 During packaging, the ```do_package`` <#ref-tasks-package>`__ task
4819 goes through ``PACKAGES`` and uses the ```FILES`` <#var-FILES>`__
4820 variable corresponding to each package to assign files to the
4821 package. If a file matches the ``FILES`` variable for more than one
4822 package in ``PACKAGES``, it will be assigned to the earliest
4823 (leftmost) package.
4824
4825 Packages in the variable's list that are empty (i.e. where none of
4826 the patterns in ``FILES_``\ pkg match any files installed by the
4827 ```do_install`` <#ref-tasks-install>`__ task) are not generated,
4828 unless generation is forced through the
4829 ```ALLOW_EMPTY`` <#var-ALLOW_EMPTY>`__ variable.
4830
4831PACKAGES_DYNAMIC
4832 A promise that your recipe satisfies runtime dependencies for
4833 optional modules that are found in other recipes.
4834 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it
4835 only states that they should be satisfied. For example, if a hard,
4836 runtime dependency (```RDEPENDS`` <#var-RDEPENDS>`__) of another
4837 package is satisfied at build time through the ``PACKAGES_DYNAMIC``
4838 variable, but a package with the module name is never actually
4839 produced, then the other package will be broken. Thus, if you attempt
4840 to include that package in an image, you will get a dependency
4841 failure from the packaging system during the
4842 ```do_rootfs`` <#ref-tasks-rootfs>`__ task.
4843
4844 Typically, if there is a chance that such a situation can occur and
4845 the package that is not created is valid without the dependency being
4846 satisfied, then you should use ```RRECOMMENDS`` <#var-RRECOMMENDS>`__
4847 (a soft runtime dependency) instead of ``RDEPENDS``.
4848
4849 For an example of how to use the ``PACKAGES_DYNAMIC`` variable when
4850 you are splitting packages, see the "`Handling Optional Module
4851 Packaging <&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging>`__"
4852 section in the Yocto Project Development Tasks Manual.
4853
4854PACKAGESPLITFUNCS
4855 Specifies a list of functions run to perform additional splitting of
4856 files into individual packages. Recipes can either prepend to this
4857 variable or prepend to the ``populate_packages`` function in order to
4858 perform additional package splitting. In either case, the function
4859 should set ```PACKAGES`` <#var-PACKAGES>`__,
4860 ```FILES`` <#var-FILES>`__, ```RDEPENDS`` <#var-RDEPENDS>`__ and
4861 other packaging variables appropriately in order to perform the
4862 desired splitting.
4863
4864PARALLEL_MAKE
4865 Extra options passed to the ``make`` command during the
4866 ```do_compile`` <#ref-tasks-compile>`__ task in order to specify
4867 parallel compilation on the local build host. This variable is
4868 usually in the form "-j x", where x represents the maximum number of
4869 parallel threads ``make`` can run.
4870
4871 .. note::
4872
4873 In order for
4874 PARALLEL_MAKE
4875 to be effective,
4876 make
4877 must be called with
4878 ${
4879 EXTRA_OEMAKE
4880 }
4881 . An easy way to ensure this is to use the
4882 oe_runmake
4883 function.
4884
4885 By default, the OpenEmbedded build system automatically sets this
4886 variable to be equal to the number of cores the build system uses.
4887
4888 .. note::
4889
4890 If the software being built experiences dependency issues during
4891 the
4892 do_compile
4893 task that result in race conditions, you can clear the
4894 PARALLEL_MAKE
4895 variable within the recipe as a workaround. For information on
4896 addressing race conditions, see the "
4897 Debugging Parallel Make Races
4898 " section in the Yocto Project Development Tasks Manual.
4899
4900 For single socket systems (i.e. one CPU), you should not have to
4901 override this variable to gain optimal parallelism during builds.
4902 However, if you have very large systems that employ multiple physical
4903 CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is
4904 not set higher than "-j 20".
4905
4906 For more information on speeding up builds, see the "`Speeding Up a
4907 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the
4908 Yocto Project Development Tasks Manual.
4909
4910PARALLEL_MAKEINST
4911 Extra options passed to the ``make install`` command during the
4912 ```do_install`` <#ref-tasks-install>`__ task in order to specify
4913 parallel installation. This variable defaults to the value of
4914 ```PARALLEL_MAKE`` <#var-PARALLEL_MAKE>`__.
4915
4916 .. note::
4917
4918 In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must
4919 be called with
4920 ``${``\ ```EXTRA_OEMAKE`` <#var-EXTRA_OEMAKE>`__\ ``}``. An easy
4921 way to ensure this is to use the ``oe_runmake`` function.
4922
4923 If the software being built experiences dependency issues during
4924 the ``do_install`` task that result in race conditions, you can
4925 clear the ``PARALLEL_MAKEINST`` variable within the recipe as a
4926 workaround. For information on addressing race conditions, see the
4927 "`Debugging Parallel Make
4928 Races <&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races>`__"
4929 section in the Yocto Project Development Tasks Manual. 3808 section in the Yocto Project Development Tasks Manual.
4930 3809
4931PATCHRESOLVE 3810 LICENSE
4932 Determines the action to take when a patch fails. You can set this 3811 The list of source licenses for the recipe. Follow these rules:
4933 variable to one of two values: "noop" and "user". 3812
4934 3813 - Do not use spaces within individual license names.
4935 The default value of "noop" causes the build to simply fail when the 3814
4936 OpenEmbedded build system cannot successfully apply a patch. Setting 3815 - Separate license names using \| (pipe) when there is a choice
4937 the value to "user" causes the build system to launch a shell and 3816 between licenses.
4938 places you in the right location so that you can manually resolve the 3817
4939 conflicts. 3818 - Separate license names using & (ampersand) when multiple licenses
4940 3819 exist that cover different parts of the source.
4941 Set this variable in your ``local.conf`` file. 3820
4942 3821 - You can use spaces between license names.
4943PATCHTOOL 3822
4944 Specifies the utility used to apply patches for a recipe during the 3823 - For standard licenses, use the names of the files in
4945 ```do_patch`` <#ref-tasks-patch>`__ task. You can specify one of 3824 ``meta/files/common-licenses/`` or the
4946 three utilities: "patch", "quilt", or "git". The default utility used 3825 :term:`SPDXLICENSEMAP` flag names defined in
4947 is "quilt" except for the quilt-native recipe itself. Because the 3826 ``meta/conf/licenses.conf``.
4948 quilt tool is not available at the time quilt-native is being 3827
4949 patched, it uses "patch". 3828 Here are some examples: LICENSE = "LGPLv2.1 \| GPLv3" LICENSE =
4950 3829 "MPL-1 & LGPLv2.1" LICENSE = "GPLv2+" The first example is from the
4951 If you wish to use an alternative patching tool, set the variable in 3830 recipes for Qt, which the user may choose to distribute under either
4952 the recipe using one of the following: PATCHTOOL = "patch" PATCHTOOL 3831 the LGPL version 2.1 or GPL version 3. The second example is from
4953 = "quilt" PATCHTOOL = "git" 3832 Cairo where two licenses cover different parts of the source code.
4954 3833 The final example is from ``sysstat``, which presents a single
4955PE 3834 license.
4956 The epoch of the recipe. By default, this variable is unset. The 3835
4957 variable is used to make upgrades possible when the versioning scheme 3836 You can also specify licenses on a per-package basis to handle
4958 changes in some backwards incompatible way. 3837 situations where components of the output have different licenses.
4959 3838 For example, a piece of software whose code is licensed under GPLv2
4960 ``PE`` is the default value of the ```PKGE`` <#var-PKGE>`__ variable. 3839 but has accompanying documentation licensed under the GNU Free
4961 3840 Documentation License 1.2 could be specified as follows: LICENSE =
4962PF 3841 "GFDL-1.2 & GPLv2" LICENSE_${PN} = "GPLv2" LICENSE_${PN}-doc =
4963 Specifies the recipe or package name and includes all version and 3842 "GFDL-1.2"
4964 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 3843
4965 ``bash-4.2-r1/``). This variable is comprised of the following: 3844 LICENSE_CREATE_PACKAGE
4966 ${`PN <#var-PN>`__}-${`EXTENDPE <#var-EXTENDPE>`__}${`PV <#var-PV>`__}-${`PR <#var-PR>`__} 3845 Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded
4967 3846 build system to create an extra package (i.e.
4968PIXBUF_PACKAGES 3847 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
4969 When inheriting the ```pixbufcache`` <#ref-classes-pixbufcache>`__ 3848 those packages to the
4970 class, this variable identifies packages that contain the pixbuf 3849 :term:`RRECOMMENDS`\ ``_${PN}``.
4971 loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` 3850
4972 class assumes that the loaders are in the recipe's main package (i.e. 3851 The ``${PN}-lic`` package installs a directory in
4973 ``${``\ ```PN`` <#var-PN>`__\ ``}``). Use this variable if the 3852 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
4974 loaders you need are in a package other than that main package. 3853 name, and installs files in that directory that contain license and
4975 3854 copyright information (i.e. copies of the appropriate license files
4976PKG 3855 from ``meta/common-licenses`` that match the licenses specified in
4977 The name of the resulting package created by the OpenEmbedded build 3856 the :term:`LICENSE` variable of the recipe metadata
4978 system. 3857 and copies of files marked in
4979 3858 :term:`LIC_FILES_CHKSUM` as containing
4980 .. note:: 3859 license text).
4981 3860
4982 When using the 3861 For related information on providing license text, see the
4983 PKG 3862 :term:`COPY_LIC_DIRS` variable, the
4984 variable, you must use a package name override. 3863 :term:`COPY_LIC_MANIFEST` variable, and the
4985 3864 "`Providing License
4986 For example, when the ```debian`` <#ref-classes-debian>`__ class 3865 Text <&YOCTO_DOCS_DEV_URL;#providing-license-text>`__" section in the
4987 renames the output package, it does so by setting 3866 Yocto Project Development Tasks Manual.
4988 ``PKG_packagename``. 3867
4989 3868 LICENSE_FLAGS
4990PKG_CONFIG_PATH 3869 Specifies additional flags for a recipe you must whitelist through
4991 The path to ``pkg-config`` files for the current build context. 3870 :term:`LICENSE_FLAGS_WHITELIST` in
4992 ``pkg-config`` reads this variable from the environment. 3871 order to allow the recipe to be built. When providing multiple flags,
4993 3872 separate them with spaces.
4994PKGD 3873
4995 Points to the destination directory for files to be packaged before 3874 This value is independent of :term:`LICENSE` and is
4996 they are split into individual packages. This directory defaults to 3875 typically used to mark recipes that might require additional licenses
4997 the following: ${WORKDIR}/package 3876 in order to be used in a commercial product. For more information,
4998 3877 see the "`Enabling Commercially Licensed
4999 Do not change this default. 3878 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__"
5000 3879 section in the Yocto Project Development Tasks Manual.
5001PKGDATA_DIR 3880
5002 Points to a shared, global-state directory that holds data generated 3881 LICENSE_FLAGS_WHITELIST
5003 during the packaging process. During the packaging process, the 3882 Lists license flags that when specified in
5004 ```do_packagedata`` <#ref-tasks-packagedata>`__ task packages data 3883 :term:`LICENSE_FLAGS` within a recipe should not
5005 for each recipe and installs it into this temporary, shared area. 3884 prevent that recipe from being built. This practice is otherwise
5006 This directory defaults to the following, which you should not 3885 known as "whitelisting" license flags. For more information, see the
5007 change: ${STAGING_DIR_HOST}/pkgdata For examples of how this data is 3886 "`Enabling Commercially Licensed
5008 used, see the "`Automatically Added Runtime 3887 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__"
5009 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 3888 section in the Yocto Project Development Tasks Manual.
5010 section in the Yocto Project Overview and Concepts Manual and the 3889
5011 "`Viewing Package Information with 3890 LICENSE_PATH
5012 ``oe-pkgdata-util`` <&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util>`__" 3891 Path to additional licenses used during the build. By default, the
5013 section in the Yocto Project Development Tasks Manual. For more 3892 OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the
5014 information on the shared, global-state directory, see 3893 directory that holds common license text used during the build. The
5015 ```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__. 3894 ``LICENSE_PATH`` variable allows you to extend that location to other
5016 3895 areas that have additional licenses: LICENSE_PATH +=
5017PKGDEST 3896 "path-to-additional-common-licenses"
5018 Points to the parent directory for files to be packaged after they 3897
5019 have been split into individual packages. This directory defaults to 3898 LINUX_KERNEL_TYPE
5020 the following: ${WORKDIR}/packages-split 3899 Defines the kernel type to be used in assembling the configuration.
5021 3900 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
5022 Under this directory, the build system creates directories for each 3901 kernel types. See the "`Kernel
5023 package specified in ```PACKAGES`` <#var-PACKAGES>`__. Do not change 3902 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the
5024 this default. 3903 Yocto Project Linux Kernel Development Manual for more information on
5025 3904 kernel types.
5026PKGDESTWORK 3905
5027 Points to a temporary work area where the 3906 If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to
5028 ```do_package`` <#ref-tasks-package>`__ task saves package metadata. 3907 "standard". Together with :term:`KMACHINE`, the
5029 The ``PKGDESTWORK`` location defaults to the following: 3908 ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by
5030 ${WORKDIR}/pkgdata Do not change this default. 3909 the kernel tools to find the appropriate description within the
5031 3910 kernel :term:`Metadata` with which to build out the sources
5032 The ```do_packagedata`` <#ref-tasks-packagedata>`__ task copies the 3911 and configuration.
5033 package metadata from ``PKGDESTWORK`` to 3912
5034 ```PKGDATA_DIR`` <#var-PKGDATA_DIR>`__ to make it available globally. 3913 LINUX_VERSION
5035 3914 The Linux version from ``kernel.org`` on which the Linux kernel image
5036PKGE 3915 being built using the OpenEmbedded build system is based. You define
5037 The epoch of the package(s) built by the recipe. By default, ``PKGE`` 3916 this variable in the kernel recipe. For example, the
5038 is set to ```PE`` <#var-PE>`__. 3917 ``linux-yocto-3.4.bb`` kernel recipe found in
5039 3918 ``meta/recipes-kernel/linux`` defines the variables as follows:
5040PKGR 3919 LINUX_VERSION ?= "3.4.24"
5041 The revision of the package(s) built by the recipe. By default, 3920
5042 ``PKGR`` is set to ```PR`` <#var-PR>`__. 3921 The ``LINUX_VERSION`` variable is used to define :term:`PV`
5043 3922 for the recipe: PV = "${LINUX_VERSION}+git${SRCPV}"
5044PKGV 3923
5045 The version of the package(s) built by the recipe. By default, 3924 LINUX_VERSION_EXTENSION
5046 ``PKGV`` is set to ```PV`` <#var-PV>`__. 3925 A string extension compiled into the version string of the Linux
5047 3926 kernel built with the OpenEmbedded build system. You define this
5048PN 3927 variable in the kernel recipe. For example, the linux-yocto kernel
5049 This variable can have two separate functions depending on the 3928 recipes all define the variable as follows: LINUX_VERSION_EXTENSION
5050 context: a recipe name or a resulting package name. 3929 ?= "-yocto-${:term:`LINUX_KERNEL_TYPE`}"
5051 3930
5052 ``PN`` refers to a recipe name in the context of a file used by the 3931 Defining this variable essentially sets the Linux kernel
5053 OpenEmbedded build system as input to create a package. The name is 3932 configuration item ``CONFIG_LOCALVERSION``, which is visible through
5054 normally extracted from the recipe file name. For example, if the 3933 the ``uname`` command. Here is an example that shows the extension
5055 recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` 3934 assuming it was set as previously shown: $ uname -r 3.7.0-rc8-custom
5056 will be "expat". 3935
5057 3936 LOG_DIR
5058 The variable refers to a package name in the context of a file 3937 Specifies the directory to which the OpenEmbedded build system writes
5059 created or produced by the OpenEmbedded build system. 3938 overall log files. The default directory is ``${TMPDIR}/log``.
5060 3939
5061 If applicable, the ``PN`` variable also contains any special suffix 3940 For the directory containing logs specific to each task, see the
5062 or prefix. For example, using ``bash`` to build packages for the 3941 :term:`T` variable.
5063 native machine, ``PN`` is ``bash-native``. Using ``bash`` to build 3942
5064 packages for the target and for Multilib, ``PN`` would be ``bash`` 3943 MACHINE
5065 and ``lib64-bash``, respectively. 3944 Specifies the target device for which the image is built. You define
5066 3945 ``MACHINE`` in the ``local.conf`` file found in the
5067PNBLACKLIST 3946 :term:`Build Directory`. By default, ``MACHINE`` is set to
5068 Lists recipes you do not want the OpenEmbedded build system to build. 3947 "qemux86", which is an x86-based architecture machine to be emulated
5069 This variable works in conjunction with the 3948 using QEMU: MACHINE ?= "qemux86"
5070 ```blacklist`` <#ref-classes-blacklist>`__ class, which is inherited 3949
5071 globally. 3950 The variable corresponds to a machine configuration file of the same
5072 3951 name, through which machine-specific configurations are set. Thus,
5073 To prevent a recipe from being built, use the ``PNBLACKLIST`` 3952 when ``MACHINE`` is set to "qemux86" there exists the corresponding
5074 variable in your ``local.conf`` file. Here is an example that 3953 ``qemux86.conf`` machine configuration file, which can be found in
5075 prevents ``myrecipe`` from being built: PNBLACKLIST[myrecipe] = "Not 3954 the :term:`Source Directory` in
5076 supported by our organization." 3955 ``meta/conf/machine``.
5077 3956
5078POPULATE_SDK_POST_HOST_COMMAND 3957 The list of machines supported by the Yocto Project as shipped
5079 Specifies a list of functions to call once the OpenEmbedded build 3958 include the following: MACHINE ?= "qemuarm" MACHINE ?= "qemuarm64"
5080 system has created the host part of the SDK. You can specify 3959 MACHINE ?= "qemumips" MACHINE ?= "qemumips64" MACHINE ?= "qemuppc"
5081 functions separated by semicolons: POPULATE_SDK_POST_HOST_COMMAND += 3960 MACHINE ?= "qemux86" MACHINE ?= "qemux86-64" MACHINE ?= "genericx86"
5082 "function; ... " 3961 MACHINE ?= "genericx86-64" MACHINE ?= "beaglebone" MACHINE ?=
5083 3962 "edgerouter" The last five are Yocto Project reference hardware
5084 If you need to pass the SDK path to a command within a function, you 3963 boards, which are provided in the ``meta-yocto-bsp`` layer.
5085 can use ``${SDK_DIR}``, which points to the parent directory used by 3964
5086 the OpenEmbedded build system when creating SDK output. See the 3965 .. note::
5087 ```SDK_DIR`` <#var-SDK_DIR>`__ variable for more information. 3966
5088 3967 Adding additional Board Support Package (BSP) layers to your
5089POPULATE_SDK_POST_TARGET_COMMAND 3968 configuration adds new possible settings for
5090 Specifies a list of functions to call once the OpenEmbedded build 3969 MACHINE
5091 system has created the target part of the SDK. You can specify 3970 .
5092 functions separated by semicolons: POPULATE_SDK_POST_TARGET_COMMAND 3971
5093 += "function; ... " 3972 MACHINE_ARCH
5094 3973 Specifies the name of the machine-specific architecture. This
5095 If you need to pass the SDK path to a command within a function, you 3974 variable is set automatically from :term:`MACHINE` or
5096 can use ``${SDK_DIR}``, which points to the parent directory used by 3975 :term:`TUNE_PKGARCH`. You should not hand-edit
5097 the OpenEmbedded build system when creating SDK output. See the 3976 the ``MACHINE_ARCH`` variable.
5098 ```SDK_DIR`` <#var-SDK_DIR>`__ variable for more information. 3977
5099 3978 MACHINE_ESSENTIAL_EXTRA_RDEPENDS
5100PR 3979 A list of required machine-specific packages to install as part of
5101 The revision of the recipe. The default value for this variable is 3980 the image being built. The build process depends on these packages
5102 "r0". Subsequent revisions of the recipe conventionally have the 3981 being present. Furthermore, because this is a "machine-essential"
5103 values "r1", "r2", and so forth. When ```PV`` <#var-PV>`__ increases, 3982 variable, the list of packages are essential for the machine to boot.
5104 ``PR`` is conventionally reset to "r0". 3983 The impact of this variable affects images based on
5105 3984 ``packagegroup-core-boot``, including the ``core-image-minimal``
5106 .. note:: 3985 image.
5107 3986
5108 The OpenEmbedded build system does not need the aid of 3987 This variable is similar to the
5109 PR 3988 ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception
5110 to know when to rebuild a recipe. The build system uses the task 3989 that the image being built has a build dependency on the variable's
5111 input checksums 3990 list of packages. In other words, the image will not build if a file
5112 along with the 3991 in this list is not found.
5113 stamp 3992
5114 and 3993 As an example, suppose the machine for which you are building
5115 shared state cache 3994 requires ``example-init`` to be run during boot to initialize the
5116 mechanisms. 3995 hardware. In this case, you would use the following in the machine's
5117 3996 ``.conf`` configuration file: MACHINE_ESSENTIAL_EXTRA_RDEPENDS +=
5118 The ``PR`` variable primarily becomes significant when a package 3997 "example-init"
5119 manager dynamically installs packages on an already built image. In 3998
5120 this case, ``PR``, which is the default value of 3999 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
5121 ```PKGR`` <#var-PKGR>`__, helps the package manager distinguish which 4000 A list of recommended machine-specific packages to install as part of
5122 package is the most recent one in cases where many packages have the 4001 the image being built. The build process does not depend on these
5123 same ``PV`` (i.e. ``PKGV``). A component having many packages with 4002 packages being present. However, because this is a
5124 the same ``PV`` usually means that the packages all install the same 4003 "machine-essential" variable, the list of packages are essential for
5125 upstream version, but with later (``PR``) version packages including 4004 the machine to boot. The impact of this variable affects images based
5126 packaging fixes. 4005 on ``packagegroup-core-boot``, including the ``core-image-minimal``
5127 4006 image.
5128 .. note:: 4007
5129 4008 This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS``
5130 PR 4009 variable with the exception that the image being built does not have
5131 does not need to be increased for changes that do not change the 4010 a build dependency on the variable's list of packages. In other
5132 package contents or metadata. 4011 words, the image will still build if a package in this list is not
5133 4012 found. Typically, this variable is used to handle essential kernel
5134 Because manually managing ``PR`` can be cumbersome and error-prone, 4013 modules, whose functionality may be selected to be built into the
5135 an automated solution exists. See the "`Working With a PR 4014 kernel rather than as a module, in which case a package will not be
5136 Service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__" section 4015 produced.
5137 in the Yocto Project Development Tasks Manual for more information. 4016
5138 4017 Consider an example where you have a custom kernel where a specific
5139PREFERRED_PROVIDER 4018 touchscreen driver is required for the machine to be usable. However,
5140 If multiple recipes provide the same item, this variable determines 4019 the driver can be built as a module or into the kernel depending on
5141 which recipe is preferred and thus provides the item (i.e. the 4020 the kernel configuration. If the driver is built as a module, you
5142 preferred provider). You should always suffix this variable with the 4021 want it to be installed. But, when the driver is built into the
5143 name of the provided item. And, you should define the variable using 4022 kernel, you still want the build to succeed. This variable sets up a
5144 the preferred recipe's name (```PN`` <#var-PN>`__). Here is a common 4023 "recommends" relationship so that in the latter case, the build will
5145 example: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" In the 4024 not fail due to the missing package. To accomplish this, assuming the
5146 previous example, multiple recipes are providing "virtual/kernel". 4025 package for the module was called ``kernel-module-ab123``, you would
5147 The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of 4026 use the following in the machine's ``.conf`` configuration file:
5148 the recipe you prefer to provide "virtual/kernel". 4027 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
5149 4028
5150 Following are more examples: PREFERRED_PROVIDER_virtual/xserver = 4029 .. note::
5151 "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" For more 4030
5152 information, see the "`Using Virtual 4031 In this example, the
5153 Providers <&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers>`__" 4032 kernel-module-ab123
5154 section in the Yocto Project Development Tasks Manual. 4033 recipe needs to explicitly set its
5155 4034 PACKAGES
5156 .. note:: 4035 variable to ensure that BitBake does not use the kernel recipe's
5157 4036 PACKAGES_DYNAMIC
5158 If you use a 4037 variable to satisfy the dependency.
5159 virtual/\* 4038
5160 item with 4039 Some examples of these machine essentials are flash, screen,
5161 PREFERRED_PROVIDER 4040 keyboard, mouse, or touchscreen drivers (depending on the machine).
5162 , then any recipe that 4041
5163 PROVIDES 4042 MACHINE_EXTRA_RDEPENDS
5164 that item but is not selected (defined) by 4043 A list of machine-specific packages to install as part of the image
5165 PREFERRED_PROVIDER 4044 being built that are not essential for the machine to boot. However,
5166 is prevented from building, which is usually desirable since this 4045 the build process for more fully-featured images depends on the
5167 mechanism is designed to select between mutually exclusive 4046 packages being present.
5168 alternative providers. 4047
5169 4048 This variable affects all images based on ``packagegroup-base``,
5170PREFERRED_VERSION 4049 which does not include the ``core-image-minimal`` or
5171 If multiple versions of recipes exist, this variable determines which 4050 ``core-image-full-cmdline`` images.
5172 version is given preference. You must always suffix the variable with 4051
5173 the ```PN`` <#var-PN>`__ you want to select, and you should set the 4052 The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable
5174 ```PV`` <#var-PV>`__ accordingly for precedence. 4053 with the exception that the image being built has a build dependency
5175 4054 on the variable's list of packages. In other words, the image will
5176 The ``PREFERRED_VERSION`` variable supports limited wildcard use 4055 not build if a file in this list is not found.
5177 through the "``%``" character. You can use the character to match any 4056
5178 number of characters, which can be useful when specifying versions 4057 An example is a machine that has WiFi capability but is not essential
5179 that contain long revision numbers that potentially change. Here are 4058 for the machine to boot the image. However, if you are building a
5180 two examples: PREFERRED_VERSION_python = "3.4.0" 4059 more fully-featured image, you want to enable the WiFi. The package
5181 PREFERRED_VERSION_linux-yocto = "5.0%" 4060 containing the firmware for the WiFi hardware is always expected to
5182 4061 exist, so it is acceptable for the build process to depend upon
5183 .. note:: 4062 finding the package. In this case, assuming the package for the
5184 4063 firmware was called ``wifidriver-firmware``, you would use the
5185 The use of the " 4064 following in the ``.conf`` file for the machine:
5186 % 4065 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
5187 " character is limited in that it only works at the end of the 4066
5188 string. You cannot use the wildcard character in any other 4067 MACHINE_EXTRA_RRECOMMENDS
5189 location of the string. 4068 A list of machine-specific packages to install as part of the image
5190 4069 being built that are not essential for booting the machine. The image
5191 The specified version is matched against ```PV`` <#var-PV>`__, which 4070 being built has no build dependency on this list of packages.
5192 does not necessarily match the version part of the recipe's filename. 4071
5193 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` 4072 This variable affects only images based on ``packagegroup-base``,
5194 where ``foo_git.bb`` contains the following assignment: PV = 4073 which does not include the ``core-image-minimal`` or
5195 "1.1+git${SRCPV}" In this case, the correct way to select 4074 ``core-image-full-cmdline`` images.
5196 ``foo_git.bb`` is by using an assignment such as the following: 4075
5197 PREFERRED_VERSION_foo = "1.1+git%" Compare that previous example 4076 This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable
5198 against the following incorrect example, which does not work: 4077 with the exception that the image being built does not have a build
5199 PREFERRED_VERSION_foo = "git" 4078 dependency on the variable's list of packages. In other words, the
5200 4079 image will build if a file in this list is not found.
5201 Sometimes the ``PREFERRED_VERSION`` variable can be set by 4080
5202 configuration files in a way that is hard to change. You can use 4081 An example is a machine that has WiFi capability but is not essential
5203 ```OVERRIDES`` <#var-OVERRIDES>`__ to set a machine-specific 4082 For the machine to boot the image. However, if you are building a
5204 override. Here is an example: PREFERRED_VERSION_linux-yocto_qemux86 = 4083 more fully-featured image, you want to enable WiFi. In this case, the
5205 "5.0%" Although not recommended, worst case, you can also use the 4084 package containing the WiFi kernel module will not be produced if the
5206 "forcevariable" override, which is the strongest override possible. 4085 WiFi driver is built into the kernel, in which case you still want
5207 Here is an example: PREFERRED_VERSION_linux-yocto_forcevariable = 4086 the build to succeed instead of failing as a result of the package
5208 "5.0%" 4087 not being found. To accomplish this, assuming the package for the
5209 4088 module was called ``kernel-module-examplewifi``, you would use the
5210 .. note:: 4089 following in the ``.conf`` file for the machine:
5211 4090 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
5212 The 4091
5213 \_forcevariable 4092 MACHINE_FEATURES
5214 override is not handled specially. This override only works 4093 Specifies the list of hardware features the
5215 because the default value of 4094 :term:`MACHINE` is capable of supporting. For related
5216 OVERRIDES 4095 information on enabling features, see the
5217 includes "forcevariable". 4096 :term:`DISTRO_FEATURES`,
5218 4097 :term:`COMBINED_FEATURES`, and
5219PREMIRRORS 4098 :term:`IMAGE_FEATURES` variables.
5220 Specifies additional paths from which the OpenEmbedded build system 4099
5221 gets source code. When the build system searches for source code, it 4100 For a list of hardware features supported by the Yocto Project as
5222 first tries the local download directory. If that location fails, the 4101 shipped, see the "`Machine Features <#ref-features-machine>`__"
5223 build system tries locations defined by ``PREMIRRORS``, the upstream 4102 section.
5224 source, and then locations specified by 4103
5225 ```MIRRORS`` <#var-MIRRORS>`__ in that order. 4104 MACHINE_FEATURES_BACKFILL
5226 4105 Features to be added to ``MACHINE_FEATURES`` if not also present in
5227 Assuming your distribution (```DISTRO`` <#var-DISTRO>`__) is "poky", 4106 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``.
5228 the default value for ``PREMIRRORS`` is defined in the 4107
5229 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. 4108 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
5230 4109 not intended to be user-configurable. It is best to just reference
5231 Typically, you could add a specific server for the build system to 4110 the variable to see which machine features are being backfilled for
5232 attempt before any others by adding something like the following to 4111 all machine configurations. See the "`Feature
5233 the ``local.conf`` configuration file in the `Build 4112 Backfilling <#ref-features-backfill>`__" section for more
5234 Directory <#build-directory>`__: PREMIRRORS_prepend = "\\ 4113 information.
5235 git://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* 4114
5236 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* 4115 MACHINE_FEATURES_BACKFILL_CONSIDERED
5237 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 4116 Features from ``MACHINE_FEATURES_BACKFILL`` that should not be
5238 http://www.yoctoproject.org/sources/ \\n" These changes cause the 4117 backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See
5239 build system to intercept Git, FTP, HTTP, and HTTPS requests and 4118 the "`Feature Backfilling <#ref-features-backfill>`__" section for
5240 direct them to the ``http://`` sources mirror. You can use 4119 more information.
5241 ``file://`` URLs to point to local directories or network shares as 4120
5242 well. 4121 MACHINEOVERRIDES
5243 4122 A colon-separated list of overrides that apply to the current
5244PRIORITY 4123 machine. By default, this list includes the value of
5245 Indicates the importance of a package. 4124 :term:`MACHINE`.
5246 4125
5247 ``PRIORITY`` is considered to be part of the distribution policy 4126 You can extend ``MACHINEOVERRIDES`` to add extra overrides that
5248 because the importance of any given recipe depends on the purpose for 4127 should apply to a machine. For example, all machines emulated in QEMU
5249 which the distribution is being produced. Thus, ``PRIORITY`` is not 4128 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
5250 normally set within recipes. 4129 ``meta/conf/machine/include/qemu.inc`` that prepends the following
5251 4130 override to ``MACHINEOVERRIDES``: MACHINEOVERRIDES =. "qemuall:" This
5252 You can set ``PRIORITY`` to "required", "standard", "extra", and 4131 override allows variables to be overriden for all machines emulated
5253 "optional", which is the default. 4132 in QEMU, like in the following example from the ``connman-conf``
5254 4133 recipe: SRC_URI_append_qemuall = "file://wired.config \\
5255PRIVATE_LIBS 4134 file://wired-setup \\ " The underlying mechanism behind
5256 Specifies libraries installed within a recipe that should be ignored 4135 ``MACHINEOVERRIDES`` is simply that it is included in the default
5257 by the OpenEmbedded build system's shared library resolver. This 4136 value of :term:`OVERRIDES`.
5258 variable is typically used when software being built by a recipe has 4137
5259 its own private versions of a library normally provided by another 4138 MAINTAINER
5260 recipe. In this case, you would not want the package containing the 4139 The email address of the distribution maintainer.
5261 private libraries to be set as a dependency on other unrelated 4140
5262 packages that should instead depend on the package providing the 4141 MIRRORS
5263 standard version of the library. 4142 Specifies additional paths from which the OpenEmbedded build system
5264 4143 gets source code. When the build system searches for source code, it
5265 Libraries specified in this variable should be specified by their 4144 first tries the local download directory. If that location fails, the
5266 file name. For example, from the Firefox recipe in meta-browser: 4145 build system tries locations defined by
5267 PRIVATE_LIBS = "libmozjs.so \\ libxpcom.so \\ libnspr4.so \\ 4146 :term:`PREMIRRORS`, the upstream source, and then
5268 libxul.so \\ libmozalloc.so \\ libplc4.so \\ libplds4.so" 4147 locations specified by ``MIRRORS`` in that order.
5269 4148
5270 For more information, see the "`Automatically Added Runtime 4149 Assuming your distribution (:term:`DISTRO`) is "poky",
5271 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 4150 the default value for ``MIRRORS`` is defined in the
5272 section in the Yocto Project Overview and Concepts Manual. 4151 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
5273 4152
5274PROVIDES 4153 MLPREFIX
5275 A list of aliases by which a particular recipe can be known. By 4154 Specifies a prefix has been added to :term:`PN` to create a
5276 default, a recipe's own ``PN`` is implicitly already in its 4155 special version of a recipe or package (i.e. a Multilib version). The
5277 ``PROVIDES`` list and therefore does not need to mention that it 4156 variable is used in places where the prefix needs to be added to or
5278 provides itself. If a recipe uses ``PROVIDES``, the additional 4157 removed from a the name (e.g. the :term:`BPN` variable).
5279 aliases are synonyms for the recipe and can be useful for satisfying 4158 ``MLPREFIX`` gets set when a prefix has been added to ``PN``.
5280 dependencies of other recipes during the build as specified by 4159
5281 ``DEPENDS``. 4160 .. note::
5282 4161
5283 Consider the following example ``PROVIDES`` statement from the recipe 4162 The "ML" in
5284 file ``eudev_3.2.9.bb``: PROVIDES = "udev" The ``PROVIDES`` statement 4163 MLPREFIX
5285 results in the "eudev" recipe also being available as simply "udev". 4164 stands for "MultiLib". This representation is historical and comes
5286 4165 from a time when
5287 .. note:: 4166 nativesdk
5288 4167 was a suffix rather than a prefix on the recipe name. When
5289 Given that a recipe's own recipe name is already implicitly in its 4168 nativesdk
5290 own 4169 was turned into a prefix, it made sense to set
5291 PROVIDES 4170 MLPREFIX
5292 list, it is unnecessary to add aliases with the "+=" operator; 4171 for it as well.
5293 using a simple assignment will be sufficient. In other words, 4172
5294 while you could write: 4173 To help understand when ``MLPREFIX`` might be needed, consider when
5295 :: 4174 :term:`BBCLASSEXTEND` is used to provide a
5296 4175 ``nativesdk`` version of a recipe in addition to the target version.
5297 PROVIDES += "udev" 4176 If that recipe declares build-time dependencies on tasks in other
5298 4177 recipes by using :term:`DEPENDS`, then a dependency on
5299 4178 "foo" will automatically get rewritten to a dependency on
5300 in the above, the "+=" is overkill and unnecessary. 4179 "nativesdk-foo". However, dependencies like the following will not
5301 4180 get rewritten automatically: do_foo[depends] += "recipe:do_foo" If
5302 In addition to providing recipes under alternate names, the 4181 you want such a dependency to also get transformed, you can do the
5303 ``PROVIDES`` mechanism is also used to implement virtual targets. A 4182 following: do_foo[depends] += "${MLPREFIX}recipe:do_foo"
5304 virtual target is a name that corresponds to some particular 4183
5305 functionality (e.g. a Linux kernel). Recipes that provide the 4184 module_autoload
5306 functionality in question list the virtual target in ``PROVIDES``. 4185 This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD``
5307 Recipes that depend on the functionality in question can include the 4186 variable. You should replace all occurrences of ``module_autoload``
5308 virtual target in ``DEPENDS`` to leave the choice of provider open. 4187 with additions to ``KERNEL_MODULE_AUTOLOAD``, for example:
5309 4188 module_autoload_rfcomm = "rfcomm"
5310 Conventionally, virtual targets have names on the form 4189
5311 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 4190 should now be replaced with: KERNEL_MODULE_AUTOLOAD += "rfcomm" See
5312 of the name and has no syntactical significance. 4191 the :term:`KERNEL_MODULE_AUTOLOAD`
5313 4192 variable for more information.
5314 The ```PREFERRED_PROVIDER`` <#var-PREFERRED_PROVIDER>`__ variable is 4193
5315 used to select which particular recipe provides a virtual target. 4194 module_conf
5316 4195 Specifies ```modprobe.d`http://linux.die.net/man/5/modprobe.d
5317 .. note:: 4196 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
5318 4197 file.
5319 A corresponding mechanism for virtual runtime dependencies 4198
5320 (packages) exists. However, the mechanism does not depend on any 4199 You can use this variable anywhere that it can be recognized by the
5321 special functionality beyond ordinary variable assignments. For 4200 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
5322 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of 4201 configuration file, a distribution configuration file, an append file
5323 the component that manages the ``/dev`` directory. 4202 for the recipe, or the recipe itself). If you use this variable, you
5324 4203 must also be sure to list the module name in the
5325 Setting the "preferred provider" for runtime dependencies is as 4204 :term:`KERNEL_MODULE_AUTOLOAD`
5326 simple as using the following assignment in a configuration file:
5327
5328 ::
5329
5330 VIRTUAL-RUNTIME_dev_manager = "udev"
5331
5332
5333PRSERV_HOST
5334 The network based ```PR`` <#var-PR>`__ service host and port.
5335
5336 The ``conf/local.conf.sample.extended`` configuration file in the
5337 `Source Directory <#source-directory>`__ shows how the
5338 ``PRSERV_HOST`` variable is set: PRSERV_HOST = "localhost:0" You must
5339 set the variable if you want to automatically start a local `PR
5340 service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__. You can
5341 set ``PRSERV_HOST`` to other values to use a remote PR service.
5342
5343PTEST_ENABLED
5344 Specifies whether or not `Package
5345 Test <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__ (ptest)
5346 functionality is enabled when building a recipe. You should not set
5347 this variable directly. Enabling and disabling building Package Tests
5348 at build time should be done by adding "ptest" to (or removing it
5349 from) ```DISTRO_FEATURES`` <#var-DISTRO_FEATURES>`__.
5350
5351PV
5352 The version of the recipe. The version is normally extracted from the
5353 recipe filename. For example, if the recipe is named
5354 ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1".
5355 ``PV`` is generally not overridden within a recipe unless it is
5356 building an unstable (i.e. development) version from a source code
5357 repository (e.g. Git or Subversion).
5358
5359 ``PV`` is the default value of the ```PKGV`` <#var-PKGV>`__ variable.
5360
5361PYTHON_ABI
5362 When used by recipes that inherit the
5363 ```distutils3`` <#ref-classes-distutils3>`__,
5364 ```setuptools3`` <#ref-classes-setuptools3>`__,
5365 ```distutils`` <#ref-classes-distutils>`__, or
5366 ```setuptools`` <#ref-classes-setuptools>`__ classes, denotes the
5367 Application Binary Interface (ABI) currently in use for Python. By
5368 default, the ABI is "m". You do not have to set this variable as the
5369 OpenEmbedded build system sets it for you.
5370
5371 The OpenEmbedded build system uses the ABI to construct directory
5372 names used when installing the Python headers and libraries in
5373 sysroot (e.g. ``.../python3.3m/...``).
5374
5375 Recipes that inherit the ``distutils`` class during cross-builds also
5376 use this variable to locate the headers and libraries of the
5377 appropriate Python that the extension is targeting.
5378
5379PYTHON_PN
5380 When used by recipes that inherit the
5381 ```distutils3`` <#ref-classes-distutils3>`__,
5382 ```setuptools3`` <#ref-classes-setuptools3>`__,
5383 ```distutils`` <#ref-classes-distutils>`__, or
5384 ```setuptools`` <#ref-classes-setuptools>`__ classes, specifies the
5385 major Python version being built. For Python 3.x, ``PYTHON_PN`` would
5386 be "python3". You do not have to set this variable as the
5387 OpenEmbedded build system automatically sets it for you.
5388
5389 The variable allows recipes to use common infrastructure such as the
5390 following: DEPENDS += "${PYTHON_PN}-native" In the previous example,
5391 the version of the dependency is ``PYTHON_PN``.
5392
5393RANLIB
5394 The minimal command and arguments to run ``ranlib``.
5395
5396RCONFLICTS
5397 The list of packages that conflict with packages. Note that packages
5398 will not be installed if conflicting packages are not first removed.
5399
5400 Like all package-controlling variables, you must always use them in
5401 conjunction with a package name override. Here is an example:
5402 RCONFLICTS_${PN} = "another_conflicting_package_name"
5403
5404 BitBake, which the OpenEmbedded build system uses, supports
5405 specifying versioned dependencies. Although the syntax varies
5406 depending on the packaging format, BitBake hides these differences
5407 from you. Here is the general syntax to specify versions with the
5408 ``RCONFLICTS`` variable: RCONFLICTS_${PN} = "package (operator
5409 version)" For ``operator``, you can specify the following: = < > <=
5410 >= For example, the following sets up a dependency on version 1.2 or
5411 greater of the package ``foo``: RCONFLICTS_${PN} = "foo (>= 1.2)"
5412
5413RDEPENDS
5414 Lists runtime dependencies of a package. These dependencies are other
5415 packages that must be installed in order for the package to function
5416 correctly. As an example, the following assignment declares that the
5417 package ``foo`` needs the packages ``bar`` and ``baz`` to be
5418 installed: RDEPENDS_foo = "bar baz" The most common types of package
5419 runtime dependencies are automatically detected and added. Therefore,
5420 most recipes do not need to set ``RDEPENDS``. For more information,
5421 see the "`Automatically Added Runtime
5422 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
5423 section in the Yocto Project Overview and Concepts Manual.
5424
5425 The practical effect of the above ``RDEPENDS`` assignment is that
5426 ``bar`` and ``baz`` will be declared as dependencies inside the
5427 package ``foo`` when it is written out by one of the
5428 ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks.
5429 Exactly how this is done depends on which package format is used,
5430 which is determined by
5431 ```PACKAGE_CLASSES`` <#var-PACKAGE_CLASSES>`__. When the
5432 corresponding package manager installs the package, it will know to
5433 also install the packages on which it depends.
5434
5435 To ensure that the packages ``bar`` and ``baz`` get built, the
5436 previous ``RDEPENDS`` assignment also causes a task dependency to be
5437 added. This dependency is from the recipe's
5438 ```do_build`` <#ref-tasks-build>`__ (not to be confused with
5439 ```do_compile`` <#ref-tasks-compile>`__) task to the
5440 ``do_package_write_*`` task of the recipes that build ``bar`` and
5441 ``baz``.
5442
5443 The names of the packages you list within ``RDEPENDS`` must be the
5444 names of other packages - they cannot be recipe names. Although
5445 package names and recipe names usually match, the important point
5446 here is that you are providing package names within the ``RDEPENDS``
5447 variable. For an example of the default list of packages created from
5448 a recipe, see the ```PACKAGES`` <#var-PACKAGES>`__ variable.
5449
5450 Because the ``RDEPENDS`` variable applies to packages being built,
5451 you should always use the variable in a form with an attached package
5452 name (remember that a single recipe can build multiple packages). For
5453 example, suppose you are building a development package that depends
5454 on the ``perl`` package. In this case, you would use the following
5455 ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the example,
5456 the development package depends on the ``perl`` package. Thus, the
5457 ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of
5458 the variable.
5459
5460 .. note::
5461
5462 RDEPENDS_${PN}-dev
5463 includes
5464 ${
5465 PN
5466 }
5467 by default. This default is set in the BitBake configuration file
5468 (
5469 meta/conf/bitbake.conf
5470 ). Be careful not to accidentally remove
5471 ${PN}
5472 when modifying
5473 RDEPENDS_${PN}-dev
5474 . Use the "+=" operator rather than the "=" operator.
5475
5476 The package names you use with ``RDEPENDS`` must appear as they would
5477 in the ``PACKAGES`` variable. The ```PKG`` <#var-PKG>`__ variable
5478 allows a different name to be used for the final package (e.g. the
5479 ```debian`` <#ref-classes-debian>`__ class uses this to rename
5480 packages), but this final package name cannot be used with
5481 ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be
5482 independent of the package format used.
5483
5484 BitBake, which the OpenEmbedded build system uses, supports
5485 specifying versioned dependencies. Although the syntax varies
5486 depending on the packaging format, BitBake hides these differences
5487 from you. Here is the general syntax to specify versions with the
5488 ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator version)"
5489 For operator, you can specify the following: = < > <= >= For version,
5490 provide the version number.
5491
5492 .. note::
5493
5494 You can use
5495 EXTENDPKGV
5496 to provide a full package version specification.
5497
5498 For example, the following sets up a dependency on version 1.2 or
5499 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
5500
5501 For information on build-time dependencies, see the
5502 ```DEPENDS`` <#var-DEPENDS>`__ variable. You can also see the
5503 "`Tasks <&YOCTO_DOCS_BB_URL;#tasks>`__" and
5504 "`Dependencies <&YOCTO_DOCS_BB_URL;#dependencies>`__" sections in the
5505 BitBake User Manual for additional information on tasks and
5506 dependencies.
5507
5508REQUIRED_DISTRO_FEATURES
5509 When inheriting the
5510 ```distro_features_check`` <#ref-classes-distro_features_check>`__
5511 class, this variable identifies distribution features that must exist
5512 in the current configuration in order for the OpenEmbedded build
5513 system to build the recipe. In other words, if the
5514 ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not
5515 appear in ``DISTRO_FEATURES`` within the current configuration, an
5516 error occurs and the build stops.
5517
5518RM_WORK_EXCLUDE
5519 With ``rm_work`` enabled, this variable specifies a list of recipes
5520 whose work directories should not be removed. See the
5521 "```rm_work.bbclass`` <#ref-classes-rm-work>`__" section for more
5522 details.
5523
5524ROOT_HOME
5525 Defines the root home directory. By default, this directory is set as
5526 follows in the BitBake configuration file: ROOT_HOME ??= "/home/root"
5527
5528 .. note::
5529
5530 This default value is likely used because some embedded solutions
5531 prefer to have a read-only root filesystem and prefer to keep
5532 writeable data in one place.
5533
5534 You can override the default by setting the variable in any layer or
5535 in the ``local.conf`` file. Because the default is set using a "weak"
5536 assignment (i.e. "??="), you can use either of the following forms to
5537 define your override: ROOT_HOME = "/root" ROOT_HOME ?= "/root" These
5538 override examples use ``/root``, which is probably the most commonly
5539 used override.
5540
5541ROOTFS
5542 Indicates a filesystem image to include as the root filesystem.
5543
5544 The ``ROOTFS`` variable is an optional variable used with the
5545 ```image-live`` <#ref-classes-image-live>`__ class.
5546
5547ROOTFS_POSTINSTALL_COMMAND
5548 Specifies a list of functions to call after the OpenEmbedded build
5549 system has installed packages. You can specify functions separated by
5550 semicolons: ROOTFS_POSTINSTALL_COMMAND += "function; ... "
5551
5552 If you need to pass the root filesystem path to a command within a
5553 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5554 directory that becomes the root filesystem image. See the
5555 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more
5556 information.
5557
5558ROOTFS_POSTPROCESS_COMMAND
5559 Specifies a list of functions to call once the OpenEmbedded build
5560 system has created the root filesystem. You can specify functions
5561 separated by semicolons: ROOTFS_POSTPROCESS_COMMAND += "function; ...
5562 "
5563
5564 If you need to pass the root filesystem path to a command within a
5565 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5566 directory that becomes the root filesystem image. See the
5567 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more
5568 information.
5569
5570ROOTFS_POSTUNINSTALL_COMMAND
5571 Specifies a list of functions to call after the OpenEmbedded build
5572 system has removed unnecessary packages. When runtime package
5573 management is disabled in the image, several packages are removed
5574 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
5575 You can specify functions separated by semicolons:
5576 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... "
5577
5578 If you need to pass the root filesystem path to a command within a
5579 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5580 directory that becomes the root filesystem image. See the
5581 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more
5582 information.
5583
5584ROOTFS_PREPROCESS_COMMAND
5585 Specifies a list of functions to call before the OpenEmbedded build
5586 system has created the root filesystem. You can specify functions
5587 separated by semicolons: ROOTFS_PREPROCESS_COMMAND += "function; ...
5588 "
5589
5590 If you need to pass the root filesystem path to a command within a
5591 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5592 directory that becomes the root filesystem image. See the
5593 ```IMAGE_ROOTFS`` <#var-IMAGE_ROOTFS>`__ variable for more
5594 information.
5595
5596RPROVIDES
5597 A list of package name aliases that a package also provides. These
5598 aliases are useful for satisfying runtime dependencies of other
5599 packages both during the build and on the target (as specified by
5600 ``RDEPENDS``).
5601
5602 .. note::
5603
5604 A package's own name is implicitly already in its
5605 RPROVIDES
5606 list.
5607
5608 As with all package-controlling variables, you must always use the
5609 variable in conjunction with a package name override. Here is an
5610 example: RPROVIDES_${PN} = "widget-abi-2"
5611
5612RRECOMMENDS
5613 A list of packages that extends the usability of a package being
5614 built. The package being built does not depend on this list of
5615 packages in order to successfully build, but rather uses them for
5616 extended usability. To specify runtime dependencies for packages, see
5617 the ``RDEPENDS`` variable.
5618
5619 The package manager will automatically install the ``RRECOMMENDS``
5620 list of packages when installing the built package. However, you can
5621 prevent listed packages from being installed by using the
5622 ```BAD_RECOMMENDATIONS`` <#var-BAD_RECOMMENDATIONS>`__,
5623 ```NO_RECOMMENDATIONS`` <#var-NO_RECOMMENDATIONS>`__, and
5624 ```PACKAGE_EXCLUDE`` <#var-PACKAGE_EXCLUDE>`__ variables.
5625
5626 Packages specified in ``RRECOMMENDS`` need not actually be produced.
5627 However, a recipe must exist that provides each package, either
5628 through the ```PACKAGES`` <#var-PACKAGES>`__ or
5629 ```PACKAGES_DYNAMIC`` <#var-PACKAGES_DYNAMIC>`__ variables or the
5630 ```RPROVIDES`` <#var-RPROVIDES>`__ variable, or an error will occur
5631 during the build. If such a recipe does exist and the package is not
5632 produced, the build continues without error.
5633
5634 Because the ``RRECOMMENDS`` variable applies to packages being built,
5635 you should always attach an override to the variable to specify the
5636 particular package whose usability is being extended. For example,
5637 suppose you are building a development package that is extended to
5638 support wireless functionality. In this case, you would use the
5639 following: RRECOMMENDS_${PN}-dev += "wireless_package_name" In the
5640 example, the package name (``${PN}-dev``) must appear as it would in
5641 the ``PACKAGES`` namespace before any renaming of the output package
5642 by classes such as ``debian.bbclass``.
5643
5644 BitBake, which the OpenEmbedded build system uses, supports
5645 specifying versioned recommends. Although the syntax varies depending
5646 on the packaging format, BitBake hides these differences from you.
5647 Here is the general syntax to specify versions with the
5648 ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package (operator
5649 version)" For ``operator``, you can specify the following: = < > <=
5650 >= For example, the following sets up a recommend on version 1.2 or
5651 greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>= 1.2)"
5652
5653RREPLACES
5654 A list of packages replaced by a package. The package manager uses
5655 this variable to determine which package should be installed to
5656 replace other package(s) during an upgrade. In order to also have the
5657 other package(s) removed at the same time, you must add the name of
5658 the other package to the ``RCONFLICTS`` variable.
5659
5660 As with all package-controlling variables, you must use this variable
5661 in conjunction with a package name override. Here is an example:
5662 RREPLACES_${PN} = "other_package_being_replaced"
5663
5664 BitBake, which the OpenEmbedded build system uses, supports
5665 specifying versioned replacements. Although the syntax varies
5666 depending on the packaging format, BitBake hides these differences
5667 from you. Here is the general syntax to specify versions with the
5668 ``RREPLACES`` variable: RREPLACES_${PN} = "package (operator
5669 version)" For ``operator``, you can specify the following: = < > <=
5670 >= For example, the following sets up a replacement using version 1.2
5671 or greater of the package ``foo``: RREPLACES_${PN} = "foo (>= 1.2)"
5672
5673RSUGGESTS
5674 A list of additional packages that you can suggest for installation
5675 by the package manager at the time a package is installed. Not all
5676 package managers support this functionality.
5677
5678 As with all package-controlling variables, you must always use this
5679 variable in conjunction with a package name override. Here is an
5680 example: RSUGGESTS_${PN} = "useful_package another_package"
5681
5682S
5683 The location in the `Build Directory <#build-directory>`__ where
5684 unpacked recipe source code resides. By default, this directory is
5685 ``${``\ ```WORKDIR`` <#var-WORKDIR>`__\ ``}/${``\ ```BPN`` <#var-BPN>`__\ ``}-${``\ ```PV`` <#var-PV>`__\ ``}``,
5686 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
5687 version. If the source tarball extracts the code to a directory named
5688 anything other than ``${BPN}-${PV}``, or if the source code is
5689 fetched from an SCM such as Git or Subversion, then you must set
5690 ``S`` in the recipe so that the OpenEmbedded build system knows where
5691 to find the unpacked source.
5692
5693 As an example, assume a `Source Directory <#source-directory>`__
5694 top-level folder named ``poky`` and a default Build Directory at
5695 ``poky/build``. In this case, the work directory the build system
5696 uses to keep the unpacked recipe for ``db`` is the following:
5697 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 The
5698 unpacked source code resides in the ``db-5.1.19`` folder.
5699
5700 This next example assumes a Git repository. By default, Git
5701 repositories are cloned to ``${WORKDIR}/git`` during
5702 ```do_fetch`` <#ref-tasks-fetch>`__. Since this path is different
5703 from the default value of ``S``, you must set it specifically so the
5704 source can be located: SRC_URI = "git://path/to/repo.git" S =
5705 "${WORKDIR}/git"
5706
5707SANITY_REQUIRED_UTILITIES
5708 Specifies a list of command-line utilities that should be checked for
5709 during the initial sanity checking process when running BitBake. If
5710 any of the utilities are not installed on the build host, then
5711 BitBake immediately exits with an error.
5712
5713SANITY_TESTED_DISTROS
5714 A list of the host distribution identifiers that the build system has
5715 been tested against. Identifiers consist of the host distributor ID
5716 followed by the release, as reported by the ``lsb_release`` tool or
5717 as read from ``/etc/lsb-release``. Separate the list items with
5718 explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is
5719 not empty and the current value of
5720 ```NATIVELSBSTRING`` <#var-NATIVELSBSTRING>`__ does not appear in the
5721 list, then the build system reports a warning that indicates the
5722 current host distribution has not been tested as a build host.
5723
5724SDK_ARCH
5725 The target architecture for the SDK. Typically, you do not directly
5726 set this variable. Instead, use ```SDKMACHINE`` <#var-SDKMACHINE>`__.
5727
5728SDK_DEPLOY
5729 The directory set up and used by the
5730 ```populate_sdk_base`` <#ref-classes-populate-sdk>`__ class to which
5731 the SDK is deployed. The ``populate_sdk_base`` class defines
5732 ``SDK_DEPLOY`` as follows: SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
5733
5734SDK_DIR
5735 The parent directory used by the OpenEmbedded build system when
5736 creating SDK output. The
5737 ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class defines
5738 the variable as follows: SDK_DIR = "${WORKDIR}/sdk"
5739
5740 .. note::
5741
5742 The
5743 SDK_DIR
5744 directory is a temporary directory as it is part of
5745 WORKDIR
5746 . The final output directory is
5747 SDK_DEPLOY
5748 .
5749
5750SDK_EXT_TYPE
5751 Controls whether or not shared state artifacts are copied into the
5752 extensible SDK. The default value of "full" copies all of the
5753 required shared state artifacts into the extensible SDK. The value
5754 "minimal" leaves these artifacts out of the SDK.
5755
5756 .. note::
5757
5758 If you set the variable to "minimal", you need to ensure
5759 SSTATE_MIRRORS
5760 is set in the SDK's configuration to enable the artifacts to be
5761 fetched as needed.
5762
5763SDK_HOST_MANIFEST
5764 The manifest file for the host part of the SDK. This file lists all
5765 the installed packages that make up the host part of the SDK. The
5766 file contains package information on a line-per-package basis as
5767 follows: packagename packagearch version
5768
5769 The ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class
5770 defines the manifest file as follows: SDK_HOST_MANIFEST =
5771 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" The location is
5772 derived using the ```SDK_DEPLOY`` <#var-SDK_DEPLOY>`__ and
5773 ```TOOLCHAIN_OUTPUTNAME`` <#var-TOOLCHAIN_OUTPUTNAME>`__ variables.
5774
5775SDK_INCLUDE_PKGDATA
5776 When set to "1", specifies to include the packagedata for all recipes
5777 in the "world" target in the extensible SDK. Including this data
5778 allows the ``devtool search`` command to find these recipes in search
5779 results, as well as allows the ``devtool add`` command to map
5780 dependencies more effectively.
5781
5782 .. note::
5783
5784 Enabling the
5785 SDK_INCLUDE_PKGDATA
5786 variable significantly increases build time because all of world
5787 needs to be built. Enabling the variable also slightly increases
5788 the size of the extensible SDK.
5789
5790SDK_INCLUDE_TOOLCHAIN
5791 When set to "1", specifies to include the toolchain in the extensible
5792 SDK. Including the toolchain is useful particularly when
5793 ```SDK_EXT_TYPE`` <#var-SDK_EXT_TYPE>`__ is set to "minimal" to keep
5794 the SDK reasonably small but you still want to provide a usable
5795 toolchain. For example, suppose you want to use the toolchain from an
5796 IDE or from other tools and you do not want to perform additional
5797 steps to install the toolchain.
5798
5799 The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if
5800 ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if
5801 ``SDK_EXT_TYPE`` is set to "full".
5802
5803SDK_INHERIT_BLACKLIST
5804 A list of classes to remove from the ```INHERIT`` <#var-INHERIT>`__
5805 value globally within the extensible SDK configuration. The
5806 ```populate-sdk-ext`` <#ref-classes-populate-sdk-*>`__ class sets the
5807 default value: SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
5808
5809 Some classes are not generally applicable within the extensible SDK
5810 context. You can use this variable to disable those classes.
5811
5812 For additional information on how to customize the extensible SDK's
5813 configuration, see the "`Configuring the Extensible
5814 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5815 section in the Yocto Project Application Development and the
5816 Extensible Software Development Kit (eSDK) manual.
5817
5818SDK_LOCAL_CONF_BLACKLIST
5819 A list of variables not allowed through from the OpenEmbedded build
5820 system configuration into the extensible SDK configuration. Usually,
5821 these are variables that are specific to the machine on which the
5822 build system is running and thus would be potentially problematic
5823 within the extensible SDK.
5824
5825 By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the
5826 ```populate-sdk-ext`` <#ref-classes-populate-sdk-*>`__ class and
5827 excludes the following variables:
5828 `CONF_VERSION <#var-CONF_VERSION>`__
5829 `BB_NUMBER_THREADS <#var-BB_NUMBER_THREADS>`__
5830 `BB_NUMBER_PARSE_THREADS <&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS>`__
5831 `PARALLEL_MAKE <#var-PARALLEL_MAKE>`__
5832 `PRSERV_HOST <#var-PRSERV_HOST>`__
5833 `SSTATE_MIRRORS <#var-SSTATE_MIRRORS>`__ `DL_DIR <#var-DL_DIR>`__
5834 `SSTATE_DIR <#var-SSTATE_DIR>`__ `TMPDIR <#var-TMPDIR>`__
5835 `BB_SERVER_TIMEOUT <#var-BB_SERVER_TIMEOUT>`__
5836
5837 For additional information on how to customize the extensible SDK's
5838 configuration, see the "`Configuring the Extensible
5839 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5840 section in the Yocto Project Application Development and the
5841 Extensible Software Development Kit (eSDK) manual.
5842
5843SDK_LOCAL_CONF_WHITELIST
5844 A list of variables allowed through from the OpenEmbedded build
5845 system configuration into the extensible SDK configuration. By
5846 default, the list of variables is empty and is set in the
5847 ```populate-sdk-ext`` <#ref-classes-populate-sdk-*>`__ class.
5848
5849 This list overrides the variables specified using the
5850 ```SDK_LOCAL_CONF_BLACKLIST`` <#var-SDK_LOCAL_CONF_BLACKLIST>`__
5851 variable as well as any variables identified by automatic
5852 blacklisting due to the "/" character being found at the start of the
5853 value, which is usually indicative of being a path and thus might not
5854 be valid on the system where the SDK is installed.
5855
5856 For additional information on how to customize the extensible SDK's
5857 configuration, see the "`Configuring the Extensible
5858 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5859 section in the Yocto Project Application Development and the
5860 Extensible Software Development Kit (eSDK) manual.
5861
5862SDK_NAME
5863 The base name for SDK output files. The name is derived from the
5864 ```DISTRO`` <#var-DISTRO>`__, ```TCLIBC`` <#var-TCLIBC>`__,
5865 ```SDK_ARCH`` <#var-SDK_ARCH>`__,
5866 ```IMAGE_BASENAME`` <#var-IMAGE_BASENAME>`__, and
5867 ```TUNE_PKGARCH`` <#var-TUNE_PKGARCH>`__ variables: SDK_NAME =
5868 "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
5869
5870SDK_OS
5871 Specifies the operating system for which the SDK will be built. The
5872 default value is the value of ```BUILD_OS`` <#var-BUILD_OS>`__.
5873
5874SDK_OUTPUT
5875 The location used by the OpenEmbedded build system when creating SDK
5876 output. The ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__
5877 class defines the variable as follows: SDK_DIR = "${WORKDIR}/sdk"
5878 SDK_OUTPUT = "${SDK_DIR}/image" SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
5879
5880 .. note::
5881
5882 The
5883 SDK_OUTPUT
5884 directory is a temporary directory as it is part of
5885 WORKDIR
5886 by way of
5887 SDK_DIR
5888 . The final output directory is
5889 SDK_DEPLOY
5890 .
5891
5892SDK_PACKAGE_ARCHS
5893 Specifies a list of architectures compatible with the SDK machine.
5894 This variable is set automatically and should not normally be
5895 hand-edited. Entries are separated using spaces and listed in order
5896 of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any
5897 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
5898
5899SDK_POSTPROCESS_COMMAND
5900 Specifies a list of functions to call once the OpenEmbedded build
5901 system creates the SDK. You can specify functions separated by
5902 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... "
5903
5904 If you need to pass an SDK path to a command within a function, you
5905 can use ``${SDK_DIR}``, which points to the parent directory used by
5906 the OpenEmbedded build system when creating SDK output. See the
5907 ```SDK_DIR`` <#var-SDK_DIR>`__ variable for more information.
5908
5909SDK_PREFIX
5910 The toolchain binary prefix used for ``nativesdk`` recipes. The
5911 OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the
5912 ```TARGET_PREFIX`` <#var-TARGET_PREFIX>`__ when building
5913 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
5914
5915SDK_RECRDEP_TASKS
5916 A list of shared state tasks added to the extensible SDK. By default,
5917 the following tasks are added: do_populate_lic do_package_qa
5918 do_populate_sysroot do_deploy Despite the default value of "" for the
5919 ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added
5920 to the SDK. To specify tasks beyond these four, you need to use the
5921 ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional
5922 tasks that are needed in order to build
5923 ```SDK_TARGETS`` <#var-SDK_TARGETS>`__).
5924
5925SDK_SYS
5926 Specifies the system, including the architecture and the operating
5927 system, for which the SDK will be built.
5928
5929 The OpenEmbedded build system automatically sets this variable based
5930 on ```SDK_ARCH`` <#var-SDK_ARCH>`__,
5931 ```SDK_VENDOR`` <#var-SDK_VENDOR>`__, and
5932 ```SDK_OS`` <#var-SDK_OS>`__. You do not need to set the ``SDK_SYS``
5933 variable yourself.
5934
5935SDK_TARGET_MANIFEST
5936 The manifest file for the target part of the SDK. This file lists all
5937 the installed packages that make up the target part of the SDK. The
5938 file contains package information on a line-per-package basis as
5939 follows: packagename packagearch version
5940
5941 The ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class
5942 defines the manifest file as follows: SDK_TARGET_MANIFEST =
5943 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" The location
5944 is derived using the ```SDK_DEPLOY`` <#var-SDK_DEPLOY>`__ and
5945 ```TOOLCHAIN_OUTPUTNAME`` <#var-TOOLCHAIN_OUTPUTNAME>`__ variables.
5946
5947SDK_TARGETS
5948 A list of targets to install from shared state as part of the
5949 standard or extensible SDK installation. The default value is "${PN}"
5950 (i.e. the image from which the SDK is built).
5951
5952 The ``SDK_TARGETS`` variable is an internal variable and typically
5953 would not be changed.
5954
5955SDK_TITLE
5956 The title to be printed when running the SDK installer. By default,
5957 this title is based on the ```DISTRO_NAME`` <#var-DISTRO_NAME>`__ or
5958 ```DISTRO`` <#var-DISTRO>`__ variable and is set in the
5959 ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class as
5960 follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or
5961 d.getVar('DISTRO')} SDK" For the default distribution "poky",
5962 ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)".
5963
5964 For information on how to change this default title, see the
5965 "`Changing the Extensible SDK Installer
5966 Title <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title>`__"
5967 section in the Yocto Project Application Development and the
5968 Extensible Software Development Kit (eSDK) manual.
5969
5970SDK_UPDATE_URL
5971 An optional URL for an update server for the extensible SDK. If set,
5972 the value is used as the default update server when running
5973 ``devtool sdk-update`` within the extensible SDK.
5974
5975SDK_VENDOR
5976 Specifies the name of the SDK vendor.
5977
5978SDK_VERSION
5979 Specifies the version of the SDK. The distribution configuration file
5980 (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the
5981 ``SDK_VERSION`` as follows: SDK_VERSION =
5982 "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
5983
5984 For additional information, see the
5985 ```DISTRO_VERSION`` <#var-DISTRO_VERSION>`__ and
5986 ```DATE`` <#var-DATE>`__ variables.
5987
5988SDKEXTPATH
5989 The default installation directory for the Extensible SDK. By
5990 default, this directory is based on the ```DISTRO`` <#var-DISTRO>`__
5991 variable and is set in the
5992 ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class as
5993 follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" For the
5994 default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk".
5995
5996 For information on how to change this default directory, see the
5997 "`Changing the Default SDK Installation
5998 Directory <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory>`__"
5999 section in the Yocto Project Application Development and the
6000 Extensible Software Development Kit (eSDK) manual.
6001
6002SDKIMAGE_FEATURES
6003 Equivalent to ``IMAGE_FEATURES``. However, this variable applies to
6004 the SDK generated from an image using the following command: $
6005 bitbake -c populate_sdk imagename
6006
6007SDKMACHINE
6008 The machine for which the SDK is built. In other words, the SDK is
6009 built such that it runs on the target you specify with the
6010 ``SDKMACHINE`` value. The value points to a corresponding ``.conf``
6011 file under ``conf/machine-sdk/``.
6012
6013 You can use "i686" and "x86_64" as possible values for this variable.
6014 The variable defaults to "i686" and is set in the local.conf file in
6015 the Build Directory. SDKMACHINE ?= "i686"
6016
6017 .. note::
6018
6019 You cannot set the
6020 SDKMACHINE
6021 variable in your distribution configuration file. If you do, the
6022 configuration will not take affect.
6023
6024SDKPATH
6025 Defines the path offered to the user for installation of the SDK that
6026 is generated by the OpenEmbedded build system. The path appears as
6027 the default location for installing the SDK when you run the SDK's
6028 installation script. You can override the offered path when you run
6029 the script.
6030
6031SDKTARGETSYSROOT
6032 The full path to the sysroot used for cross-compilation within an SDK
6033 as it will be when installed into the default
6034 ```SDKPATH`` <#var-SDKPATH>`__.
6035
6036SECTION
6037 The section in which packages should be categorized. Package
6038 management utilities can make use of this variable.
6039
6040SELECTED_OPTIMIZATION
6041 Specifies the optimization flags passed to the C compiler when
6042 building for the target. The flags are passed through the default
6043 value of the ```TARGET_CFLAGS`` <#var-TARGET_CFLAGS>`__ variable.
6044
6045 The ``SELECTED_OPTIMIZATION`` variable takes the value of
6046 ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the
6047 case, the value of ``DEBUG_OPTIMIZATION`` is used.
6048
6049SERIAL_CONSOLE
6050 Defines a serial console (TTY) to enable using
6051 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6052 value that specifies the baud rate followed by the TTY device name
6053 separated by a space. You cannot specify more than one TTY device:
6054 SERIAL_CONSOLE = "115200 ttyS0"
6055
6056 .. note::
6057
6058 The
6059 SERIAL_CONSOLE
6060 variable is deprecated. Please use the
6061 SERIAL_CONSOLES
6062 variable. 4205 variable.
6063 4206
6064SERIAL_CONSOLES 4207 Here is the general syntax: module_conf_module_name =
6065 Defines a serial console (TTY) to enable using 4208 "modprobe.d-syntax" You must use the kernel module name override.
6066 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a 4209
6067 value that specifies the baud rate followed by the TTY device name 4210 Run ``man modprobe.d`` in the shell to find out more information on
6068 separated by a semicolon. Use spaces to separate multiple devices: 4211 the exact syntax you want to provide with ``module_conf``.
6069 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 4212
6070 4213 Including ``module_conf`` causes the OpenEmbedded build system to
6071SERIAL_CONSOLES_CHECK 4214 populate the ``/etc/modprobe.d/modname.conf`` file with
6072 Specifies serial consoles, which must be listed in 4215 ``modprobe.d`` syntax lines. Here is an example that adds the options
6073 ```SERIAL_CONSOLES`` <#var-SERIAL_CONSOLES>`__, to check against 4216 ``arg1`` and ``arg2`` to a module named ``mymodule``:
6074 ``/proc/console`` before enabling them using getty. This variable 4217 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
6075 allows aliasing in the format: <device>:<alias>. If a device was 4218
6076 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in 4219 For information on how to specify kernel modules to auto-load on
6077 ``/proc/console``, you would do the following: SERIAL_CONSOLES_CHECK 4220 boot, see the
6078 = "slcp_line0:ttyS0" This variable is currently only supported with 4221 :term:`KERNEL_MODULE_AUTOLOAD`
6079 SysVinit (i.e. not with systemd). 4222 variable.
6080 4223
6081SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS 4224 MODULE_TARBALL_DEPLOY
6082 A list of recipe dependencies that should not be used to determine 4225 Controls creation of the ``modules-*.tgz`` file. Set this variable to
6083 signatures of tasks from one recipe when they depend on tasks from 4226 "0" to disable creation of this file, which contains all of the
6084 another recipe. For example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += 4227 kernel modules resulting from a kernel build.
6085 "intone->mplayer2" 4228
6086 4229 MODULE_TARBALL_LINK_NAME
6087 In the previous example, ``intone`` depends on ``mplayer2``. 4230 The link name of the kernel module tarball. This variable is set in
6088 4231 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
6089 You can use the special token ``"*"`` on the left-hand side of the 4232 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value
6090 dependency to match all recipes except the one on the right-hand 4233 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
6091 side. Here is an example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += 4234 same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?=
6092 "*->quilt-native" 4235 "${MACHINE}"
6093 4236
6094 In the previous example, all recipes except ``quilt-native`` ignore 4237 See the :term:`MACHINE` variable for additional
6095 task signatures from the ``quilt-native`` recipe when determining 4238 information.
6096 their task signatures. 4239
6097 4240 MODULE_TARBALL_NAME
6098 Use of this variable is one mechanism to remove dependencies that 4241 The base name of the kernel module tarball. This variable is set in
6099 affect task signatures and thus force rebuilds when a recipe changes. 4242 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
6100 4243 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the
6101 .. note:: 4244 :term:`KERNEL_ARTIFACT_NAME` variable,
6102 4245 which is set in the same file, has the following value:
6103 If you add an inappropriate dependency for a recipe relationship, 4246 KERNEL_ARTIFACT_NAME ?=
6104 the software might break during runtime if the interface of the 4247 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
6105 second recipe was changed after the first recipe had been built. 4248
6106 4249 MULTIMACH_TARGET_SYS
6107SIGGEN_EXCLUDERECIPES_ABISAFE 4250 Uniquely identifies the type of the target system for which packages
6108 A list of recipes that are completely stable and will never change. 4251 are being built. This variable allows output for different types of
6109 The ABI for the recipes in the list are presented by output from the 4252 target systems to be put into different subdirectories of the same
6110 tasks run to build the recipe. Use of this variable is one way to 4253 output directory.
6111 remove dependencies from one recipe on another that affect task 4254
6112 signatures and thus force rebuilds when the recipe changes. 4255 The default value of this variable is:
6113 4256 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} Some classes (e.g.
6114 .. note:: 4257 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the
6115 4258 ``MULTIMACH_TARGET_SYS`` value.
6116 If you add an inappropriate variable to this list, the software 4259
6117 might break at runtime if the interface of the recipe was changed 4260 See the :term:`STAMP` variable for an example. See the
6118 after the other had been built. 4261 :term:`STAGING_DIR_TARGET` variable for
6119 4262 more information.
6120SITEINFO_BITS 4263
6121 Specifies the number of bits for the target system CPU. The value 4264 NATIVELSBSTRING
6122 should be either "32" or "64". 4265 A string identifying the host distribution. Strings consist of the
6123 4266 host distributor ID followed by the release, as reported by the
6124SITEINFO_ENDIANNESS 4267 ``lsb_release`` tool or as read from ``/etc/lsb-release``. For
6125 Specifies the endian byte order of the target system. The value 4268 example, when running a build on Ubuntu 12.10, the value is
6126 should be either "le" for little-endian or "be" for big-endian. 4269 "Ubuntu-12.10". If this information is unable to be determined, the
6127 4270 value resolves to "Unknown".
6128SKIP_FILEDEPS 4271
6129 Enables removal of all files from the "Provides" section of an RPM 4272 This variable is used by default to isolate native shared state
6130 package. Removal of these files is required for packages containing 4273 packages for different distributions (e.g. to avoid problems with
6131 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. 4274 ``glibc`` version incompatibilities). Additionally, the variable is
6132 4275 checked against
6133 To enable file removal, set the variable to "1" in your 4276 :term:`SANITY_TESTED_DISTROS` if that
6134 ``conf/local.conf`` configuration file in your: `Build 4277 variable is set.
6135 Directory <#build-directory>`__. SKIP_FILEDEPS = "1" 4278
6136 4279 NM
6137SOC_FAMILY 4280 The minimal command and arguments to run ``nm``.
6138 Groups together machines based upon the same family of SOC (System On 4281
6139 Chip). You typically set this variable in a common ``.inc`` file that 4282 NO_GENERIC_LICENSE
6140 you include in the configuration files of all the machines. 4283 Avoids QA errors when you use a non-common, non-CLOSED license in a
6141 4284 recipe. Packages exist, such as the linux-firmware package, with many
6142 .. note:: 4285 licenses that are not in any way common. Also, new licenses are added
6143 4286 occasionally to avoid introducing a lot of common license files,
6144 You must include 4287 which are only applicable to a specific package.
6145 conf/machine/include/soc-family.inc 4288 ``NO_GENERIC_LICENSE`` is used to allow copying a license that does
6146 for this variable to appear in 4289 not exist in common licenses.
6147 MACHINEOVERRIDES 4290
6148 . 4291 The following example shows how to add ``NO_GENERIC_LICENSE`` to a
6149 4292 recipe: NO_GENERIC_LICENSE[license_name] =
6150SOLIBS 4293 "license_file_in_fetched_source" The following is an example that
6151 Defines the suffix for shared libraries used on the target platform. 4294 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
6152 By default, this suffix is ".so.*" for all Linux-based systems and is 4295 source: NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
6153 defined in the ``meta/conf/bitbake.conf`` configuration file. 4296
6154 4297 NO_RECOMMENDATIONS
6155 You will see this variable referenced in the default values of 4298 Prevents installation of all "recommended-only" packages.
6156 ``FILES_${PN}``. 4299 Recommended-only packages are packages installed only through the
6157 4300 :term:`RRECOMMENDS` variable). Setting the
6158SOLIBSDEV 4301 ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on:
6159 Defines the suffix for the development symbolic link (symlink) for 4302 NO_RECOMMENDATIONS = "1"
6160 shared libraries on the target platform. By default, this suffix is 4303
6161 ".so" for Linux-based systems and is defined in the 4304 You can set this variable globally in your ``local.conf`` file or you
6162 ``meta/conf/bitbake.conf`` configuration file. 4305 can attach it to a specific image recipe by using the recipe name
6163 4306 override: NO_RECOMMENDATIONS_pn-target_image = "1"
6164 You will see this variable referenced in the default values of 4307
6165 ``FILES_${PN}-dev``. 4308 It is important to realize that if you choose to not install packages
6166 4309 using this variable and some other packages are dependent on them
6167SOURCE_MIRROR_FETCH 4310 (i.e. listed in a recipe's :term:`RDEPENDS`
6168 When you are fetching files to create a mirror of sources (i.e. 4311 variable), the OpenEmbedded build system ignores your request and
6169 creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in 4312 will install the packages to avoid dependency errors.
6170 your ``local.conf`` configuration file ensures the source for all 4313
6171 recipes are fetched regardless of whether or not a recipe is
6172 compatible with the configuration. A recipe is considered
6173 incompatible with the currently configured machine when either or
6174 both the ```COMPATIBLE_MACHINE`` <#var-COMPATIBLE_MACHINE>`__
6175 variable and ```COMPATIBLE_HOST`` <#var-COMPATIBLE_HOST>`__ variables
6176 specify compatibility with a machine other than that of the current
6177 machine or host.
6178
6179 .. note::
6180
6181 Do not set the
6182 SOURCE_MIRROR_FETCH
6183 variable unless you are creating a source mirror. In other words,
6184 do not set the variable during a normal build.
6185
6186SOURCE_MIRROR_URL
6187 Defines your own ```PREMIRRORS`` <#var-PREMIRRORS>`__ from which to
6188 first fetch source before attempting to fetch from the upstream
6189 specified in ```SRC_URI`` <#var-SRC_URI>`__.
6190
6191 To use this variable, you must globally inherit the
6192 ```own-mirrors`` <#ref-classes-own-mirrors>`__ class and then provide
6193 the URL to your mirrors. Here is the general syntax: INHERIT +=
6194 "own-mirrors" SOURCE_MIRROR_URL =
6195 "http://example.com/my_source_mirror"
6196
6197 .. note::
6198
6199 You can specify only a single URL in
6200 SOURCE_MIRROR_URL
6201 .
6202
6203SPDXLICENSEMAP
6204 Maps commonly used license names to their SPDX counterparts found in
6205 ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP``
6206 mappings, see the ``meta/conf/licenses.conf`` file.
6207
6208 For additional information, see the ```LICENSE`` <#var-LICENSE>`__
6209 variable.
6210
6211SPECIAL_PKGSUFFIX
6212 A list of prefixes for ```PN`` <#var-PN>`__ used by the OpenEmbedded
6213 build system to create variants of recipes or packages. The list
6214 specifies the prefixes to strip off during certain circumstances such
6215 as the generation of the ```BPN`` <#var-BPN>`__ variable.
6216
6217SPL_BINARY
6218 The file type for the Secondary Program Loader (SPL). Some devices
6219 use an SPL from which to boot (e.g. the BeagleBone development
6220 board). For such cases, you can declare the file type of the SPL
6221 binary in the ``u-boot.inc`` include file, which is used in the
6222 U-Boot recipe.
6223
6224 The SPL file type is set to "null" by default in the ``u-boot.inc``
6225 file as follows: # Some versions of u-boot build an SPL (Second
6226 Program Loader) image that # should be packaged along with the u-boot
6227 binary as well as placed in the # deploy directory. For those
6228 versions they can set the following variables # to allow packaging
6229 the SPL. SPL_BINARY ?= "" SPL_BINARYNAME ?=
6230 "${@os.path.basename(d.getVar("SPL_BINARY"))}" SPL_IMAGE ?=
6231 "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" SPL_SYMLINK ?=
6232 "${SPL_BINARYNAME}-${MACHINE}" The ``SPL_BINARY`` variable helps form
6233 various ``SPL_*`` variables used by the OpenEmbedded build system.
6234
6235 See the BeagleBone machine configuration example in the "`Creating a
6236 new BSP Layer Using the ``bitbake-layers``
6237 Script <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__"
6238 section in the Yocto Project Board Support Package Developer's Guide
6239 for additional information.
6240
6241SRC_URI
6242 The list of source files - local or remote. This variable tells the
6243 OpenEmbedded build system which bits to pull in for the build and how
6244 to pull them in. For example, if the recipe or append file only needs
6245 to fetch a tarball from the Internet, the recipe or append file uses
6246 a single ``SRC_URI`` entry. On the other hand, if the recipe or
6247 append file needs to fetch a tarball, apply two patches, and include
6248 a custom file, the recipe or append file would include four instances
6249 of the variable.
6250
6251 The following list explains the available URI protocols. URI
6252 protocols are highly dependent on particular BitBake Fetcher
6253 submodules. Depending on the fetcher BitBake uses, various URL
6254 parameters are employed. For specifics on the supported Fetchers, see
6255 the "`Fetchers <&YOCTO_DOCS_BB_URL;#bb-fetchers>`__" section in the
6256 BitBake User Manual.
6257
6258 - *``file://`` -* Fetches files, which are usually files shipped
6259 with the `Metadata <#metadata>`__, from the local machine (e.g.
6260 `patch <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__ files).
6261 The path is relative to the ```FILESPATH`` <#var-FILESPATH>`__
6262 variable. Thus, the build system searches, in order, from the
6263 following directories, which are assumed to be a subdirectories of
6264 the directory in which the recipe file (``.bb``) or append file
6265 (``.bbappend``) resides:
6266
6267 - *``${BPN}`` -* The base recipe name without any special suffix
6268 or version numbers.
6269
6270 - *``${BP}`` -* ``${BPN}-${PV}``. The base recipe name and
6271 version but without any special package name suffix.
6272
6273 - *files -* Files within a directory, which is named ``files``
6274 and is also alongside the recipe or append file.
6275
6276 .. note:: 4314 .. note::
6277 4315
6278 If you want the build system to pick up files specified through 4316 Some recommended packages might be required for certain system
6279 a 4317 functionality, such as kernel modules. It is up to you to add
6280 SRC_URI 4318 packages with the
6281 statement from your append file, you need to be sure to extend 4319 IMAGE_INSTALL
4320 variable.
4321
4322 Support for this variable exists only when using the IPK and RPM
4323 packaging backend. Support does not exist for DEB.
4324
4325 See the :term:`BAD_RECOMMENDATIONS` and
4326 the :term:`PACKAGE_EXCLUDE` variables for
4327 related information.
4328
4329 NOAUTOPACKAGEDEBUG
4330 Disables auto package from splitting ``.debug`` files. If a recipe
4331 requires ``FILES_${PN}-dbg`` to be set manually, the
4332 ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the
4333 content of the debug package. For example: NOAUTOPACKAGEDEBUG = "1"
4334 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" FILES_${PN}-dbg
4335 = "/usr/src/debug/" FILES_${QT_BASE_NAME}-demos-doc =
4336 "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
4337
4338 OBJCOPY
4339 The minimal command and arguments to run ``objcopy``.
4340
4341 OBJDUMP
4342 The minimal command and arguments to run ``objdump``.
4343
4344 OE_BINCONFIG_EXTRA_MANGLE
4345 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
4346 this variable specifies additional arguments passed to the "sed"
4347 command. The sed command alters any paths in configuration scripts
4348 that have been set up during compilation. Inheriting this class
4349 results in all paths in these scripts being changed to point into the
4350 ``sysroots/`` directory so that all builds that use the script will
4351 use the correct directories for the cross compiling layout.
4352
4353 See the ``meta/classes/binconfig.bbclass`` in the
4354 :term:`Source Directory` for details on how this class
4355 applies these additional sed command arguments. For general
4356 information on the ``binconfig`` class, see the
4357 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
4358
4359 OE_IMPORTS
4360 An internal variable used to tell the OpenEmbedded build system what
4361 Python modules to import for every Python function run by the system.
4362
4363 .. note::
4364
4365 Do not set this variable. It is for internal use only.
4366
4367 OE_INIT_ENV_SCRIPT
4368 The name of the build environment setup script for the purposes of
4369 setting up the environment within the extensible SDK. The default
4370 value is "oe-init-build-env".
4371
4372 If you use a custom script to set up your build environment, set the
4373 ``OE_INIT_ENV_SCRIPT`` variable to its name.
4374
4375 OE_TERMINAL
4376 Controls how the OpenEmbedded build system spawns interactive
4377 terminals on the host development system (e.g. using the BitBake
4378 command with the ``-c devshell`` command-line option). For more
4379 information, see the "`Using a Development
4380 Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" section in
4381 the Yocto Project Development Tasks Manual.
4382
4383 You can use the following values for the ``OE_TERMINAL`` variable:
4384 auto gnome xfce rxvt screen konsole none
4385
4386 OEROOT
4387 The directory from which the top-level build environment setup script
4388 is sourced. The Yocto Project provides a top-level build environment
4389 setup script: ````` <#structure-core-script>`__. When you run this
4390 script, the ``OEROOT`` variable resolves to the directory that
4391 contains the script.
4392
4393 For additional information on how this variable is used, see the
4394 initialization script.
4395
4396 OLDEST_KERNEL
4397 Declares the oldest version of the Linux kernel that the produced
4398 binaries must support. This variable is passed into the build of the
4399 Embedded GNU C Library (``glibc``).
4400
4401 The default for this variable comes from the
4402 ``meta/conf/bitbake.conf`` configuration file. You can override this
4403 default by setting the variable in a custom distribution
4404 configuration file.
4405
4406 OVERRIDES
4407 A colon-separated list of overrides that currently apply. Overrides
4408 are a BitBake mechanism that allows variables to be selectively
4409 overridden at the end of parsing. The set of overrides in
4410 ``OVERRIDES`` represents the "state" during building, which includes
4411 the current recipe being built, the machine for which it is being
4412 built, and so forth.
4413
4414 As an example, if the string "an-override" appears as an element in
4415 the colon-separated list in ``OVERRIDES``, then the following
4416 assignment will override ``FOO`` with the value "overridden" at the
4417 end of parsing: FOO_an-override = "overridden" See the
4418 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
4419 section in the BitBake User Manual for more information on the
4420 overrides mechanism.
4421
4422 The default value of ``OVERRIDES`` includes the values of the
4423 :term:`CLASSOVERRIDE`,
4424 :term:`MACHINEOVERRIDES`, and
4425 :term:`DISTROOVERRIDES` variables. Another
4426 important override included by default is ``pn-${PN}``. This override
4427 allows variables to be set for a single recipe within configuration
4428 (``.conf``) files. Here is an example: FOO_pn-myrecipe =
4429 "myrecipe-specific value"
4430
4431 .. note::
4432
4433 An easy way to see what overrides apply is to search for
4434 OVERRIDES
4435 in the output of the
4436 bitbake -e
4437 command. See the "
4438 Viewing Variable Values
4439 " section in the Yocto Project Development Tasks Manual for more
4440 information.
4441
4442 P
4443 The recipe name and version. ``P`` is comprised of the following:
4444 ${PN}-${PV}
4445
4446 PACKAGE_ADD_METADATA
4447 This variable defines additional metdata to add to packages.
4448
4449 You may find you need to inject additional metadata into packages.
4450 This variable allows you to do that by setting the injected data as
4451 the value. Multiple fields can be added by splitting the content with
4452 the literal separator "\n".
4453
4454 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
4455 to do package type specific settings. It can also be made package
4456 specific by using the package name as a suffix.
4457
4458 You can find out more about applying this variable in the "`Adding
4459 custom metadata to
4460 packages <&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages>`__"
4461 section in the Yocto Project Development Tasks Manual.
4462
4463 PACKAGE_ARCH
4464 The architecture of the resulting package or packages.
4465
4466 By default, the value of this variable is set to
4467 :term:`TUNE_PKGARCH` when building for the
4468 target, :term:`BUILD_ARCH` when building for the
4469 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
4470 SDK.
4471
4472 .. note::
4473
4474 See
4475 SDK_ARCH
4476 for more information.
4477
4478 However, if your recipe's output packages are built specific to the
4479 target machine rather than generally for the architecture of the
4480 machine, you should set ``PACKAGE_ARCH`` to the value of
4481 :term:`MACHINE_ARCH` in the recipe as follows:
4482 PACKAGE_ARCH = "${MACHINE_ARCH}"
4483
4484 PACKAGE_ARCHS
4485 Specifies a list of architectures compatible with the target machine.
4486 This variable is set automatically and should not normally be
4487 hand-edited. Entries are separated using spaces and listed in order
4488 of priority. The default value for ``PACKAGE_ARCHS`` is "all any
4489 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
4490
4491 PACKAGE_BEFORE_PN
4492 Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so
4493 that those added packages can pick up files that would normally be
4494 included in the default package.
4495
4496 PACKAGE_CLASSES
4497 This variable, which is set in the ``local.conf`` configuration file
4498 found in the ``conf`` folder of the
4499 :term:`Build Directory`, specifies the package manager the
4500 OpenEmbedded build system uses when packaging data.
4501
4502 You can provide one or more of the following arguments for the
4503 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk
4504 package_tar"
4505
4506 .. note::
4507
4508 While it is a legal option, the
4509 package_tar
4510 class has limited functionality due to no support for package
4511 dependencies by that backend. Therefore, it is recommended that
4512 you do not use it.
4513
4514 The build system uses only the first argument in the list as the
4515 package manager when creating your image or SDK. However, packages
4516 will be created using any additional packaging classes you specify.
4517 For example, if you use the following in your ``local.conf`` file:
4518 PACKAGE_CLASSES ?= "package_ipk" The OpenEmbedded build system uses
4519 the IPK package manager to create your image or SDK.
4520
4521 For information on packaging and build performance effects as a
4522 result of the package manager in use, see the
4523 ":ref:`package.bbclass <ref-classes-package>`" section.
4524
4525 PACKAGE_DEBUG_SPLIT_STYLE
4526 Determines how to split up the binary and debug information when
4527 creating ``*-dbg`` packages to be used with the GNU Project Debugger
4528 (GDB).
4529
4530 With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control
4531 where debug information, which can include or exclude source files,
4532 is stored:
4533
4534 - ".debug": Debug symbol files are placed next to the binary in a
4535 ``.debug`` directory on the target. For example, if a binary is
4536 installed into ``/bin``, the corresponding debug symbol files are
4537 installed in ``/bin/.debug``. Source files are placed in
4538 ``/usr/src/debug``.
4539
4540 - "debug-file-directory": Debug symbol files are placed under
4541 ``/usr/lib/debug`` on the target, and separated by the path from
4542 where the binary is installed. For example, if a binary is
4543 installed in ``/bin``, the corresponding debug symbols are
4544 installed in ``/usr/lib/debug/bin``. Source files are placed in
4545 ``/usr/src/debug``.
4546
4547 - "debug-without-src": The same behavior as ".debug" previously
4548 described with the exception that no source files are installed.
4549
4550 - "debug-with-srcpkg": The same behavior as ".debug" previously
4551 described with the exception that all source files are placed in a
4552 separate ``*-src`` pkg. This is the default behavior.
4553
4554 You can find out more about debugging using GDB by reading the
4555 "`Debugging With the GNU Project Debugger (GDB)
4556 Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section
4557 in the Yocto Project Development Tasks Manual.
4558
4559 PACKAGE_EXCLUDE_COMPLEMENTARY
4560 Prevents specific packages from being installed when you are
4561 installing complementary packages.
4562
4563 You might find that you want to prevent installing certain packages
4564 when you are installing complementary packages. For example, if you
4565 are using :term:`IMAGE_FEATURES` to install
4566 ``dev-pkgs``, you might not want to install all packages from a
4567 particular multilib. If you find yourself in this situation, you can
4568 use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular
4569 expressions to match the packages you want to exclude.
4570
4571 PACKAGE_EXCLUDE
4572 Lists packages that should not be installed into an image. For
4573 example: PACKAGE_EXCLUDE = "package_name package_name package_name
4574 ..."
4575
4576 You can set this variable globally in your ``local.conf`` file or you
4577 can attach it to a specific image recipe by using the recipe name
4578 override: PACKAGE_EXCLUDE_pn-target_image = "package_name"
4579
4580 If you choose to not install a package using this variable and some
4581 other package is dependent on it (i.e. listed in a recipe's
4582 :term:`RDEPENDS` variable), the OpenEmbedded build
4583 system generates a fatal installation error. Because the build system
4584 halts the process with a fatal error, you can use the variable with
4585 an iterative development process to remove specific components from a
4586 system.
4587
4588 Support for this variable exists only when using the IPK and RPM
4589 packaging backend. Support does not exist for DEB.
4590
4591 See the :term:`NO_RECOMMENDATIONS` and the
4592 :term:`BAD_RECOMMENDATIONS` variables for
4593 related information.
4594
4595 PACKAGE_EXTRA_ARCHS
4596 Specifies the list of architectures compatible with the device CPU.
4597 This variable is useful when you build for several different devices
4598 that use miscellaneous processors such as XScale and ARM926-EJS.
4599
4600 PACKAGE_FEED_ARCHS
4601 Optionally specifies the package architectures used as part of the
4602 package feed URIs during the build. When used, the
4603 ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed
4604 URI, which is constructed using the
4605 :term:`PACKAGE_FEED_URIS` and
4606 :term:`PACKAGE_FEED_BASE_PATHS`
4607 variables.
4608
4609 .. note::
4610
4611 You can use the
4612 PACKAGE_FEEDS_ARCHS
4613 variable to whitelist specific package architectures. If you do
4614 not need to whitelist specific architectures, which is a common
4615 case, you can omit this variable. Omitting the variable results in
4616 all available architectures for the current machine being included
4617 into remote package feeds.
4618
4619 Consider the following example where the ``PACKAGE_FEED_URIS``,
4620 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4621 defined in your ``local.conf`` file: PACKAGE_FEED_URIS =
4622 "https://example.com/packagerepos/release \\
4623 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS =
4624 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these
4625 settings, the resulting package feeds are as follows:
4626 https://example.com/packagerepos/release/rpm/all
4627 https://example.com/packagerepos/release/rpm/core2-64
4628 https://example.com/packagerepos/release/rpm-dev/all
4629 https://example.com/packagerepos/release/rpm-dev/core2-64
4630 https://example.com/packagerepos/updates/rpm/all
4631 https://example.com/packagerepos/updates/rpm/core2-64
4632 https://example.com/packagerepos/updates/rpm-dev/all
4633 https://example.com/packagerepos/updates/rpm-dev/core2-64
4634
4635 PACKAGE_FEED_BASE_PATHS
4636 Specifies the base path used when constructing package feed URIs. The
4637 ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a
4638 package feed URI used by the OpenEmbedded build system. The base path
4639 lies between the :term:`PACKAGE_FEED_URIS`
4640 and :term:`PACKAGE_FEED_ARCHS` variables.
4641
4642 Consider the following example where the ``PACKAGE_FEED_URIS``,
4643 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4644 defined in your ``local.conf`` file: PACKAGE_FEED_URIS =
4645 "https://example.com/packagerepos/release \\
4646 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS =
4647 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these
4648 settings, the resulting package feeds are as follows:
4649 https://example.com/packagerepos/release/rpm/all
4650 https://example.com/packagerepos/release/rpm/core2-64
4651 https://example.com/packagerepos/release/rpm-dev/all
4652 https://example.com/packagerepos/release/rpm-dev/core2-64
4653 https://example.com/packagerepos/updates/rpm/all
4654 https://example.com/packagerepos/updates/rpm/core2-64
4655 https://example.com/packagerepos/updates/rpm-dev/all
4656 https://example.com/packagerepos/updates/rpm-dev/core2-64
4657
4658 PACKAGE_FEED_URIS
4659 Specifies the front portion of the package feed URI used by the
4660 OpenEmbedded build system. Each final package feed URI is comprised
4661 of ``PACKAGE_FEED_URIS``,
4662 :term:`PACKAGE_FEED_BASE_PATHS`, and
4663 :term:`PACKAGE_FEED_ARCHS` variables.
4664
4665 Consider the following example where the ``PACKAGE_FEED_URIS``,
4666 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4667 defined in your ``local.conf`` file: PACKAGE_FEED_URIS =
4668 "https://example.com/packagerepos/release \\
4669 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS =
4670 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these
4671 settings, the resulting package feeds are as follows:
4672 https://example.com/packagerepos/release/rpm/all
4673 https://example.com/packagerepos/release/rpm/core2-64
4674 https://example.com/packagerepos/release/rpm-dev/all
4675 https://example.com/packagerepos/release/rpm-dev/core2-64
4676 https://example.com/packagerepos/updates/rpm/all
4677 https://example.com/packagerepos/updates/rpm/core2-64
4678 https://example.com/packagerepos/updates/rpm-dev/all
4679 https://example.com/packagerepos/updates/rpm-dev/core2-64
4680
4681 PACKAGE_INSTALL
4682 The final list of packages passed to the package manager for
4683 installation into the image.
4684
4685 Because the package manager controls actual installation of all
4686 packages, the list of packages passed using ``PACKAGE_INSTALL`` is
4687 not the final list of packages that are actually installed. This
4688 variable is internal to the image construction code. Consequently, in
4689 general, you should use the
4690 :term:`IMAGE_INSTALL` variable to specify
4691 packages for installation. The exception to this is when working with
4692 the
4693 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__
4694 image. When working with an initial RAM filesystem (initramfs) image,
4695 use the ``PACKAGE_INSTALL`` variable. For information on creating an
4696 initramfs, see the "`Building an Initial RAM Filesystem (initramfs)
4697 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
4698 in the Yocto Project Development Tasks Manual.
4699
4700 PACKAGE_INSTALL_ATTEMPTONLY
4701 Specifies a list of packages the OpenEmbedded build system attempts
4702 to install when creating an image. If a listed package fails to
4703 install, the build system does not generate an error. This variable
4704 is generally not user-defined.
4705
4706 PACKAGE_PREPROCESS_FUNCS
4707 Specifies a list of functions run to pre-process the
4708 :term:`PKGD` directory prior to splitting the files out
4709 to individual packages.
4710
4711 PACKAGE_WRITE_DEPS
4712 Specifies a list of dependencies for post-installation and
4713 pre-installation scripts on native/cross tools. If your
4714 post-installation or pre-installation script can execute at rootfs
4715 creation time rather than on the target but depends on a native tool
4716 in order to execute, you need to list the tools in
4717 ``PACKAGE_WRITE_DEPS``.
4718
4719 For information on running post-installation scripts, see the
4720 "`Post-Installation
4721 Scripts <&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts>`__"
4722 section in the Yocto Project Development Tasks Manual.
4723
4724 PACKAGECONFIG
4725 This variable provides a means of enabling or disabling features of a
4726 recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in
4727 recipes when you specify features and then arguments that define
4728 feature behaviors. Here is the basic block structure (broken over
4729 multiple lines for readability): PACKAGECONFIG ??= "f1 f2 f3 ..."
4730 PACKAGECONFIG[f1] = "\\ --with-f1, \\ --without-f1, \\
4731 build-deps-for-f1, \\ runtime-deps-for-f1, \\
4732 runtime-recommends-for-f1, \\ packageconfig-conflicts-for-f1 \\ "
4733 PACKAGECONFIG[f2] = "\\ ... and so on and so on ...
4734
4735 The ``PACKAGECONFIG`` variable itself specifies a space-separated
4736 list of the features to enable. Following the features, you can
4737 determine the behavior of each feature by providing up to six
4738 order-dependent arguments, which are separated by commas. You can
4739 omit any argument you like but must retain the separating commas. The
4740 order is important and specifies the following:
4741
4742 1. Extra arguments that should be added to the configure script
4743 argument list (:term:`EXTRA_OECONF` or
4744 :term:`PACKAGECONFIG_CONFARGS`) if
4745 the feature is enabled.
4746
4747 2. Extra arguments that should be added to ``EXTRA_OECONF`` or
4748 ``PACKAGECONFIG_CONFARGS`` if the feature is disabled.
4749
4750 3. Additional build dependencies (:term:`DEPENDS`)
4751 that should be added if the feature is enabled.
4752
4753 4. Additional runtime dependencies (:term:`RDEPENDS`)
4754 that should be added if the feature is enabled.
4755
4756 5. Additional runtime recommendations
4757 (:term:`RRECOMMENDS`) that should be added if
4758 the feature is enabled.
4759
4760 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG``
4761 settings for this feature.
4762
4763 Consider the following ``PACKAGECONFIG`` block taken from the
4764 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
4765 three arguments that determine the feature's behavior.
4766 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" The
4767 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
4768 enabled. In this case, ``--with-gtk3`` is added to the configure
4769 script argument list and ``gtk+3`` is added to ``DEPENDS``. On the
4770 other hand, if the feature is disabled say through a ``.bbappend``
4771 file in another layer, then the second argument ``--without-gtk3`` is
4772 added to the configure script instead.
4773
4774 The basic ``PACKAGECONFIG`` structure previously described holds true
4775 regardless of whether you are creating a block or changing a block.
4776 When creating a block, use the structure inside your recipe.
4777
4778 If you want to change an existing ``PACKAGECONFIG`` block, you can do
4779 so one of two ways:
4780
4781 - *Append file:* Create an append file named
4782 recipename\ ``.bbappend`` in your layer and override the value of
4783 ``PACKAGECONFIG``. You can either completely override the
4784 variable: PACKAGECONFIG = "f4 f5" Or, you can just append the
4785 variable: PACKAGECONFIG_append = " f4"
4786
4787 - *Configuration file:* This method is identical to changing the
4788 block through an append file except you edit your ``local.conf``
4789 or ``mydistro.conf`` file. As with append files previously
4790 described, you can either completely override the variable:
4791 PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the
4792 variable: PACKAGECONFIG_append_pn-recipename = " f4"
4793
4794 PACKAGECONFIG_CONFARGS
4795 A space-separated list of configuration options generated from the
4796 :term:`PACKAGECONFIG` setting.
4797
4798 Classes such as :ref:`autotools <ref-classes-autotools>` and
4799 :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to
4800 pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``,
4801 respectively. If you are using ``PACKAGECONFIG`` but not a class that
4802 handles the ``do_configure`` task, then you need to use
4803 ``PACKAGECONFIG_CONFARGS`` appropriately.
4804
4805 PACKAGEGROUP_DISABLE_COMPLEMENTARY
4806 For recipes inheriting the
4807 :ref:`packagegroup <ref-classes-packagegroup>` class, setting
4808 ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the
4809 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
4810 should not be automatically created by the ``packagegroup`` recipe,
4811 which is the default behavior.
4812
4813 PACKAGES
4814 The list of packages the recipe creates. The default value is the
4815 following: ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale
4816 ${PACKAGE_BEFORE_PN} ${PN}
4817
4818 During packaging, the :ref:`ref-tasks-package` task
4819 goes through ``PACKAGES`` and uses the :term:`FILES`
4820 variable corresponding to each package to assign files to the
4821 package. If a file matches the ``FILES`` variable for more than one
4822 package in ``PACKAGES``, it will be assigned to the earliest
4823 (leftmost) package.
4824
4825 Packages in the variable's list that are empty (i.e. where none of
4826 the patterns in ``FILES_``\ pkg match any files installed by the
4827 :ref:`ref-tasks-install` task) are not generated,
4828 unless generation is forced through the
4829 :term:`ALLOW_EMPTY` variable.
4830
4831 PACKAGES_DYNAMIC
4832 A promise that your recipe satisfies runtime dependencies for
4833 optional modules that are found in other recipes.
4834 ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it
4835 only states that they should be satisfied. For example, if a hard,
4836 runtime dependency (:term:`RDEPENDS`) of another
4837 package is satisfied at build time through the ``PACKAGES_DYNAMIC``
4838 variable, but a package with the module name is never actually
4839 produced, then the other package will be broken. Thus, if you attempt
4840 to include that package in an image, you will get a dependency
4841 failure from the packaging system during the
4842 :ref:`ref-tasks-rootfs` task.
4843
4844 Typically, if there is a chance that such a situation can occur and
4845 the package that is not created is valid without the dependency being
4846 satisfied, then you should use :term:`RRECOMMENDS`
4847 (a soft runtime dependency) instead of ``RDEPENDS``.
4848
4849 For an example of how to use the ``PACKAGES_DYNAMIC`` variable when
4850 you are splitting packages, see the "`Handling Optional Module
4851 Packaging <&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging>`__"
4852 section in the Yocto Project Development Tasks Manual.
4853
4854 PACKAGESPLITFUNCS
4855 Specifies a list of functions run to perform additional splitting of
4856 files into individual packages. Recipes can either prepend to this
4857 variable or prepend to the ``populate_packages`` function in order to
4858 perform additional package splitting. In either case, the function
4859 should set :term:`PACKAGES`,
4860 :term:`FILES`, :term:`RDEPENDS` and
4861 other packaging variables appropriately in order to perform the
4862 desired splitting.
4863
4864 PARALLEL_MAKE
4865 Extra options passed to the ``make`` command during the
4866 :ref:`ref-tasks-compile` task in order to specify
4867 parallel compilation on the local build host. This variable is
4868 usually in the form "-j x", where x represents the maximum number of
4869 parallel threads ``make`` can run.
4870
4871 .. note::
4872
4873 In order for
4874 PARALLEL_MAKE
4875 to be effective,
4876 make
4877 must be called with
4878 ${
4879 EXTRA_OEMAKE
4880 }
4881 . An easy way to ensure this is to use the
4882 oe_runmake
4883 function.
4884
4885 By default, the OpenEmbedded build system automatically sets this
4886 variable to be equal to the number of cores the build system uses.
4887
4888 .. note::
4889
4890 If the software being built experiences dependency issues during
6282 the 4891 the
6283 FILESPATH 4892 do_compile
6284 variable by also using the 4893 task that result in race conditions, you can clear the
6285 FILESEXTRAPATHS 4894 PARALLEL_MAKE
6286 variable from within your append file. 4895 variable within the recipe as a workaround. For information on
6287 4896 addressing race conditions, see the "
6288 - *``bzr://`` -* Fetches files from a Bazaar revision control 4897 Debugging Parallel Make Races
6289 repository. 4898 " section in the Yocto Project Development Tasks Manual.
6290 4899
6291 - *``git://`` -* Fetches files from a Git revision control 4900 For single socket systems (i.e. one CPU), you should not have to
6292 repository. 4901 override this variable to gain optimal parallelism during builds.
6293 4902 However, if you have very large systems that employ multiple physical
6294 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service) 4903 CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is
6295 revision control repository. 4904 not set higher than "-j 20".
6296 4905
6297 - *``repo://`` -* Fetches files from a repo (Git) repository. 4906 For more information on speeding up builds, see the "`Speeding Up a
6298 4907 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the
6299 - *``ccrc://`` -* Fetches files from a ClearCase repository. 4908 Yocto Project Development Tasks Manual.
6300 4909
6301 - *``http://`` -* Fetches files from the Internet using ``http``. 4910 PARALLEL_MAKEINST
6302 4911 Extra options passed to the ``make install`` command during the
6303 - *``https://`` -* Fetches files from the Internet using ``https``. 4912 :ref:`ref-tasks-install` task in order to specify
6304 4913 parallel installation. This variable defaults to the value of
6305 - *``ftp://`` -* Fetches files from the Internet using ``ftp``. 4914 :term:`PARALLEL_MAKE`.
6306 4915
6307 - *``cvs://`` -* Fetches files from a CVS revision control
6308 repository.
6309
6310 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision
6311 control repository.
6312
6313 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision
6314 control repository.
6315
6316 - *``ssh://`` -* Fetches files from a secure shell.
6317
6318 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision
6319 control repository.
6320
6321 - *``npm://`` -* Fetches JavaScript modules from a registry.
6322
6323 Standard and recipe-specific options for ``SRC_URI`` exist. Here are
6324 standard options:
6325
6326 - *``apply`` -* Whether to apply the patch or not. The default
6327 action is to apply the patch.
6328
6329 - *``striplevel`` -* Which striplevel to use when applying the
6330 patch. The default level is 1.
6331
6332 - *``patchdir`` -* Specifies the directory in which the patch should
6333 be applied. The default is ``${``\ ```S`` <#var-S>`__\ ``}``.
6334
6335 Here are options specific to recipes building code from a revision
6336 control system:
6337
6338 - *``mindate`` -* Apply the patch only if
6339 ```SRCDATE`` <#var-SRCDATE>`__ is equal to or greater than
6340 ``mindate``.
6341
6342 - *``maxdate`` -* Apply the patch only if ``SRCDATE`` is not later
6343 than ``maxdate``.
6344
6345 - *``minrev`` -* Apply the patch only if ``SRCREV`` is equal to or
6346 greater than ``minrev``.
6347
6348 - *``maxrev`` -* Apply the patch only if ``SRCREV`` is not later
6349 than ``maxrev``.
6350
6351 - *``rev`` -* Apply the patch only if ``SRCREV`` is equal to
6352 ``rev``.
6353
6354 - *``notrev`` -* Apply the patch only if ``SRCREV`` is not equal to
6355 ``rev``.
6356
6357 Here are some additional options worth mentioning:
6358
6359 - *``unpack`` -* Controls whether or not to unpack the file if it is
6360 an archive. The default action is to unpack the file.
6361
6362 - *``destsuffix`` -* Places the file (or extracts its contents) into
6363 the specified subdirectory of ```WORKDIR`` <#var-WORKDIR>`__ when
6364 the Git fetcher is used.
6365
6366 - *``subdir`` -* Places the file (or extracts its contents) into the
6367 specified subdirectory of ``WORKDIR`` when the local (``file://``)
6368 fetcher is used.
6369
6370 - *``localdir`` -* Places the file (or extracts its contents) into
6371 the specified subdirectory of ``WORKDIR`` when the CVS fetcher is
6372 used.
6373
6374 - *``subpath`` -* Limits the checkout to a specific subpath of the
6375 tree when using the Git fetcher is used.
6376
6377 - *``name`` -* Specifies a name to be used for association with
6378 ``SRC_URI`` checksums when you have more than one file specified
6379 in ``SRC_URI``.
6380
6381 - *``downloadfilename`` -* Specifies the filename used when storing
6382 the downloaded file.
6383
6384SRC_URI_OVERRIDES_PACKAGE_ARCH
6385 By default, the OpenEmbedded build system automatically detects
6386 whether ``SRC_URI`` contains files that are machine-specific. If so,
6387 the build system automatically changes ``PACKAGE_ARCH``. Setting this
6388 variable to "0" disables this behavior.
6389
6390SRCDATE
6391 The date of the source code used to build the package. This variable
6392 applies only if the source was fetched from a Source Code Manager
6393 (SCM).
6394
6395SRCPV
6396 Returns the version string of the current package. This string is
6397 used to help define the value of ```PV`` <#var-PV>`__.
6398
6399 The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf``
6400 configuration file in the `Source Directory <#source-directory>`__ as
6401 follows: SRCPV = "${@bb.fetch2.get_srcrev(d)}"
6402
6403 Recipes that need to define ``PV`` do so with the help of the
6404 ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``)
6405 located in ``meta/recipes-connectivity`` in the Source Directory
6406 defines ``PV`` as follows: PV = "0.12-git${SRCPV}"
6407
6408SRCREV
6409 The revision of the source code used to build the package. This
6410 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
6411 that if you want to build a fixed revision and you want to avoid
6412 performing a query on the remote repository every time BitBake parses
6413 your recipe, you should specify a ``SRCREV`` that is a full revision
6414 identifier and not just a tag.
6415
6416 .. note::
6417
6418 For information on limitations when inheriting the latest revision
6419 of software using
6420 SRCREV
6421 , see the
6422 AUTOREV
6423 variable description and the "
6424 Automatically Incrementing a Binary Package Revision Number
6425 " section, which is in the Yocto Project Development Tasks Manual.
6426
6427SSTATE_DIR
6428 The directory for the shared state cache.
6429
6430SSTATE_MIRROR_ALLOW_NETWORK
6431 If set to "1", allows fetches from mirrors that are specified in
6432 ```SSTATE_MIRRORS`` <#var-SSTATE_MIRRORS>`__ to work even when
6433 fetching from the network is disabled by setting ``BB_NO_NETWORK`` to
6434 "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if
6435 you have set ``SSTATE_MIRRORS`` to point to an internal server for
6436 your shared state cache, but you want to disable any other fetching
6437 from the network.
6438
6439SSTATE_MIRRORS
6440 Configures the OpenEmbedded build system to search other mirror
6441 locations for prebuilt cache data objects before building out the
6442 data. This variable works like fetcher ```MIRRORS`` <#var-MIRRORS>`__
6443 and ```PREMIRRORS`` <#var-PREMIRRORS>`__ and points to the cache
6444 locations to check for the shared state (sstate) objects.
6445
6446 You can specify a filesystem directory or a remote URL such as HTTP
6447 or FTP. The locations you specify need to contain the shared state
6448 cache (sstate-cache) results from previous builds. The sstate-cache
6449 you point to can also be from builds on other machines.
6450
6451 When pointing to sstate build artifacts on another machine that uses
6452 a different GCC version for native builds, you must configure
6453 ``SSTATE_MIRRORS`` with a regular expression that maps local search
6454 paths to server paths. The paths need to take into account
6455 ```NATIVELSBSTRING`` <#var-NATIVELSBSTRING>`__ set by the
6456 ```uninative`` <#ref-classes-uninative>`__ class. For example, the
6457 following maps the local search path ``universal-4.9`` to the
6458 server-provided path server_url_sstate_path: SSTATE_MIRRORS ?=
6459 file://universal-4.9/(.*)
6460 http://server_url_sstate_path/universal-4.8/\1 \\n
6461
6462 If a mirror uses the same structure as
6463 ```SSTATE_DIR`` <#var-SSTATE_DIR>`__, you need to add "PATH" at the
6464 end as shown in the examples below. The build system substitutes the
6465 correct path within the directory structure. SSTATE_MIRRORS ?= "\\
6466 file://.\*
6467 http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\
6468 file://.\* file:///some-local-dir/sstate/PATH"
6469
6470SSTATE_SCAN_FILES
6471 Controls the list of files the OpenEmbedded build system scans for
6472 hardcoded installation paths. The variable uses a space-separated
6473 list of filenames (not paths) with standard wildcard characters
6474 allowed.
6475
6476 During a build, the OpenEmbedded build system creates a shared state
6477 (sstate) object during the first stage of preparing the sysroots.
6478 That object is scanned for hardcoded paths for original installation
6479 locations. The list of files that are scanned for paths is controlled
6480 by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files
6481 they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather
6482 than the variable being comprehensively set. The
6483 ```sstate`` <#ref-classes-sstate>`__ class specifies the default list
6484 of files.
6485
6486 For details on the process, see the
6487 ```staging`` <#ref-classes-staging>`__ class.
6488
6489STAGING_BASE_LIBDIR_NATIVE
6490 Specifies the path to the ``/lib`` subdirectory of the sysroot
6491 directory for the build host.
6492
6493STAGING_BASELIBDIR
6494 Specifies the path to the ``/lib`` subdirectory of the sysroot
6495 directory for the target for which the current recipe is being built
6496 (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__).
6497
6498STAGING_BINDIR
6499 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6500 directory for the target for which the current recipe is being built
6501 (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__).
6502
6503STAGING_BINDIR_CROSS
6504 Specifies the path to the directory containing binary configuration
6505 scripts. These scripts provide configuration information for other
6506 software that wants to make use of libraries or include files
6507 provided by the software associated with the script.
6508
6509 .. note::
6510
6511 This style of build configuration has been largely replaced by
6512 pkg-config
6513 . Consequently, if
6514 pkg-config
6515 is supported by the library to which you are linking, it is
6516 recommended you use
6517 pkg-config
6518 instead of a provided configuration script.
6519
6520STAGING_BINDIR_NATIVE
6521 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6522 directory for the build host.
6523
6524STAGING_DATADIR
6525 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6526 directory for the target for which the current recipe is being built
6527 (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__).
6528
6529STAGING_DATADIR_NATIVE
6530 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6531 directory for the build host.
6532
6533STAGING_DIR
6534 Helps construct the ``recipe-sysroots`` directory, which is used
6535 during packaging.
6536
6537 For information on how staging for recipe-specific sysroots occurs,
6538 see the ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__
6539 task, the "`Sharing Files Between
6540 Recipes <&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes>`__"
6541 section in the Yocto Project Development Tasks Manual, the
6542 "`Configuration, Compilation, and
6543 Staging <&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment>`__"
6544 section in the Yocto Project Overview and Concepts Manual, and the
6545 ```SYSROOT_DIRS`` <#var-SYSROOT_DIRS>`__ variable.
6546
6547 .. note::
6548
6549 Recipes should never write files directly under the
6550 STAGING_DIR
6551 directory because the OpenEmbedded build system manages the
6552 directory automatically. Instead, files should be installed to
6553 ${
6554 D
6555 }
6556 within your recipe's
6557 do_install
6558 task and then the OpenEmbedded build system will stage a subset of
6559 those files into the sysroot.
6560
6561STAGING_DIR_HOST
6562 Specifies the path to the sysroot directory for the system on which
6563 the component is built to run (the system that hosts the component).
6564 For most recipes, this sysroot is the one in which that recipe's
6565 ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task copies
6566 files. Exceptions include ``-native`` recipes, where the
6567 ``do_populate_sysroot`` task instead uses
6568 ```STAGING_DIR_NATIVE`` <#var-STAGING_DIR_NATIVE>`__. Depending on
6569 the type of recipe and the build target, ``STAGING_DIR_HOST`` can
6570 have the following values:
6571
6572 - For recipes building for the target machine, the value is
6573 "${`STAGING_DIR <#var-STAGING_DIR>`__}/${`MACHINE <#var-MACHINE>`__}".
6574
6575 - For native recipes building for the build host, the value is empty
6576 given the assumption that when building for the build host, the
6577 build host's own directories should be used.
6578
6579 .. note:: 4916 .. note::
6580 4917
6581 ``-native`` recipes are not installed into host paths like such 4918 In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must
6582 as ``/usr``. Rather, these recipes are installed into 4919 be called with
6583 ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, 4920 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
6584 standard build environment variables such as 4921 way to ensure this is to use the ``oe_runmake`` function.
6585 ```CPPFLAGS`` <#var-CPPFLAGS>`__ and 4922
6586 ```CFLAGS`` <#var-CFLAGS>`__ are set up so that both host paths 4923 If the software being built experiences dependency issues during
6587 and ``STAGING_DIR_NATIVE`` are searched for libraries and 4924 the ``do_install`` task that result in race conditions, you can
6588 headers using, for example, GCC's ``-isystem`` option. 4925 clear the ``PARALLEL_MAKEINST`` variable within the recipe as a
6589 4926 workaround. For information on addressing race conditions, see the
6590 Thus, the emphasis is that the ``STAGING_DIR*`` variables 4927 "`Debugging Parallel Make
6591 should be viewed as input variables by tasks such as 4928 Races <&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races>`__"
6592 ```do_configure`` <#ref-tasks-configure>`__, 4929 section in the Yocto Project Development Tasks Manual.
6593 ```do_compile`` <#ref-tasks-compile>`__, and 4930
6594 ```do_install`` <#ref-tasks-install>`__. Having the real system 4931 PATCHRESOLVE
6595 root correspond to ``STAGING_DIR_HOST`` makes conceptual sense 4932 Determines the action to take when a patch fails. You can set this
6596 for ``-native`` recipes, as they make use of host headers and 4933 variable to one of two values: "noop" and "user".
6597 libraries. 4934
6598 4935 The default value of "noop" causes the build to simply fail when the
6599STAGING_DIR_NATIVE 4936 OpenEmbedded build system cannot successfully apply a patch. Setting
6600 Specifies the path to the sysroot directory used when building 4937 the value to "user" causes the build system to launch a shell and
6601 components that run on the build host itself. 4938 places you in the right location so that you can manually resolve the
6602 4939 conflicts.
6603STAGING_DIR_TARGET 4940
6604 Specifies the path to the sysroot used for the system for which the 4941 Set this variable in your ``local.conf`` file.
6605 component generates code. For components that do not generate code, 4942
6606 which is the majority, ``STAGING_DIR_TARGET`` is set to match 4943 PATCHTOOL
6607 ```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__. 4944 Specifies the utility used to apply patches for a recipe during the
6608 4945 :ref:`ref-tasks-patch` task. You can specify one of
6609 Some recipes build binaries that can run on the target system but 4946 three utilities: "patch", "quilt", or "git". The default utility used
6610 those binaries in turn generate code for another different system 4947 is "quilt" except for the quilt-native recipe itself. Because the
6611 (e.g. cross-canadian recipes). Using terminology from GNU, the 4948 quilt tool is not available at the time quilt-native is being
6612 primary system is referred to as the "HOST" and the secondary, or 4949 patched, it uses "patch".
6613 different, system is referred to as the "TARGET". Thus, the binaries 4950
6614 run on the "HOST" system and generate binaries for the "TARGET" 4951 If you wish to use an alternative patching tool, set the variable in
6615 system. The ``STAGING_DIR_HOST`` variable points to the sysroot used 4952 the recipe using one of the following: PATCHTOOL = "patch" PATCHTOOL
6616 for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the 4953 = "quilt" PATCHTOOL = "git"
6617 sysroot used for the "TARGET" system. 4954
6618 4955 PE
6619STAGING_ETCDIR_NATIVE 4956 The epoch of the recipe. By default, this variable is unset. The
6620 Specifies the path to the ``/etc`` subdirectory of the sysroot 4957 variable is used to make upgrades possible when the versioning scheme
6621 directory for the build host. 4958 changes in some backwards incompatible way.
6622 4959
6623STAGING_EXECPREFIXDIR 4960 ``PE`` is the default value of the :term:`PKGE` variable.
6624 Specifies the path to the ``/usr`` subdirectory of the sysroot 4961
6625 directory for the target for which the current recipe is being built 4962 PF
6626 (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__). 4963 Specifies the recipe or package name and includes all version and
6627 4964 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
6628STAGING_INCDIR 4965 ``bash-4.2-r1/``). This variable is comprised of the following:
6629 Specifies the path to the ``/usr/include`` subdirectory of the 4966 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
6630 sysroot directory for the target for which the current recipe being 4967
6631 built (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__). 4968 PIXBUF_PACKAGES
6632 4969 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
6633STAGING_INCDIR_NATIVE 4970 class, this variable identifies packages that contain the pixbuf
6634 Specifies the path to the ``/usr/include`` subdirectory of the 4971 loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache``
6635 sysroot directory for the build host. 4972 class assumes that the loaders are in the recipe's main package (i.e.
6636 4973 ``${``\ :term:`PN`\ ``}``). Use this variable if the
6637STAGING_KERNEL_BUILDDIR 4974 loaders you need are in a package other than that main package.
6638 Points to the directory containing the kernel build artifacts. 4975
6639 Recipes building software that needs to access kernel build artifacts 4976 PKG
6640 (e.g. ``systemtap-uprobes``) can look in the directory specified with 4977 The name of the resulting package created by the OpenEmbedded build
6641 the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts 4978 system.
6642 after the kernel has been built. 4979
6643 4980 .. note::
6644STAGING_KERNEL_DIR 4981
6645 The directory with kernel headers that are required to build 4982 When using the
6646 out-of-tree modules. 4983 PKG
6647 4984 variable, you must use a package name override.
6648STAGING_LIBDIR 4985
6649 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 4986 For example, when the :ref:`debian <ref-classes-debian>` class
6650 directory for the target for which the current recipe is being built 4987 renames the output package, it does so by setting
6651 (```STAGING_DIR_HOST`` <#var-STAGING_DIR_HOST>`__). 4988 ``PKG_packagename``.
6652 4989
6653STAGING_LIBDIR_NATIVE 4990 PKG_CONFIG_PATH
6654 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 4991 The path to ``pkg-config`` files for the current build context.
6655 directory for the build host. 4992 ``pkg-config`` reads this variable from the environment.
6656 4993
6657STAMP 4994 PKGD
6658 Specifies the base path used to create recipe stamp files. The path 4995 Points to the destination directory for files to be packaged before
6659 to an actual stamp file is constructed by evaluating this string and 4996 they are split into individual packages. This directory defaults to
6660 then appending additional information. Currently, the default 4997 the following: ${WORKDIR}/package
6661 assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` 4998
6662 file is: STAMP = 4999 Do not change this default.
6663 "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 5000
6664 5001 PKGDATA_DIR
6665 For information on how BitBake uses stamp files to determine if a 5002 Points to a shared, global-state directory that holds data generated
6666 task should be rerun, see the "`Stamp Files and the Rerunning of 5003 during the packaging process. During the packaging process, the
6667 Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__" 5004 :ref:`ref-tasks-packagedata` task packages data
6668 section in the Yocto Project Overview and Concepts Manual. 5005 for each recipe and installs it into this temporary, shared area.
6669 5006 This directory defaults to the following, which you should not
6670 See ```STAMPS_DIR`` <#var-STAMPS_DIR>`__, 5007 change: ${STAGING_DIR_HOST}/pkgdata For examples of how this data is
6671 ```MULTIMACH_TARGET_SYS`` <#var-MULTIMACH_TARGET_SYS>`__, 5008 used, see the "`Automatically Added Runtime
6672 ```PN`` <#var-PN>`__, ```EXTENDPE`` <#var-EXTENDPE>`__, 5009 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
6673 ```PV`` <#var-PV>`__, and ```PR`` <#var-PR>`__ for related variable 5010 section in the Yocto Project Overview and Concepts Manual and the
6674 information. 5011 "`Viewing Package Information with
6675 5012 ``oe-pkgdata-util`` <&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util>`__"
6676STAMPS_DIR 5013 section in the Yocto Project Development Tasks Manual. For more
6677 Specifies the base directory in which the OpenEmbedded build system 5014 information on the shared, global-state directory, see
6678 places stamps. The default directory is ``${TMPDIR}/stamps``. 5015 :term:`STAGING_DIR_HOST`.
6679 5016
6680STRIP 5017 PKGDEST
6681 The minimal command and arguments to run ``strip``, which is used to 5018 Points to the parent directory for files to be packaged after they
6682 strip symbols. 5019 have been split into individual packages. This directory defaults to
6683 5020 the following: ${WORKDIR}/packages-split
6684SUMMARY 5021
6685 The short (72 characters or less) summary of the binary package for 5022 Under this directory, the build system creates directories for each
6686 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 5023 package specified in :term:`PACKAGES`. Do not change
6687 ``SUMMARY`` is used to define the 5024 this default.
6688 ```DESCRIPTION`` <#var-DESCRIPTION>`__ variable if ``DESCRIPTION`` is 5025
6689 not set in the recipe. 5026 PKGDESTWORK
6690 5027 Points to a temporary work area where the
6691SVNDIR 5028 :ref:`ref-tasks-package` task saves package metadata.
6692 The directory in which files checked out of a Subversion system are 5029 The ``PKGDESTWORK`` location defaults to the following:
6693 stored. 5030 ${WORKDIR}/pkgdata Do not change this default.
6694 5031
6695SYSLINUX_DEFAULT_CONSOLE 5032 The :ref:`ref-tasks-packagedata` task copies the
6696 Specifies the kernel boot default console. If you want to use a 5033 package metadata from ``PKGDESTWORK`` to
6697 console other than the default, set this variable in your recipe as 5034 :term:`PKGDATA_DIR` to make it available globally.
6698 follows where "X" is the console number you want to use: 5035
6699 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 5036 PKGE
6700 5037 The epoch of the package(s) built by the recipe. By default, ``PKGE``
6701 The ```syslinux`` <#ref-classes-syslinux>`__ class initially sets 5038 is set to :term:`PE`.
6702 this variable to null but then checks for a value later. 5039
6703 5040 PKGR
6704SYSLINUX_OPTS 5041 The revision of the package(s) built by the recipe. By default,
6705 Lists additional options to add to the syslinux file. You need to set 5042 ``PKGR`` is set to :term:`PR`.
6706 this variable in your recipe. If you want to list multiple options, 5043
6707 separate the options with a semicolon character (``;``). 5044 PKGV
6708 5045 The version of the package(s) built by the recipe. By default,
6709 The ```syslinux`` <#ref-classes-syslinux>`__ class uses this variable 5046 ``PKGV`` is set to :term:`PV`.
6710 to create a set of options. 5047
6711 5048 PN
6712SYSLINUX_SERIAL 5049 This variable can have two separate functions depending on the
6713 Specifies the alternate serial port or turns it off. To turn off 5050 context: a recipe name or a resulting package name.
6714 serial, set this variable to an empty string in your recipe. The 5051
6715 variable's default value is set in the 5052 ``PN`` refers to a recipe name in the context of a file used by the
6716 ```syslinux`` <#ref-classes-syslinux>`__ class as follows: 5053 OpenEmbedded build system as input to create a package. The name is
6717 SYSLINUX_SERIAL ?= "0 115200" 5054 normally extracted from the recipe file name. For example, if the
6718 5055 recipe is named ``expat_2.0.1.bb``, then the default value of ``PN``
6719 The class checks for and uses the variable as needed. 5056 will be "expat".
6720 5057
6721SYSLINUX_SPLASH 5058 The variable refers to a package name in the context of a file
6722 An ``.LSS`` file used as the background for the VGA boot menu when 5059 created or produced by the OpenEmbedded build system.
6723 you use the boot menu. You need to set this variable in your recipe. 5060
6724 5061 If applicable, the ``PN`` variable also contains any special suffix
6725 The ```syslinux`` <#ref-classes-syslinux>`__ class checks for this 5062 or prefix. For example, using ``bash`` to build packages for the
6726 variable and if found, the OpenEmbedded build system installs the 5063 native machine, ``PN`` is ``bash-native``. Using ``bash`` to build
6727 splash screen. 5064 packages for the target and for Multilib, ``PN`` would be ``bash``
6728 5065 and ``lib64-bash``, respectively.
6729SYSLINUX_SERIAL_TTY 5066
6730 Specifies the alternate console=tty... kernel boot argument. The 5067 PNBLACKLIST
6731 variable's default value is set in the 5068 Lists recipes you do not want the OpenEmbedded build system to build.
6732 ```syslinux`` <#ref-classes-syslinux>`__ class as follows: 5069 This variable works in conjunction with the
6733 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 5070 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited
6734 5071 globally.
6735 The class checks for and uses the variable as needed. 5072
6736 5073 To prevent a recipe from being built, use the ``PNBLACKLIST``
6737SYSROOT_DESTDIR 5074 variable in your ``local.conf`` file. Here is an example that
6738 Points to the temporary directory under the work directory (default 5075 prevents ``myrecipe`` from being built: PNBLACKLIST[myrecipe] = "Not
6739 "``${``\ ```WORKDIR`` <#var-WORKDIR>`__\ ``}/sysroot-destdir``") 5076 supported by our organization."
6740 where the files populated into the sysroot are assembled during the 5077
6741 ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task. 5078 POPULATE_SDK_POST_HOST_COMMAND
6742 5079 Specifies a list of functions to call once the OpenEmbedded build
6743SYSROOT_DIRS 5080 system has created the host part of the SDK. You can specify
6744 Directories that are staged into the sysroot by the 5081 functions separated by semicolons: POPULATE_SDK_POST_HOST_COMMAND +=
6745 ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task. By 5082 "function; ... "
6746 default, the following directories are staged: SYSROOT_DIRS = " \\ 5083
6747 ${includedir} \\ ${libdir} \\ ${base_libdir} \\ 5084 If you need to pass the SDK path to a command within a function, you
6748 ${nonarch_base_libdir} \\ ${datadir} \\ " 5085 can use ``${SDK_DIR}``, which points to the parent directory used by
6749 5086 the OpenEmbedded build system when creating SDK output. See the
6750SYSROOT_DIRS_BLACKLIST 5087 :term:`SDK_DIR` variable for more information.
6751 Directories that are not staged into the sysroot by the 5088
6752 ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task. You 5089 POPULATE_SDK_POST_TARGET_COMMAND
6753 can use this variable to exclude certain subdirectories of 5090 Specifies a list of functions to call once the OpenEmbedded build
6754 directories listed in ```SYSROOT_DIRS`` <#var-SYSROOT_DIRS>`__ from 5091 system has created the target part of the SDK. You can specify
6755 staging. By default, the following directories are not staged: 5092 functions separated by semicolons: POPULATE_SDK_POST_TARGET_COMMAND
6756 SYSROOT_DIRS_BLACKLIST = " \\ ${mandir} \\ ${docdir} \\ ${infodir} \\ 5093 += "function; ... "
6757 ${datadir}/locale \\ ${datadir}/applications \\ ${datadir}/fonts \\ 5094
6758 ${datadir}/pixmaps \\ " 5095 If you need to pass the SDK path to a command within a function, you
6759 5096 can use ``${SDK_DIR}``, which points to the parent directory used by
6760SYSROOT_DIRS_NATIVE 5097 the OpenEmbedded build system when creating SDK output. See the
6761 Extra directories staged into the sysroot by the 5098 :term:`SDK_DIR` variable for more information.
6762 ```do_populate_sysroot`` <#ref-tasks-populate_sysroot>`__ task for 5099
6763 ``-native`` recipes, in addition to those specified in 5100 PR
6764 ```SYSROOT_DIRS`` <#var-SYSROOT_DIRS>`__. By default, the following 5101 The revision of the recipe. The default value for this variable is
6765 extra directories are staged: SYSROOT_DIRS_NATIVE = " \\ ${bindir} \\ 5102 "r0". Subsequent revisions of the recipe conventionally have the
6766 ${sbindir} \\ ${base_bindir} \\ ${base_sbindir} \\ ${libexecdir} \\ 5103 values "r1", "r2", and so forth. When :term:`PV` increases,
6767 ${sysconfdir} \\ ${localstatedir} \\ " 5104 ``PR`` is conventionally reset to "r0".
6768 5105
6769 .. note:: 5106 .. note::
6770 5107
6771 Programs built by 5108 The OpenEmbedded build system does not need the aid of
6772 -native 5109 PR
6773 recipes run directly from the sysroot ( 5110 to know when to rebuild a recipe. The build system uses the task
6774 STAGING_DIR_NATIVE 5111 input checksums
6775 ), which is why additional directories containing program 5112 along with the
6776 executables and supporting files need to be staged. 5113 stamp
6777 5114 and
6778SYSROOT_PREPROCESS_FUNCS 5115 shared state cache
6779 A list of functions to execute after files are staged into the 5116 mechanisms.
6780 sysroot. These functions are usually used to apply additional 5117
6781 processing on the staged files, or to stage additional files. 5118 The ``PR`` variable primarily becomes significant when a package
6782 5119 manager dynamically installs packages on an already built image. In
6783SYSTEMD_AUTO_ENABLE 5120 this case, ``PR``, which is the default value of
6784 When inheriting the ```systemd`` <#ref-classes-systemd>`__ class, 5121 :term:`PKGR`, helps the package manager distinguish which
6785 this variable specifies whether the specified service in 5122 package is the most recent one in cases where many packages have the
6786 ```SYSTEMD_SERVICE`` <#var-SYSTEMD_SERVICE>`__ should start 5123 same ``PV`` (i.e. ``PKGV``). A component having many packages with
6787 automatically or not. By default, the service is enabled to 5124 the same ``PV`` usually means that the packages all install the same
6788 automatically start at boot time. The default setting is in the 5125 upstream version, but with later (``PR``) version packages including
6789 ```systemd`` <#ref-classes-systemd>`__ class as follows: 5126 packaging fixes.
6790 SYSTEMD_AUTO_ENABLE ??= "enable" 5127
6791 5128 .. note::
6792 You can disable the service by setting the variable to "disable". 5129
6793 5130 PR
6794SYSTEMD_BOOT_CFG 5131 does not need to be increased for changes that do not change the
6795 When ```EFI_PROVIDER`` <#var-EFI_PROVIDER>`__ is set to 5132 package contents or metadata.
6796 "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the 5133
6797 configuration file that should be used. By default, the 5134 Because manually managing ``PR`` can be cumbersome and error-prone,
6798 ```systemd-boot`` <#ref-classes-systemd-boot>`__ class sets the 5135 an automated solution exists. See the "`Working With a PR
6799 ``SYSTEMD_BOOT_CFG`` as follows: SYSTEMD_BOOT_CFG ?= 5136 Service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__" section
6800 "${`S <#var-S>`__}/loader.conf" 5137 in the Yocto Project Development Tasks Manual for more information.
6801 5138
6802 For information on Systemd-boot, see the `Systemd-boot 5139 PREFERRED_PROVIDER
6803 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 5140 If multiple recipes provide the same item, this variable determines
6804 5141 which recipe is preferred and thus provides the item (i.e. the
6805SYSTEMD_BOOT_ENTRIES 5142 preferred provider). You should always suffix this variable with the
6806 When ```EFI_PROVIDER`` <#var-EFI_PROVIDER>`__ is set to 5143 name of the provided item. And, you should define the variable using
6807 "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a 5144 the preferred recipe's name (:term:`PN`). Here is a common
6808 list of entry files (``*.conf``) to install that contain one boot 5145 example: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" In the
6809 entry per file. By default, the 5146 previous example, multiple recipes are providing "virtual/kernel".
6810 ```systemd-boot`` <#ref-classes-systemd-boot>`__ class sets the 5147 The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of
6811 ``SYSTEMD_BOOT_ENTRIES`` as follows: SYSTEMD_BOOT_ENTRIES ?= "" 5148 the recipe you prefer to provide "virtual/kernel".
6812 5149
6813 For information on Systemd-boot, see the `Systemd-boot 5150 Following are more examples: PREFERRED_PROVIDER_virtual/xserver =
6814 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 5151 "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" For more
6815 5152 information, see the "`Using Virtual
6816SYSTEMD_BOOT_TIMEOUT 5153 Providers <&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers>`__"
6817 When ```EFI_PROVIDER`` <#var-EFI_PROVIDER>`__ is set to 5154 section in the Yocto Project Development Tasks Manual.
6818 "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the 5155
6819 boot menu timeout in seconds. By default, the 5156 .. note::
6820 ```systemd-boot`` <#ref-classes-systemd-boot>`__ class sets the 5157
6821 ``SYSTEMD_BOOT_TIMEOUT`` as follows: SYSTEMD_BOOT_TIMEOUT ?= "10" 5158 If you use a
6822 5159 virtual/\*
6823 For information on Systemd-boot, see the `Systemd-boot 5160 item with
6824 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 5161 PREFERRED_PROVIDER
6825 5162 , then any recipe that
6826SYSTEMD_PACKAGES 5163 PROVIDES
6827 When inheriting the ```systemd`` <#ref-classes-systemd>`__ class, 5164 that item but is not selected (defined) by
6828 this variable locates the systemd unit files when they are not found 5165 PREFERRED_PROVIDER
6829 in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` 5166 is prevented from building, which is usually desirable since this
6830 variable is set such that the systemd unit files are assumed to 5167 mechanism is designed to select between mutually exclusive
6831 reside in the recipes main package: SYSTEMD_PACKAGES ?= "${PN}" 5168 alternative providers.
6832 5169
6833 If these unit files are not in this recipe's main package, you need 5170 PREFERRED_VERSION
6834 to use ``SYSTEMD_PACKAGES`` to list the package or packages in which 5171 If multiple versions of recipes exist, this variable determines which
6835 the build system can find the systemd unit files. 5172 version is given preference. You must always suffix the variable with
6836 5173 the :term:`PN` you want to select, and you should set the
6837SYSTEMD_SERVICE 5174 :term:`PV` accordingly for precedence.
6838 When inheriting the ```systemd`` <#ref-classes-systemd>`__ class, 5175
6839 this variable specifies the systemd service name for a package. 5176 The ``PREFERRED_VERSION`` variable supports limited wildcard use
6840 5177 through the "``%``" character. You can use the character to match any
6841 When you specify this file in your recipe, use a package name 5178 number of characters, which can be useful when specifying versions
6842 override to indicate the package to which the value applies. Here is 5179 that contain long revision numbers that potentially change. Here are
6843 an example from the connman recipe: SYSTEMD_SERVICE_${PN} = 5180 two examples: PREFERRED_VERSION_python = "3.4.0"
6844 "connman.service" 5181 PREFERRED_VERSION_linux-yocto = "5.0%"
6845 5182
6846SYSVINIT_ENABLED_GETTYS 5183 .. note::
6847 When using 5184
6848 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__, 5185 The use of the "
6849 specifies a space-separated list of the virtual terminals that should 5186 %
6850 run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ 5187 " character is limited in that it only works at the end of the
6851 (allowing login), assuming ```USE_VT`` <#var-USE_VT>`__ is not set to 5188 string. You cannot use the wildcard character in any other
6852 "0". 5189 location of the string.
6853 5190
6854 The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only 5191 The specified version is matched against :term:`PV`, which
6855 run a getty on the first virtual terminal). 5192 does not necessarily match the version part of the recipe's filename.
6856 5193 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
6857T 5194 where ``foo_git.bb`` contains the following assignment: PV =
6858 This variable points to a directory were BitBake places temporary 5195 "1.1+git${SRCPV}" In this case, the correct way to select
6859 files, which consist mostly of task logs and scripts, when building a 5196 ``foo_git.bb`` is by using an assignment such as the following:
6860 particular recipe. The variable is typically set as follows: T = 5197 PREFERRED_VERSION_foo = "1.1+git%" Compare that previous example
6861 "${WORKDIR}/temp" 5198 against the following incorrect example, which does not work:
6862 5199 PREFERRED_VERSION_foo = "git"
6863 The ```WORKDIR`` <#var-WORKDIR>`__ is the directory into which 5200
6864 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 5201 Sometimes the ``PREFERRED_VERSION`` variable can be set by
6865 file sets this variable. 5202 configuration files in a way that is hard to change. You can use
6866 5203 :term:`OVERRIDES` to set a machine-specific
6867 The ``T`` variable is not to be confused with the 5204 override. Here is an example: PREFERRED_VERSION_linux-yocto_qemux86 =
6868 ```TMPDIR`` <#var-TMPDIR>`__ variable, which points to the root of 5205 "5.0%" Although not recommended, worst case, you can also use the
6869 the directory tree where BitBake places the output of an entire 5206 "forcevariable" override, which is the strongest override possible.
6870 build. 5207 Here is an example: PREFERRED_VERSION_linux-yocto_forcevariable =
6871 5208 "5.0%"
6872TARGET_ARCH 5209
6873 The target machine's architecture. The OpenEmbedded build system 5210 .. note::
6874 supports many architectures. Here is an example list of architectures 5211
6875 supported. This list is by no means complete as the architecture is 5212 The
6876 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel 5213 \_forcevariable
6877 5214 override is not handled specially. This override only works
6878 For additional information on machine architectures, see the 5215 because the default value of
6879 ```TUNE_ARCH`` <#var-TUNE_ARCH>`__ variable. 5216 OVERRIDES
6880 5217 includes "forcevariable".
6881TARGET_AS_ARCH 5218
6882 Specifies architecture-specific assembler flags for the target 5219 PREMIRRORS
6883 system. ``TARGET_AS_ARCH`` is initialized from 5220 Specifies additional paths from which the OpenEmbedded build system
6884 ```TUNE_ASARGS`` <#var-TUNE_ASARGS>`__ by default in the BitBake 5221 gets source code. When the build system searches for source code, it
6885 configuration file (``meta/conf/bitbake.conf``): TARGET_AS_ARCH = 5222 first tries the local download directory. If that location fails, the
6886 "${TUNE_ASARGS}" 5223 build system tries locations defined by ``PREMIRRORS``, the upstream
6887 5224 source, and then locations specified by
6888TARGET_CC_ARCH 5225 :term:`MIRRORS` in that order.
6889 Specifies architecture-specific C compiler flags for the target 5226
6890 system. ``TARGET_CC_ARCH`` is initialized from 5227 Assuming your distribution (:term:`DISTRO`) is "poky",
6891 ```TUNE_CCARGS`` <#var-TUNE_CCARGS>`__ by default. 5228 the default value for ``PREMIRRORS`` is defined in the
6892 5229 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
6893 .. note:: 5230
6894 5231 Typically, you could add a specific server for the build system to
6895 It is a common workaround to append 5232 attempt before any others by adding something like the following to
6896 LDFLAGS 5233 the ``local.conf`` configuration file in the
6897 to 5234 :term:`Build Directory`: PREMIRRORS_prepend = "\\
6898 TARGET_CC_ARCH 5235 git://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\*
6899 in recipes that build software for the target that would not 5236 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\*
6900 otherwise respect the exported 5237 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\*
6901 LDFLAGS 5238 http://www.yoctoproject.org/sources/ \\n" These changes cause the
6902 variable. 5239 build system to intercept Git, FTP, HTTP, and HTTPS requests and
6903 5240 direct them to the ``http://`` sources mirror. You can use
6904TARGET_CC_KERNEL_ARCH 5241 ``file://`` URLs to point to local directories or network shares as
6905 This is a specific kernel compiler flag for a CPU or Application 5242 well.
6906 Binary Interface (ABI) tune. The flag is used rarely and only for 5243
6907 cases where a userspace ```TUNE_CCARGS`` <#var-TUNE_CCARGS>`__ is not 5244 PRIORITY
6908 compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` 5245 Indicates the importance of a package.
6909 variable allows the kernel (and associated modules) to use a 5246
6910 different configuration. See the 5247 ``PRIORITY`` is considered to be part of the distribution policy
6911 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 5248 because the importance of any given recipe depends on the purpose for
6912 `Source Directory <#source-directory>`__ for an example. 5249 which the distribution is being produced. Thus, ``PRIORITY`` is not
6913 5250 normally set within recipes.
6914TARGET_CFLAGS 5251
6915 Specifies the flags to pass to the C compiler when building for the 5252 You can set ``PRIORITY`` to "required", "standard", "extra", and
6916 target. When building in the target context, 5253 "optional", which is the default.
6917 ```CFLAGS`` <#var-CFLAGS>`__ is set to the value of this variable by 5254
6918 default. 5255 PRIVATE_LIBS
6919 5256 Specifies libraries installed within a recipe that should be ignored
6920 Additionally, the SDK's environment setup script sets the ``CFLAGS`` 5257 by the OpenEmbedded build system's shared library resolver. This
6921 variable in the environment to the ``TARGET_CFLAGS`` value so that 5258 variable is typically used when software being built by a recipe has
6922 executables built using the SDK also have the flags applied. 5259 its own private versions of a library normally provided by another
6923 5260 recipe. In this case, you would not want the package containing the
6924TARGET_CPPFLAGS 5261 private libraries to be set as a dependency on other unrelated
6925 Specifies the flags to pass to the C pre-processor (i.e. to both the 5262 packages that should instead depend on the package providing the
6926 C and the C++ compilers) when building for the target. When building 5263 standard version of the library.
6927 in the target context, ```CPPFLAGS`` <#var-CPPFLAGS>`__ is set to the 5264
6928 value of this variable by default. 5265 Libraries specified in this variable should be specified by their
6929 5266 file name. For example, from the Firefox recipe in meta-browser:
6930 Additionally, the SDK's environment setup script sets the 5267 PRIVATE_LIBS = "libmozjs.so \\ libxpcom.so \\ libnspr4.so \\
6931 ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` 5268 libxul.so \\ libmozalloc.so \\ libplc4.so \\ libplds4.so"
6932 value so that executables built using the SDK also have the flags 5269
6933 applied. 5270 For more information, see the "`Automatically Added Runtime
6934 5271 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
6935TARGET_CXXFLAGS 5272 section in the Yocto Project Overview and Concepts Manual.
6936 Specifies the flags to pass to the C++ compiler when building for the 5273
6937 target. When building in the target context, 5274 PROVIDES
6938 ```CXXFLAGS`` <#var-CXXFLAGS>`__ is set to the value of this variable 5275 A list of aliases by which a particular recipe can be known. By
6939 by default. 5276 default, a recipe's own ``PN`` is implicitly already in its
6940 5277 ``PROVIDES`` list and therefore does not need to mention that it
6941 Additionally, the SDK's environment setup script sets the 5278 provides itself. If a recipe uses ``PROVIDES``, the additional
6942 ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` 5279 aliases are synonyms for the recipe and can be useful for satisfying
6943 value so that executables built using the SDK also have the flags 5280 dependencies of other recipes during the build as specified by
6944 applied. 5281 ``DEPENDS``.
6945 5282
6946TARGET_FPU 5283 Consider the following example ``PROVIDES`` statement from the recipe
6947 Specifies the method for handling FPU code. For FPU-less targets, 5284 file ``eudev_3.2.9.bb``: PROVIDES = "udev" The ``PROVIDES`` statement
6948 which include most ARM CPUs, the variable must be set to "soft". If 5285 results in the "eudev" recipe also being available as simply "udev".
6949 not, the kernel emulation gets used, which results in a performance 5286
6950 penalty. 5287 .. note::
6951 5288
6952TARGET_LD_ARCH 5289 Given that a recipe's own recipe name is already implicitly in its
6953 Specifies architecture-specific linker flags for the target system. 5290 own
6954 ``TARGET_LD_ARCH`` is initialized from 5291 PROVIDES
6955 ```TUNE_LDARGS`` <#var-TUNE_LDARGS>`__ by default in the BitBake 5292 list, it is unnecessary to add aliases with the "+=" operator;
6956 configuration file (``meta/conf/bitbake.conf``): TARGET_LD_ARCH = 5293 using a simple assignment will be sufficient. In other words,
6957 "${TUNE_LDARGS}" 5294 while you could write:
6958 5295 ::
6959TARGET_LDFLAGS 5296
6960 Specifies the flags to pass to the linker when building for the 5297 PROVIDES += "udev"
6961 target. When building in the target context, 5298
6962 ```LDFLAGS`` <#var-LDFLAGS>`__ is set to the value of this variable 5299
6963 by default. 5300 in the above, the "+=" is overkill and unnecessary.
6964 5301
6965 Additionally, the SDK's environment setup script sets the 5302 In addition to providing recipes under alternate names, the
6966 ```LDFLAGS`` <#var-LDFLAGS>`__ variable in the environment to the 5303 ``PROVIDES`` mechanism is also used to implement virtual targets. A
6967 ``TARGET_LDFLAGS`` value so that executables built using the SDK also 5304 virtual target is a name that corresponds to some particular
6968 have the flags applied. 5305 functionality (e.g. a Linux kernel). Recipes that provide the
6969 5306 functionality in question list the virtual target in ``PROVIDES``.
6970TARGET_OS 5307 Recipes that depend on the functionality in question can include the
6971 Specifies the target's operating system. The variable can be set to 5308 virtual target in ``DEPENDS`` to leave the choice of provider open.
6972 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 5309
6973 for musl libc. For ARM/EABI targets, "linux-gnueabi" and 5310 Conventionally, virtual targets have names on the form
6974 "linux-musleabi" possible values exist. 5311 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
6975 5312 of the name and has no syntactical significance.
6976TARGET_PREFIX 5313
6977 Specifies the prefix used for the toolchain binary target tools. 5314 The :term:`PREFERRED_PROVIDER` variable is
6978 5315 used to select which particular recipe provides a virtual target.
6979 Depending on the type of recipe and the build target, 5316
6980 ``TARGET_PREFIX`` is set as follows: 5317 .. note::
6981 5318
6982 - For recipes building for the target machine, the value is 5319 A corresponding mechanism for virtual runtime dependencies
6983 "${`TARGET_SYS <#var-TARGET_SYS>`__}-". 5320 (packages) exists. However, the mechanism does not depend on any
6984 5321 special functionality beyond ordinary variable assignments. For
6985 - For native recipes, the build system sets the variable to the 5322 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of
6986 value of ``BUILD_PREFIX``. 5323 the component that manages the ``/dev`` directory.
6987 5324
6988 - For native SDK recipes (``nativesdk``), the build system sets the 5325 Setting the "preferred provider" for runtime dependencies is as
6989 variable to the value of ``SDK_PREFIX``. 5326 simple as using the following assignment in a configuration file:
6990 5327
6991TARGET_SYS 5328 ::
6992 Specifies the system, including the architecture and the operating 5329
6993 system, for which the build is occurring in the context of the 5330 VIRTUAL-RUNTIME_dev_manager = "udev"
6994 current recipe. 5331
6995 5332
6996 The OpenEmbedded build system automatically sets this variable based 5333 PRSERV_HOST
6997 on ```TARGET_ARCH`` <#var-TARGET_ARCH>`__, 5334 The network based :term:`PR` service host and port.
6998 ```TARGET_VENDOR`` <#var-TARGET_VENDOR>`__, and 5335
6999 ```TARGET_OS`` <#var-TARGET_OS>`__ variables. 5336 The ``conf/local.conf.sample.extended`` configuration file in the
7000 5337 :term:`Source Directory` shows how the
7001 .. note:: 5338 ``PRSERV_HOST`` variable is set: PRSERV_HOST = "localhost:0" You must
7002 5339 set the variable if you want to automatically start a local `PR
7003 You do not need to set the 5340 service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__. You can
7004 TARGET_SYS 5341 set ``PRSERV_HOST`` to other values to use a remote PR service.
5342
5343 PTEST_ENABLED
5344 Specifies whether or not `Package
5345 Test <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__ (ptest)
5346 functionality is enabled when building a recipe. You should not set
5347 this variable directly. Enabling and disabling building Package Tests
5348 at build time should be done by adding "ptest" to (or removing it
5349 from) :term:`DISTRO_FEATURES`.
5350
5351 PV
5352 The version of the recipe. The version is normally extracted from the
5353 recipe filename. For example, if the recipe is named
5354 ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1".
5355 ``PV`` is generally not overridden within a recipe unless it is
5356 building an unstable (i.e. development) version from a source code
5357 repository (e.g. Git or Subversion).
5358
5359 ``PV`` is the default value of the :term:`PKGV` variable.
5360
5361 PYTHON_ABI
5362 When used by recipes that inherit the
5363 :ref:`distutils3 <ref-classes-distutils3>`,
5364 :ref:`setuptools3 <ref-classes-setuptools3>`,
5365 :ref:`distutils <ref-classes-distutils>`, or
5366 :ref:`setuptools <ref-classes-setuptools>` classes, denotes the
5367 Application Binary Interface (ABI) currently in use for Python. By
5368 default, the ABI is "m". You do not have to set this variable as the
5369 OpenEmbedded build system sets it for you.
5370
5371 The OpenEmbedded build system uses the ABI to construct directory
5372 names used when installing the Python headers and libraries in
5373 sysroot (e.g. ``.../python3.3m/...``).
5374
5375 Recipes that inherit the ``distutils`` class during cross-builds also
5376 use this variable to locate the headers and libraries of the
5377 appropriate Python that the extension is targeting.
5378
5379 PYTHON_PN
5380 When used by recipes that inherit the
5381 `distutils3 <ref-classes-distutils3>`,
5382 :ref:`setuptools3 <ref-classes-setuptools3>`,
5383 :ref:`distutils <ref-classes-distutils>`, or
5384 :ref:`setuptools <ref-classes-setuptools>` classes, specifies the
5385 major Python version being built. For Python 3.x, ``PYTHON_PN`` would
5386 be "python3". You do not have to set this variable as the
5387 OpenEmbedded build system automatically sets it for you.
5388
5389 The variable allows recipes to use common infrastructure such as the
5390 following: DEPENDS += "${PYTHON_PN}-native" In the previous example,
5391 the version of the dependency is ``PYTHON_PN``.
5392
5393 RANLIB
5394 The minimal command and arguments to run ``ranlib``.
5395
5396 RCONFLICTS
5397 The list of packages that conflict with packages. Note that packages
5398 will not be installed if conflicting packages are not first removed.
5399
5400 Like all package-controlling variables, you must always use them in
5401 conjunction with a package name override. Here is an example:
5402 RCONFLICTS_${PN} = "another_conflicting_package_name"
5403
5404 BitBake, which the OpenEmbedded build system uses, supports
5405 specifying versioned dependencies. Although the syntax varies
5406 depending on the packaging format, BitBake hides these differences
5407 from you. Here is the general syntax to specify versions with the
5408 ``RCONFLICTS`` variable: RCONFLICTS_${PN} = "package (operator
5409 version)" For ``operator``, you can specify the following: = < > <=
5410 >= For example, the following sets up a dependency on version 1.2 or
5411 greater of the package ``foo``: RCONFLICTS_${PN} = "foo (>= 1.2)"
5412
5413 RDEPENDS
5414 Lists runtime dependencies of a package. These dependencies are other
5415 packages that must be installed in order for the package to function
5416 correctly. As an example, the following assignment declares that the
5417 package ``foo`` needs the packages ``bar`` and ``baz`` to be
5418 installed: RDEPENDS_foo = "bar baz" The most common types of package
5419 runtime dependencies are automatically detected and added. Therefore,
5420 most recipes do not need to set ``RDEPENDS``. For more information,
5421 see the "`Automatically Added Runtime
5422 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
5423 section in the Yocto Project Overview and Concepts Manual.
5424
5425 The practical effect of the above ``RDEPENDS`` assignment is that
5426 ``bar`` and ``baz`` will be declared as dependencies inside the
5427 package ``foo`` when it is written out by one of the
5428 ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks.
5429 Exactly how this is done depends on which package format is used,
5430 which is determined by
5431 :term:`PACKAGE_CLASSES`. When the
5432 corresponding package manager installs the package, it will know to
5433 also install the packages on which it depends.
5434
5435 To ensure that the packages ``bar`` and ``baz`` get built, the
5436 previous ``RDEPENDS`` assignment also causes a task dependency to be
5437 added. This dependency is from the recipe's
5438 :ref:`ref-tasks-build` (not to be confused with
5439 :ref:`ref-tasks-compile`) task to the
5440 ``do_package_write_*`` task of the recipes that build ``bar`` and
5441 ``baz``.
5442
5443 The names of the packages you list within ``RDEPENDS`` must be the
5444 names of other packages - they cannot be recipe names. Although
5445 package names and recipe names usually match, the important point
5446 here is that you are providing package names within the ``RDEPENDS``
5447 variable. For an example of the default list of packages created from
5448 a recipe, see the :term:`PACKAGES` variable.
5449
5450 Because the ``RDEPENDS`` variable applies to packages being built,
5451 you should always use the variable in a form with an attached package
5452 name (remember that a single recipe can build multiple packages). For
5453 example, suppose you are building a development package that depends
5454 on the ``perl`` package. In this case, you would use the following
5455 ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the example,
5456 the development package depends on the ``perl`` package. Thus, the
5457 ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of
5458 the variable.
5459
5460 .. note::
5461
5462 RDEPENDS_${PN}-dev
5463 includes
5464 ${
5465 PN
5466 }
5467 by default. This default is set in the BitBake configuration file
5468 (
5469 meta/conf/bitbake.conf
5470 ). Be careful not to accidentally remove
5471 ${PN}
5472 when modifying
5473 RDEPENDS_${PN}-dev
5474 . Use the "+=" operator rather than the "=" operator.
5475
5476 The package names you use with ``RDEPENDS`` must appear as they would
5477 in the ``PACKAGES`` variable. The :term:`PKG` variable
5478 allows a different name to be used for the final package (e.g. the
5479 :ref:`debian <ref-classes-debian>` class uses this to rename
5480 packages), but this final package name cannot be used with
5481 ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be
5482 independent of the package format used.
5483
5484 BitBake, which the OpenEmbedded build system uses, supports
5485 specifying versioned dependencies. Although the syntax varies
5486 depending on the packaging format, BitBake hides these differences
5487 from you. Here is the general syntax to specify versions with the
5488 ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator version)"
5489 For operator, you can specify the following: = < > <= >= For version,
5490 provide the version number.
5491
5492 .. note::
5493
5494 You can use
5495 EXTENDPKGV
5496 to provide a full package version specification.
5497
5498 For example, the following sets up a dependency on version 1.2 or
5499 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)"
5500
5501 For information on build-time dependencies, see the
5502 :term:`DEPENDS` variable. You can also see the
5503 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and
5504 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the
5505 BitBake User Manual for additional information on tasks and
5506 dependencies.
5507
5508 REQUIRED_DISTRO_FEATURES
5509 When inheriting the
5510 :ref:`distro_features_check <ref-classes-distro_features_check>`
5511 class, this variable identifies distribution features that must exist
5512 in the current configuration in order for the OpenEmbedded build
5513 system to build the recipe. In other words, if the
5514 ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not
5515 appear in ``DISTRO_FEATURES`` within the current configuration, an
5516 error occurs and the build stops.
5517
5518 RM_WORK_EXCLUDE
5519 With ``rm_work`` enabled, this variable specifies a list of recipes
5520 whose work directories should not be removed. See the
5521 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more
5522 details.
5523
5524 ROOT_HOME
5525 Defines the root home directory. By default, this directory is set as
5526 follows in the BitBake configuration file: ROOT_HOME ??= "/home/root"
5527
5528 .. note::
5529
5530 This default value is likely used because some embedded solutions
5531 prefer to have a read-only root filesystem and prefer to keep
5532 writeable data in one place.
5533
5534 You can override the default by setting the variable in any layer or
5535 in the ``local.conf`` file. Because the default is set using a "weak"
5536 assignment (i.e. "??="), you can use either of the following forms to
5537 define your override: ROOT_HOME = "/root" ROOT_HOME ?= "/root" These
5538 override examples use ``/root``, which is probably the most commonly
5539 used override.
5540
5541 ROOTFS
5542 Indicates a filesystem image to include as the root filesystem.
5543
5544 The ``ROOTFS`` variable is an optional variable used with the
5545 :ref:`image-live <ref-classes-image-live>` class.
5546
5547 ROOTFS_POSTINSTALL_COMMAND
5548 Specifies a list of functions to call after the OpenEmbedded build
5549 system has installed packages. You can specify functions separated by
5550 semicolons: ROOTFS_POSTINSTALL_COMMAND += "function; ... "
5551
5552 If you need to pass the root filesystem path to a command within a
5553 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5554 directory that becomes the root filesystem image. See the
5555 :term:`IMAGE_ROOTFS` variable for more
5556 information.
5557
5558 ROOTFS_POSTPROCESS_COMMAND
5559 Specifies a list of functions to call once the OpenEmbedded build
5560 system has created the root filesystem. You can specify functions
5561 separated by semicolons: ROOTFS_POSTPROCESS_COMMAND += "function; ...
5562 "
5563
5564 If you need to pass the root filesystem path to a command within a
5565 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5566 directory that becomes the root filesystem image. See the
5567 :term:`IMAGE_ROOTFS` variable for more
5568 information.
5569
5570 ROOTFS_POSTUNINSTALL_COMMAND
5571 Specifies a list of functions to call after the OpenEmbedded build
5572 system has removed unnecessary packages. When runtime package
5573 management is disabled in the image, several packages are removed
5574 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
5575 You can specify functions separated by semicolons:
5576 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... "
5577
5578 If you need to pass the root filesystem path to a command within a
5579 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5580 directory that becomes the root filesystem image. See the
5581 :term:`IMAGE_ROOTFS` variable for more
5582 information.
5583
5584 ROOTFS_PREPROCESS_COMMAND
5585 Specifies a list of functions to call before the OpenEmbedded build
5586 system has created the root filesystem. You can specify functions
5587 separated by semicolons: ROOTFS_PREPROCESS_COMMAND += "function; ...
5588 "
5589
5590 If you need to pass the root filesystem path to a command within a
5591 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5592 directory that becomes the root filesystem image. See the
5593 :term:`IMAGE_ROOTFS` variable for more
5594 information.
5595
5596 RPROVIDES
5597 A list of package name aliases that a package also provides. These
5598 aliases are useful for satisfying runtime dependencies of other
5599 packages both during the build and on the target (as specified by
5600 ``RDEPENDS``).
5601
5602 .. note::
5603
5604 A package's own name is implicitly already in its
5605 RPROVIDES
5606 list.
5607
5608 As with all package-controlling variables, you must always use the
5609 variable in conjunction with a package name override. Here is an
5610 example: RPROVIDES_${PN} = "widget-abi-2"
5611
5612 RRECOMMENDS
5613 A list of packages that extends the usability of a package being
5614 built. The package being built does not depend on this list of
5615 packages in order to successfully build, but rather uses them for
5616 extended usability. To specify runtime dependencies for packages, see
5617 the ``RDEPENDS`` variable.
5618
5619 The package manager will automatically install the ``RRECOMMENDS``
5620 list of packages when installing the built package. However, you can
5621 prevent listed packages from being installed by using the
5622 :term:`BAD_RECOMMENDATIONS`,
5623 :term:`NO_RECOMMENDATIONS`, and
5624 :term:`PACKAGE_EXCLUDE` variables.
5625
5626 Packages specified in ``RRECOMMENDS`` need not actually be produced.
5627 However, a recipe must exist that provides each package, either
5628 through the :term:`PACKAGES` or
5629 :term:`PACKAGES_DYNAMIC` variables or the
5630 :term:`RPROVIDES` variable, or an error will occur
5631 during the build. If such a recipe does exist and the package is not
5632 produced, the build continues without error.
5633
5634 Because the ``RRECOMMENDS`` variable applies to packages being built,
5635 you should always attach an override to the variable to specify the
5636 particular package whose usability is being extended. For example,
5637 suppose you are building a development package that is extended to
5638 support wireless functionality. In this case, you would use the
5639 following: RRECOMMENDS_${PN}-dev += "wireless_package_name" In the
5640 example, the package name (``${PN}-dev``) must appear as it would in
5641 the ``PACKAGES`` namespace before any renaming of the output package
5642 by classes such as ``debian.bbclass``.
5643
5644 BitBake, which the OpenEmbedded build system uses, supports
5645 specifying versioned recommends. Although the syntax varies depending
5646 on the packaging format, BitBake hides these differences from you.
5647 Here is the general syntax to specify versions with the
5648 ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package (operator
5649 version)" For ``operator``, you can specify the following: = < > <=
5650 >= For example, the following sets up a recommend on version 1.2 or
5651 greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>= 1.2)"
5652
5653 RREPLACES
5654 A list of packages replaced by a package. The package manager uses
5655 this variable to determine which package should be installed to
5656 replace other package(s) during an upgrade. In order to also have the
5657 other package(s) removed at the same time, you must add the name of
5658 the other package to the ``RCONFLICTS`` variable.
5659
5660 As with all package-controlling variables, you must use this variable
5661 in conjunction with a package name override. Here is an example:
5662 RREPLACES_${PN} = "other_package_being_replaced"
5663
5664 BitBake, which the OpenEmbedded build system uses, supports
5665 specifying versioned replacements. Although the syntax varies
5666 depending on the packaging format, BitBake hides these differences
5667 from you. Here is the general syntax to specify versions with the
5668 ``RREPLACES`` variable: RREPLACES_${PN} = "package (operator
5669 version)" For ``operator``, you can specify the following: = < > <=
5670 >= For example, the following sets up a replacement using version 1.2
5671 or greater of the package ``foo``: RREPLACES_${PN} = "foo (>= 1.2)"
5672
5673 RSUGGESTS
5674 A list of additional packages that you can suggest for installation
5675 by the package manager at the time a package is installed. Not all
5676 package managers support this functionality.
5677
5678 As with all package-controlling variables, you must always use this
5679 variable in conjunction with a package name override. Here is an
5680 example: RSUGGESTS_${PN} = "useful_package another_package"
5681
5682 S
5683 The location in the :term:`Build Directory` where
5684 unpacked recipe source code resides. By default, this directory is
5685 ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
5686 where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe
5687 version. If the source tarball extracts the code to a directory named
5688 anything other than ``${BPN}-${PV}``, or if the source code is
5689 fetched from an SCM such as Git or Subversion, then you must set
5690 ``S`` in the recipe so that the OpenEmbedded build system knows where
5691 to find the unpacked source.
5692
5693 As an example, assume a :term:`Source Directory`
5694 top-level folder named ``poky`` and a default Build Directory at
5695 ``poky/build``. In this case, the work directory the build system
5696 uses to keep the unpacked recipe for ``db`` is the following:
5697 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 The
5698 unpacked source code resides in the ``db-5.1.19`` folder.
5699
5700 This next example assumes a Git repository. By default, Git
5701 repositories are cloned to ``${WORKDIR}/git`` during
5702 :ref:`ref-tasks-fetch`. Since this path is different
5703 from the default value of ``S``, you must set it specifically so the
5704 source can be located: SRC_URI = "git://path/to/repo.git" S =
5705 "${WORKDIR}/git"
5706
5707 SANITY_REQUIRED_UTILITIES
5708 Specifies a list of command-line utilities that should be checked for
5709 during the initial sanity checking process when running BitBake. If
5710 any of the utilities are not installed on the build host, then
5711 BitBake immediately exits with an error.
5712
5713 SANITY_TESTED_DISTROS
5714 A list of the host distribution identifiers that the build system has
5715 been tested against. Identifiers consist of the host distributor ID
5716 followed by the release, as reported by the ``lsb_release`` tool or
5717 as read from ``/etc/lsb-release``. Separate the list items with
5718 explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is
5719 not empty and the current value of
5720 :term:`NATIVELSBSTRING` does not appear in the
5721 list, then the build system reports a warning that indicates the
5722 current host distribution has not been tested as a build host.
5723
5724 SDK_ARCH
5725 The target architecture for the SDK. Typically, you do not directly
5726 set this variable. Instead, use :term:`SDKMACHINE`.
5727
5728 SDK_DEPLOY
5729 The directory set up and used by the
5730 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
5731 the SDK is deployed. The ``populate_sdk_base`` class defines
5732 ``SDK_DEPLOY`` as follows: SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
5733
5734 SDK_DIR
5735 The parent directory used by the OpenEmbedded build system when
5736 creating SDK output. The
5737 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
5738 the variable as follows: SDK_DIR = "${WORKDIR}/sdk"
5739
5740 .. note::
5741
5742 The
5743 SDK_DIR
5744 directory is a temporary directory as it is part of
5745 WORKDIR
5746 . The final output directory is
5747 SDK_DEPLOY
5748 .
5749
5750 SDK_EXT_TYPE
5751 Controls whether or not shared state artifacts are copied into the
5752 extensible SDK. The default value of "full" copies all of the
5753 required shared state artifacts into the extensible SDK. The value
5754 "minimal" leaves these artifacts out of the SDK.
5755
5756 .. note::
5757
5758 If you set the variable to "minimal", you need to ensure
5759 SSTATE_MIRRORS
5760 is set in the SDK's configuration to enable the artifacts to be
5761 fetched as needed.
5762
5763 SDK_HOST_MANIFEST
5764 The manifest file for the host part of the SDK. This file lists all
5765 the installed packages that make up the host part of the SDK. The
5766 file contains package information on a line-per-package basis as
5767 follows: packagename packagearch version
5768
5769 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
5770 defines the manifest file as follows: SDK_HOST_MANIFEST =
5771 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" The location is
5772 derived using the :term:`SDK_DEPLOY` and
5773 :term:`TOOLCHAIN_OUTPUTNAME` variables.
5774
5775 SDK_INCLUDE_PKGDATA
5776 When set to "1", specifies to include the packagedata for all recipes
5777 in the "world" target in the extensible SDK. Including this data
5778 allows the ``devtool search`` command to find these recipes in search
5779 results, as well as allows the ``devtool add`` command to map
5780 dependencies more effectively.
5781
5782 .. note::
5783
5784 Enabling the
5785 SDK_INCLUDE_PKGDATA
5786 variable significantly increases build time because all of world
5787 needs to be built. Enabling the variable also slightly increases
5788 the size of the extensible SDK.
5789
5790 SDK_INCLUDE_TOOLCHAIN
5791 When set to "1", specifies to include the toolchain in the extensible
5792 SDK. Including the toolchain is useful particularly when
5793 :term:`SDK_EXT_TYPE` is set to "minimal" to keep
5794 the SDK reasonably small but you still want to provide a usable
5795 toolchain. For example, suppose you want to use the toolchain from an
5796 IDE or from other tools and you do not want to perform additional
5797 steps to install the toolchain.
5798
5799 The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if
5800 ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if
5801 ``SDK_EXT_TYPE`` is set to "full".
5802
5803 SDK_INHERIT_BLACKLIST
5804 A list of classes to remove from the :term:`INHERIT`
5805 value globally within the extensible SDK configuration. The
5806 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
5807 default value: SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
5808
5809 Some classes are not generally applicable within the extensible SDK
5810 context. You can use this variable to disable those classes.
5811
5812 For additional information on how to customize the extensible SDK's
5813 configuration, see the "`Configuring the Extensible
5814 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5815 section in the Yocto Project Application Development and the
5816 Extensible Software Development Kit (eSDK) manual.
5817
5818 SDK_LOCAL_CONF_BLACKLIST
5819 A list of variables not allowed through from the OpenEmbedded build
5820 system configuration into the extensible SDK configuration. Usually,
5821 these are variables that are specific to the machine on which the
5822 build system is running and thus would be potentially problematic
5823 within the extensible SDK.
5824
5825 By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the
5826 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
5827 excludes the following variables:
5828 :term:`CONF_VERSION`
5829 :term:`BB_NUMBER_THREADS`
5830 :term:`bitbake:BB_NUMBER_PARSE_THREADS`
5831 :term:`PARALLEL_MAKE`
5832 :term:`PRSERV_HOST`
5833 :term:`SSTATE_MIRRORS` :term:`DL_DIR`
5834 :term:`SSTATE_DIR` :term:`TMPDIR`
5835 :term:`BB_SERVER_TIMEOUT`
5836
5837 For additional information on how to customize the extensible SDK's
5838 configuration, see the "`Configuring the Extensible
5839 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5840 section in the Yocto Project Application Development and the
5841 Extensible Software Development Kit (eSDK) manual.
5842
5843 SDK_LOCAL_CONF_WHITELIST
5844 A list of variables allowed through from the OpenEmbedded build
5845 system configuration into the extensible SDK configuration. By
5846 default, the list of variables is empty and is set in the
5847 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
5848
5849 This list overrides the variables specified using the
5850 :term:`SDK_LOCAL_CONF_BLACKLIST`
5851 variable as well as any variables identified by automatic
5852 blacklisting due to the "/" character being found at the start of the
5853 value, which is usually indicative of being a path and thus might not
5854 be valid on the system where the SDK is installed.
5855
5856 For additional information on how to customize the extensible SDK's
5857 configuration, see the "`Configuring the Extensible
5858 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__"
5859 section in the Yocto Project Application Development and the
5860 Extensible Software Development Kit (eSDK) manual.
5861
5862 SDK_NAME
5863 The base name for SDK output files. The name is derived from the
5864 :term:`DISTRO`, :term:`TCLIBC`,
5865 :term:`SDK_ARCH`,
5866 :term:`IMAGE_BASENAME`, and
5867 :term:`TUNE_PKGARCH` variables: SDK_NAME =
5868 "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
5869
5870 SDK_OS
5871 Specifies the operating system for which the SDK will be built. The
5872 default value is the value of :term:`BUILD_OS`.
5873
5874 SDK_OUTPUT
5875 The location used by the OpenEmbedded build system when creating SDK
5876 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
5877 class defines the variable as follows: SDK_DIR = "${WORKDIR}/sdk"
5878 SDK_OUTPUT = "${SDK_DIR}/image" SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
5879
5880 .. note::
5881
5882 The
5883 SDK_OUTPUT
5884 directory is a temporary directory as it is part of
5885 WORKDIR
5886 by way of
5887 SDK_DIR
5888 . The final output directory is
5889 SDK_DEPLOY
5890 .
5891
5892 SDK_PACKAGE_ARCHS
5893 Specifies a list of architectures compatible with the SDK machine.
5894 This variable is set automatically and should not normally be
5895 hand-edited. Entries are separated using spaces and listed in order
5896 of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any
5897 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
5898
5899 SDK_POSTPROCESS_COMMAND
5900 Specifies a list of functions to call once the OpenEmbedded build
5901 system creates the SDK. You can specify functions separated by
5902 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... "
5903
5904 If you need to pass an SDK path to a command within a function, you
5905 can use ``${SDK_DIR}``, which points to the parent directory used by
5906 the OpenEmbedded build system when creating SDK output. See the
5907 :term:`SDK_DIR` variable for more information.
5908
5909 SDK_PREFIX
5910 The toolchain binary prefix used for ``nativesdk`` recipes. The
5911 OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the
5912 :term:`TARGET_PREFIX` when building
5913 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
5914
5915 SDK_RECRDEP_TASKS
5916 A list of shared state tasks added to the extensible SDK. By default,
5917 the following tasks are added: do_populate_lic do_package_qa
5918 do_populate_sysroot do_deploy Despite the default value of "" for the
5919 ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added
5920 to the SDK. To specify tasks beyond these four, you need to use the
5921 ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional
5922 tasks that are needed in order to build
5923 :term:`SDK_TARGETS`).
5924
5925 SDK_SYS
5926 Specifies the system, including the architecture and the operating
5927 system, for which the SDK will be built.
5928
5929 The OpenEmbedded build system automatically sets this variable based
5930 on :term:`SDK_ARCH`,
5931 :term:`SDK_VENDOR`, and
5932 :term:`SDK_OS`. You do not need to set the ``SDK_SYS``
7005 variable yourself. 5933 variable yourself.
7006 5934
7007 Consider these two examples: 5935 SDK_TARGET_MANIFEST
7008 5936 The manifest file for the target part of the SDK. This file lists all
7009 - Given a native recipe on a 32-bit, x86 machine running Linux, the 5937 the installed packages that make up the target part of the SDK. The
7010 value is "i686-linux". 5938 file contains package information on a line-per-package basis as
7011 5939 follows: packagename packagearch version
7012 - Given a recipe being built for a little-endian, MIPS target 5940
7013 running Linux, the value might be "mipsel-linux". 5941 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
7014 5942 defines the manifest file as follows: SDK_TARGET_MANIFEST =
7015TARGET_VENDOR 5943 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" The location
7016 Specifies the name of the target vendor. 5944 is derived using the :term:`SDK_DEPLOY` and
7017 5945 :term:`TOOLCHAIN_OUTPUTNAME` variables.
7018TCLIBC 5946
7019 Specifies the GNU standard C library (``libc``) variant to use during 5947 SDK_TARGETS
7020 the build process. This variable replaces ``POKYLIBC``, which is no 5948 A list of targets to install from shared state as part of the
7021 longer supported. 5949 standard or extensible SDK installation. The default value is "${PN}"
7022 5950 (i.e. the image from which the SDK is built).
7023 You can select "glibc", "musl", "newlib", or "baremetal" 5951
7024 5952 The ``SDK_TARGETS`` variable is an internal variable and typically
7025TCLIBCAPPEND 5953 would not be changed.
7026 Specifies a suffix to be appended onto the 5954
7027 ```TMPDIR`` <#var-TMPDIR>`__ value. The suffix identifies the 5955 SDK_TITLE
7028 ``libc`` variant for building. When you are building for multiple 5956 The title to be printed when running the SDK installer. By default,
7029 variants with the same `Build Directory <#build-directory>`__, this 5957 this title is based on the :term:`DISTRO_NAME` or
7030 mechanism ensures that output for different ``libc`` variants is kept 5958 :term:`DISTRO` variable and is set in the
7031 separate to avoid potential conflicts. 5959 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
7032 5960 follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or
7033 In the ``defaultsetup.conf`` file, the default value of 5961 d.getVar('DISTRO')} SDK" For the default distribution "poky",
7034 ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, 5962 ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)".
7035 which normally only support one ``libc`` variant, set 5963
7036 ``TCLIBCAPPEND`` to "" in their distro configuration file resulting 5964 For information on how to change this default title, see the
7037 in no suffix being applied. 5965 "`Changing the Extensible SDK Installer
7038 5966 Title <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title>`__"
7039TCMODE 5967 section in the Yocto Project Application Development and the
7040 Specifies the toolchain selector. ``TCMODE`` controls the 5968 Extensible Software Development Kit (eSDK) manual.
7041 characteristics of the generated packages and images by telling the 5969
7042 OpenEmbedded build system which toolchain profile to use. By default, 5970 SDK_UPDATE_URL
7043 the OpenEmbedded build system builds its own internal toolchain. The 5971 An optional URL for an update server for the extensible SDK. If set,
7044 variable's default value is "default", which uses that internal 5972 the value is used as the default update server when running
7045 toolchain. 5973 ``devtool sdk-update`` within the extensible SDK.
7046 5974
7047 .. note:: 5975 SDK_VENDOR
7048 5976 Specifies the name of the SDK vendor.
7049 If 5977
7050 TCMODE 5978 SDK_VERSION
7051 is set to a value other than "default", then it is your 5979 Specifies the version of the SDK. The distribution configuration file
7052 responsibility to ensure that the toolchain is compatible with the 5980 (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the
7053 default toolchain. Using older or newer versions of these 5981 ``SDK_VERSION`` as follows: SDK_VERSION =
7054 components might cause build problems. See the Release Notes for 5982 "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
7055 the Yocto Project release for the specific components with which 5983
7056 the toolchain must be compatible. To access the Release Notes, go 5984 For additional information, see the
7057 to the 5985 :term:`DISTRO_VERSION` and
7058 Downloads 5986 :term:`DATE` variables.
7059 page on the Yocto Project website and click on the "RELEASE 5987
7060 INFORMATION" link for the appropriate release. 5988 SDKEXTPATH
7061 5989 The default installation directory for the Extensible SDK. By
7062 The ``TCMODE`` variable is similar to ```TCLIBC`` <#var-TCLIBC>`__, 5990 default, this directory is based on the :term:`DISTRO`
7063 which controls the variant of the GNU standard C library (``libc``) 5991 variable and is set in the
7064 used during the build process: ``glibc`` or ``musl``. 5992 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
7065 5993 follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" For the
7066 With additional layers, it is possible to use a pre-compiled external 5994 default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk".
7067 toolchain. One example is the Sourcery G++ Toolchain. The support for 5995
7068 this toolchain resides in the separate Mentor Graphics 5996 For information on how to change this default directory, see the
7069 ``meta-sourcery`` layer at 5997 "`Changing the Default SDK Installation
7070 ` <http://github.com/MentorEmbedded/meta-sourcery/>`__. 5998 Directory <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory>`__"
7071 5999 section in the Yocto Project Application Development and the
7072 The layer's ``README`` file contains information on how to use the 6000 Extensible Software Development Kit (eSDK) manual.
7073 Sourcery G++ Toolchain as an external toolchain. In summary, you must 6001
7074 be sure to add the layer to your ``bblayers.conf`` file in front of 6002 SDKIMAGE_FEATURES
7075 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable 6003 Equivalent to ``IMAGE_FEATURES``. However, this variable applies to
7076 in your ``local.conf`` file to the location in which you installed 6004 the SDK generated from an image using the following command: $
7077 the toolchain. 6005 bitbake -c populate_sdk imagename
7078 6006
7079 The fundamentals used for this example apply to any external 6007 SDKMACHINE
7080 toolchain. You can use ``meta-sourcery`` as a template for adding 6008 The machine for which the SDK is built. In other words, the SDK is
7081 support for other external toolchains. 6009 built such that it runs on the target you specify with the
7082 6010 ``SDKMACHINE`` value. The value points to a corresponding ``.conf``
7083TEST_EXPORT_DIR 6011 file under ``conf/machine-sdk/``.
7084 The location the OpenEmbedded build system uses to export tests when 6012
7085 the ```TEST_EXPORT_ONLY`` <#var-TEST_EXPORT_ONLY>`__ variable is set 6013 You can use "i686" and "x86_64" as possible values for this variable.
7086 to "1". 6014 The variable defaults to "i686" and is set in the local.conf file in
7087 6015 the Build Directory. SDKMACHINE ?= "i686"
7088 The ``TEST_EXPORT_DIR`` variable defaults to 6016
7089 ``"${TMPDIR}/testimage/${PN}"``. 6017 .. note::
7090 6018
7091TEST_EXPORT_ONLY 6019 You cannot set the
7092 Specifies to export the tests only. Set this variable to "1" if you 6020 SDKMACHINE
7093 do not want to run the tests but you want them to be exported in a 6021 variable in your distribution configuration file. If you do, the
7094 manner that you to run them outside of the build system. 6022 configuration will not take affect.
7095 6023
7096TEST_LOG_DIR 6024 SDKPATH
7097 Holds the SSH log and the boot log for QEMU machines. The 6025 Defines the path offered to the user for installation of the SDK that
7098 ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. 6026 is generated by the OpenEmbedded build system. The path appears as
7099 6027 the default location for installing the SDK when you run the SDK's
7100 .. note:: 6028 installation script. You can override the offered path when you run
7101 6029 the script.
7102 Actual test results reside in the task log ( 6030
7103 log.do_testimage 6031 SDKTARGETSYSROOT
7104 ), which is in the 6032 The full path to the sysroot used for cross-compilation within an SDK
7105 ${WORKDIR}/temp/ 6033 as it will be when installed into the default
7106 directory. 6034 :term:`SDKPATH`.
7107 6035
7108TEST_POWERCONTROL_CMD 6036 SECTION
7109 For automated hardware testing, specifies the command to use to 6037 The section in which packages should be categorized. Package
7110 control the power of the target machine under test. Typically, this 6038 management utilities can make use of this variable.
7111 command would point to a script that performs the appropriate action 6039
7112 (e.g. interacting with a web-enabled power strip). The specified 6040 SELECTED_OPTIMIZATION
7113 command should expect to receive as the last argument "off", "on" or 6041 Specifies the optimization flags passed to the C compiler when
7114 "cycle" specifying to power off, on, or cycle (power off and then 6042 building for the target. The flags are passed through the default
7115 power on) the device, respectively. 6043 value of the :term:`TARGET_CFLAGS` variable.
7116 6044
7117TEST_POWERCONTROL_EXTRA_ARGS 6045 The ``SELECTED_OPTIMIZATION`` variable takes the value of
7118 For automated hardware testing, specifies additional arguments to 6046 ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the
7119 pass through to the command specified in 6047 case, the value of ``DEBUG_OPTIMIZATION`` is used.
7120 ```TEST_POWERCONTROL_CMD`` <#var-TEST_POWERCONTROL_CMD>`__. Setting 6048
7121 ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you 6049 SERIAL_CONSOLE
7122 wish, for example, to separate the machine-specific and 6050 Defines a serial console (TTY) to enable using
7123 non-machine-specific parts of the arguments. 6051 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
7124 6052 value that specifies the baud rate followed by the TTY device name
7125TEST_QEMUBOOT_TIMEOUT 6053 separated by a space. You cannot specify more than one TTY device:
7126 The time in seconds allowed for an image to boot before automated 6054 SERIAL_CONSOLE = "115200 ttyS0"
7127 runtime tests begin to run against an image. The default timeout 6055
7128 period to allow the boot process to reach the login prompt is 500 6056 .. note::
7129 seconds. You can specify a different value in the ``local.conf`` 6057
7130 file. 6058 The
7131 6059 SERIAL_CONSOLE
7132 For more information on testing images, see the "`Performing 6060 variable is deprecated. Please use the
7133 Automated Runtime 6061 SERIAL_CONSOLES
7134 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" 6062 variable.
7135 section in the Yocto Project Development Tasks Manual. 6063
7136 6064 SERIAL_CONSOLES
7137TEST_SERIALCONTROL_CMD 6065 Defines a serial console (TTY) to enable using
7138 For automated hardware testing, specifies the command to use to 6066 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
7139 connect to the serial console of the target machine under test. This 6067 value that specifies the baud rate followed by the TTY device name
7140 command simply needs to connect to the serial console and forward 6068 separated by a semicolon. Use spaces to separate multiple devices:
7141 that connection to standard input and output as any normal terminal 6069 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
7142 program does. 6070
7143 6071 SERIAL_CONSOLES_CHECK
7144 For example, to use the Picocom terminal program on serial device 6072 Specifies serial consoles, which must be listed in
7145 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: 6073 :term:`SERIAL_CONSOLES`, to check against
7146 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 6074 ``/proc/console`` before enabling them using getty. This variable
7147 6075 allows aliasing in the format: <device>:<alias>. If a device was
7148TEST_SERIALCONTROL_EXTRA_ARGS 6076 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in
7149 For automated hardware testing, specifies additional arguments to 6077 ``/proc/console``, you would do the following: SERIAL_CONSOLES_CHECK
7150 pass through to the command specified in 6078 = "slcp_line0:ttyS0" This variable is currently only supported with
7151 ```TEST_SERIALCONTROL_CMD`` <#var-TEST_SERIALCONTROL_CMD>`__. Setting 6079 SysVinit (i.e. not with systemd).
7152 ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you 6080
7153 wish, for example, to separate the machine-specific and 6081 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS
7154 non-machine-specific parts of the command. 6082 A list of recipe dependencies that should not be used to determine
7155 6083 signatures of tasks from one recipe when they depend on tasks from
7156TEST_SERVER_IP 6084 another recipe. For example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS +=
7157 The IP address of the build machine (host machine). This IP address 6085 "intone->mplayer2"
7158 is usually automatically detected. However, if detection fails, this 6086
7159 variable needs to be set to the IP address of the build machine (i.e. 6087 In the previous example, ``intone`` depends on ``mplayer2``.
7160 where the build is taking place). 6088
7161 6089 You can use the special token ``"*"`` on the left-hand side of the
7162 .. note:: 6090 dependency to match all recipes except the one on the right-hand
7163 6091 side. Here is an example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS +=
7164 The 6092 "*->quilt-native"
7165 TEST_SERVER_IP 6093
7166 variable is only used for a small number of tests such as the 6094 In the previous example, all recipes except ``quilt-native`` ignore
7167 "dnf" test suite, which needs to download packages from 6095 task signatures from the ``quilt-native`` recipe when determining
7168 WORKDIR/oe-rootfs-repo 6096 their task signatures.
7169 . 6097
7170 6098 Use of this variable is one mechanism to remove dependencies that
7171TEST_TARGET 6099 affect task signatures and thus force rebuilds when a recipe changes.
7172 Specifies the target controller to use when running tests against a 6100
7173 test image. The default controller to use is "qemu": TEST_TARGET = 6101 .. note::
7174 "qemu" 6102
7175 6103 If you add an inappropriate dependency for a recipe relationship,
7176 A target controller is a class that defines how an image gets 6104 the software might break during runtime if the interface of the
7177 deployed on a target and how a target is started. A layer can extend 6105 second recipe was changed after the first recipe had been built.
7178 the controllers by adding a module in the layer's 6106
7179 ``/lib/oeqa/controllers`` directory and by inheriting the 6107 SIGGEN_EXCLUDERECIPES_ABISAFE
7180 ``BaseTarget`` class, which is an abstract class that cannot be used 6108 A list of recipes that are completely stable and will never change.
7181 as a value of ``TEST_TARGET``. 6109 The ABI for the recipes in the list are presented by output from the
7182 6110 tasks run to build the recipe. Use of this variable is one way to
7183 You can provide the following arguments with ``TEST_TARGET``: 6111 remove dependencies from one recipe on another that affect task
7184 6112 signatures and thus force rebuilds when the recipe changes.
7185 - *"qemu":* Boots a QEMU image and runs the tests. See the 6113
7186 "`Enabling Runtime Tests on 6114 .. note::
7187 QEMU <&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests>`__" section 6115
7188 in the Yocto Project Development Tasks Manual for more 6116 If you add an inappropriate variable to this list, the software
6117 might break at runtime if the interface of the recipe was changed
6118 after the other had been built.
6119
6120 SITEINFO_BITS
6121 Specifies the number of bits for the target system CPU. The value
6122 should be either "32" or "64".
6123
6124 SITEINFO_ENDIANNESS
6125 Specifies the endian byte order of the target system. The value
6126 should be either "le" for little-endian or "be" for big-endian.
6127
6128 SKIP_FILEDEPS
6129 Enables removal of all files from the "Provides" section of an RPM
6130 package. Removal of these files is required for packages containing
6131 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
6132
6133 To enable file removal, set the variable to "1" in your
6134 ``conf/local.conf`` configuration file in your:
6135 :term:`Build Directory`. SKIP_FILEDEPS = "1"
6136
6137 SOC_FAMILY
6138 Groups together machines based upon the same family of SOC (System On
6139 Chip). You typically set this variable in a common ``.inc`` file that
6140 you include in the configuration files of all the machines.
6141
6142 .. note::
6143
6144 You must include
6145 conf/machine/include/soc-family.inc
6146 for this variable to appear in
6147 MACHINEOVERRIDES
6148 .
6149
6150 SOLIBS
6151 Defines the suffix for shared libraries used on the target platform.
6152 By default, this suffix is ".so.*" for all Linux-based systems and is
6153 defined in the ``meta/conf/bitbake.conf`` configuration file.
6154
6155 You will see this variable referenced in the default values of
6156 ``FILES_${PN}``.
6157
6158 SOLIBSDEV
6159 Defines the suffix for the development symbolic link (symlink) for
6160 shared libraries on the target platform. By default, this suffix is
6161 ".so" for Linux-based systems and is defined in the
6162 ``meta/conf/bitbake.conf`` configuration file.
6163
6164 You will see this variable referenced in the default values of
6165 ``FILES_${PN}-dev``.
6166
6167 SOURCE_MIRROR_FETCH
6168 When you are fetching files to create a mirror of sources (i.e.
6169 creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in
6170 your ``local.conf`` configuration file ensures the source for all
6171 recipes are fetched regardless of whether or not a recipe is
6172 compatible with the configuration. A recipe is considered
6173 incompatible with the currently configured machine when either or
6174 both the :term:`COMPATIBLE_MACHINE`
6175 variable and :term:`COMPATIBLE_HOST` variables
6176 specify compatibility with a machine other than that of the current
6177 machine or host.
6178
6179 .. note::
6180
6181 Do not set the
6182 SOURCE_MIRROR_FETCH
6183 variable unless you are creating a source mirror. In other words,
6184 do not set the variable during a normal build.
6185
6186 SOURCE_MIRROR_URL
6187 Defines your own :term:`PREMIRRORS` from which to
6188 first fetch source before attempting to fetch from the upstream
6189 specified in :term:`SRC_URI`.
6190
6191 To use this variable, you must globally inherit the
6192 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide
6193 the URL to your mirrors. Here is the general syntax: INHERIT +=
6194 "own-mirrors" SOURCE_MIRROR_URL =
6195 "http://example.com/my_source_mirror"
6196
6197 .. note::
6198
6199 You can specify only a single URL in
6200 SOURCE_MIRROR_URL
6201 .
6202
6203 SPDXLICENSEMAP
6204 Maps commonly used license names to their SPDX counterparts found in
6205 ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP``
6206 mappings, see the ``meta/conf/licenses.conf`` file.
6207
6208 For additional information, see the :term:`LICENSE`
6209 variable.
6210
6211 SPECIAL_PKGSUFFIX
6212 A list of prefixes for :term:`PN` used by the OpenEmbedded
6213 build system to create variants of recipes or packages. The list
6214 specifies the prefixes to strip off during certain circumstances such
6215 as the generation of the :term:`BPN` variable.
6216
6217 SPL_BINARY
6218 The file type for the Secondary Program Loader (SPL). Some devices
6219 use an SPL from which to boot (e.g. the BeagleBone development
6220 board). For such cases, you can declare the file type of the SPL
6221 binary in the ``u-boot.inc`` include file, which is used in the
6222 U-Boot recipe.
6223
6224 The SPL file type is set to "null" by default in the ``u-boot.inc``
6225 file as follows: # Some versions of u-boot build an SPL (Second
6226 Program Loader) image that # should be packaged along with the u-boot
6227 binary as well as placed in the # deploy directory. For those
6228 versions they can set the following variables # to allow packaging
6229 the SPL. SPL_BINARY ?= "" SPL_BINARYNAME ?=
6230 "${@os.path.basename(d.getVar("SPL_BINARY"))}" SPL_IMAGE ?=
6231 "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" SPL_SYMLINK ?=
6232 "${SPL_BINARYNAME}-${MACHINE}" The ``SPL_BINARY`` variable helps form
6233 various ``SPL_*`` variables used by the OpenEmbedded build system.
6234
6235 See the BeagleBone machine configuration example in the "`Creating a
6236 new BSP Layer Using the ``bitbake-layers``
6237 Script <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__"
6238 section in the Yocto Project Board Support Package Developer's Guide
6239 for additional information.
6240
6241 SRC_URI
6242 The list of source files - local or remote. This variable tells the
6243 OpenEmbedded build system which bits to pull in for the build and how
6244 to pull them in. For example, if the recipe or append file only needs
6245 to fetch a tarball from the Internet, the recipe or append file uses
6246 a single ``SRC_URI`` entry. On the other hand, if the recipe or
6247 append file needs to fetch a tarball, apply two patches, and include
6248 a custom file, the recipe or append file would include four instances
6249 of the variable.
6250
6251 The following list explains the available URI protocols. URI
6252 protocols are highly dependent on particular BitBake Fetcher
6253 submodules. Depending on the fetcher BitBake uses, various URL
6254 parameters are employed. For specifics on the supported Fetchers, see
6255 the ":ref:`Fetchers <bitbake:bb-fetchers>`" section in the
6256 BitBake User Manual.
6257
6258 - *``file://`` -* Fetches files, which are usually files shipped
6259 with the :term:`Metadata`, from the local machine (e.g.
6260 `patch <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__ files).
6261 The path is relative to the :term:`FILESPATH`
6262 variable. Thus, the build system searches, in order, from the
6263 following directories, which are assumed to be a subdirectories of
6264 the directory in which the recipe file (``.bb``) or append file
6265 (``.bbappend``) resides:
6266
6267 - *``${BPN}`` -* The base recipe name without any special suffix
6268 or version numbers.
6269
6270 - *``${BP}`` -* ``${BPN}-${PV}``. The base recipe name and
6271 version but without any special package name suffix.
6272
6273 - *files -* Files within a directory, which is named ``files``
6274 and is also alongside the recipe or append file.
6275
6276 .. note::
6277
6278 If you want the build system to pick up files specified through
6279 a
6280 SRC_URI
6281 statement from your append file, you need to be sure to extend
6282 the
6283 FILESPATH
6284 variable by also using the
6285 FILESEXTRAPATHS
6286 variable from within your append file.
6287
6288 - *``bzr://`` -* Fetches files from a Bazaar revision control
6289 repository.
6290
6291 - *``git://`` -* Fetches files from a Git revision control
6292 repository.
6293
6294 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service)
6295 revision control repository.
6296
6297 - *``repo://`` -* Fetches files from a repo (Git) repository.
6298
6299 - *``ccrc://`` -* Fetches files from a ClearCase repository.
6300
6301 - *``http://`` -* Fetches files from the Internet using ``http``.
6302
6303 - *``https://`` -* Fetches files from the Internet using ``https``.
6304
6305 - *``ftp://`` -* Fetches files from the Internet using ``ftp``.
6306
6307 - *``cvs://`` -* Fetches files from a CVS revision control
6308 repository.
6309
6310 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision
6311 control repository.
6312
6313 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision
6314 control repository.
6315
6316 - *``ssh://`` -* Fetches files from a secure shell.
6317
6318 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision
6319 control repository.
6320
6321 - *``npm://`` -* Fetches JavaScript modules from a registry.
6322
6323 Standard and recipe-specific options for ``SRC_URI`` exist. Here are
6324 standard options:
6325
6326 - *``apply`` -* Whether to apply the patch or not. The default
6327 action is to apply the patch.
6328
6329 - *``striplevel`` -* Which striplevel to use when applying the
6330 patch. The default level is 1.
6331
6332 - *``patchdir`` -* Specifies the directory in which the patch should
6333 be applied. The default is ``${``\ :term:`S`\ ``}``.
6334
6335 Here are options specific to recipes building code from a revision
6336 control system:
6337
6338 - *``mindate`` -* Apply the patch only if
6339 :term:`SRCDATE` is equal to or greater than
6340 ``mindate``.
6341
6342 - *``maxdate`` -* Apply the patch only if ``SRCDATE`` is not later
6343 than ``maxdate``.
6344
6345 - *``minrev`` -* Apply the patch only if ``SRCREV`` is equal to or
6346 greater than ``minrev``.
6347
6348 - *``maxrev`` -* Apply the patch only if ``SRCREV`` is not later
6349 than ``maxrev``.
6350
6351 - *``rev`` -* Apply the patch only if ``SRCREV`` is equal to
6352 ``rev``.
6353
6354 - *``notrev`` -* Apply the patch only if ``SRCREV`` is not equal to
6355 ``rev``.
6356
6357 Here are some additional options worth mentioning:
6358
6359 - *``unpack`` -* Controls whether or not to unpack the file if it is
6360 an archive. The default action is to unpack the file.
6361
6362 - *``destsuffix`` -* Places the file (or extracts its contents) into
6363 the specified subdirectory of :term:`WORKDIR` when
6364 the Git fetcher is used.
6365
6366 - *``subdir`` -* Places the file (or extracts its contents) into the
6367 specified subdirectory of ``WORKDIR`` when the local (``file://``)
6368 fetcher is used.
6369
6370 - *``localdir`` -* Places the file (or extracts its contents) into
6371 the specified subdirectory of ``WORKDIR`` when the CVS fetcher is
6372 used.
6373
6374 - *``subpath`` -* Limits the checkout to a specific subpath of the
6375 tree when using the Git fetcher is used.
6376
6377 - *``name`` -* Specifies a name to be used for association with
6378 ``SRC_URI`` checksums when you have more than one file specified
6379 in ``SRC_URI``.
6380
6381 - *``downloadfilename`` -* Specifies the filename used when storing
6382 the downloaded file.
6383
6384 SRC_URI_OVERRIDES_PACKAGE_ARCH
6385 By default, the OpenEmbedded build system automatically detects
6386 whether ``SRC_URI`` contains files that are machine-specific. If so,
6387 the build system automatically changes ``PACKAGE_ARCH``. Setting this
6388 variable to "0" disables this behavior.
6389
6390 SRCDATE
6391 The date of the source code used to build the package. This variable
6392 applies only if the source was fetched from a Source Code Manager
6393 (SCM).
6394
6395 SRCPV
6396 Returns the version string of the current package. This string is
6397 used to help define the value of :term:`PV`.
6398
6399 The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf``
6400 configuration file in the :term:`Source Directory` as
6401 follows: SRCPV = "${@bb.fetch2.get_srcrev(d)}"
6402
6403 Recipes that need to define ``PV`` do so with the help of the
6404 ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``)
6405 located in ``meta/recipes-connectivity`` in the Source Directory
6406 defines ``PV`` as follows: PV = "0.12-git${SRCPV}"
6407
6408 SRCREV
6409 The revision of the source code used to build the package. This
6410 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
6411 that if you want to build a fixed revision and you want to avoid
6412 performing a query on the remote repository every time BitBake parses
6413 your recipe, you should specify a ``SRCREV`` that is a full revision
6414 identifier and not just a tag.
6415
6416 .. note::
6417
6418 For information on limitations when inheriting the latest revision
6419 of software using
6420 SRCREV
6421 , see the
6422 AUTOREV
6423 variable description and the "
6424 Automatically Incrementing a Binary Package Revision Number
6425 " section, which is in the Yocto Project Development Tasks Manual.
6426
6427 SSTATE_DIR
6428 The directory for the shared state cache.
6429
6430 SSTATE_MIRROR_ALLOW_NETWORK
6431 If set to "1", allows fetches from mirrors that are specified in
6432 :term:`SSTATE_MIRRORS` to work even when
6433 fetching from the network is disabled by setting ``BB_NO_NETWORK`` to
6434 "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if
6435 you have set ``SSTATE_MIRRORS`` to point to an internal server for
6436 your shared state cache, but you want to disable any other fetching
6437 from the network.
6438
6439 SSTATE_MIRRORS
6440 Configures the OpenEmbedded build system to search other mirror
6441 locations for prebuilt cache data objects before building out the
6442 data. This variable works like fetcher :term:`MIRRORS`
6443 and :term:`PREMIRRORS` and points to the cache
6444 locations to check for the shared state (sstate) objects.
6445
6446 You can specify a filesystem directory or a remote URL such as HTTP
6447 or FTP. The locations you specify need to contain the shared state
6448 cache (sstate-cache) results from previous builds. The sstate-cache
6449 you point to can also be from builds on other machines.
6450
6451 When pointing to sstate build artifacts on another machine that uses
6452 a different GCC version for native builds, you must configure
6453 ``SSTATE_MIRRORS`` with a regular expression that maps local search
6454 paths to server paths. The paths need to take into account
6455 :term:`NATIVELSBSTRING` set by the
6456 :ref:`uninative <ref-classes-uninative>` class. For example, the
6457 following maps the local search path ``universal-4.9`` to the
6458 server-provided path server_url_sstate_path: SSTATE_MIRRORS ?=
6459 file://universal-4.9/(.*)
6460 http://server_url_sstate_path/universal-4.8/\1 \\n
6461
6462 If a mirror uses the same structure as
6463 :term:`SSTATE_DIR`, you need to add "PATH" at the
6464 end as shown in the examples below. The build system substitutes the
6465 correct path within the directory structure. SSTATE_MIRRORS ?= "\\
6466 file://.\*
6467 http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\
6468 file://.\* file:///some-local-dir/sstate/PATH"
6469
6470 SSTATE_SCAN_FILES
6471 Controls the list of files the OpenEmbedded build system scans for
6472 hardcoded installation paths. The variable uses a space-separated
6473 list of filenames (not paths) with standard wildcard characters
6474 allowed.
6475
6476 During a build, the OpenEmbedded build system creates a shared state
6477 (sstate) object during the first stage of preparing the sysroots.
6478 That object is scanned for hardcoded paths for original installation
6479 locations. The list of files that are scanned for paths is controlled
6480 by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files
6481 they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather
6482 than the variable being comprehensively set. The
6483 :ref:`sstate <ref-classes-sstate>` class specifies the default list
6484 of files.
6485
6486 For details on the process, see the
6487 :ref:`staging <ref-classes-staging>` class.
6488
6489 STAGING_BASE_LIBDIR_NATIVE
6490 Specifies the path to the ``/lib`` subdirectory of the sysroot
6491 directory for the build host.
6492
6493 STAGING_BASELIBDIR
6494 Specifies the path to the ``/lib`` subdirectory of the sysroot
6495 directory for the target for which the current recipe is being built
6496 (:term:`STAGING_DIR_HOST`).
6497
6498 STAGING_BINDIR
6499 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6500 directory for the target for which the current recipe is being built
6501 (:term:`STAGING_DIR_HOST`).
6502
6503 STAGING_BINDIR_CROSS
6504 Specifies the path to the directory containing binary configuration
6505 scripts. These scripts provide configuration information for other
6506 software that wants to make use of libraries or include files
6507 provided by the software associated with the script.
6508
6509 .. note::
6510
6511 This style of build configuration has been largely replaced by
6512 pkg-config
6513 . Consequently, if
6514 pkg-config
6515 is supported by the library to which you are linking, it is
6516 recommended you use
6517 pkg-config
6518 instead of a provided configuration script.
6519
6520 STAGING_BINDIR_NATIVE
6521 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6522 directory for the build host.
6523
6524 STAGING_DATADIR
6525 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6526 directory for the target for which the current recipe is being built
6527 (:term:`STAGING_DIR_HOST`).
6528
6529 STAGING_DATADIR_NATIVE
6530 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6531 directory for the build host.
6532
6533 STAGING_DIR
6534 Helps construct the ``recipe-sysroots`` directory, which is used
6535 during packaging.
6536
6537 For information on how staging for recipe-specific sysroots occurs,
6538 see the :ref:`ref-tasks-populate_sysroot`
6539 task, the "`Sharing Files Between
6540 Recipes <&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes>`__"
6541 section in the Yocto Project Development Tasks Manual, the
6542 "`Configuration, Compilation, and
6543 Staging <&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment>`__"
6544 section in the Yocto Project Overview and Concepts Manual, and the
6545 :term:`SYSROOT_DIRS` variable.
6546
6547 .. note::
6548
6549 Recipes should never write files directly under the
6550 STAGING_DIR
6551 directory because the OpenEmbedded build system manages the
6552 directory automatically. Instead, files should be installed to
6553 ${
6554 D
6555 }
6556 within your recipe's
6557 do_install
6558 task and then the OpenEmbedded build system will stage a subset of
6559 those files into the sysroot.
6560
6561 STAGING_DIR_HOST
6562 Specifies the path to the sysroot directory for the system on which
6563 the component is built to run (the system that hosts the component).
6564 For most recipes, this sysroot is the one in which that recipe's
6565 :ref:`ref-tasks-populate_sysroot` task copies
6566 files. Exceptions include ``-native`` recipes, where the
6567 ``do_populate_sysroot`` task instead uses
6568 :term:`STAGING_DIR_NATIVE`. Depending on
6569 the type of recipe and the build target, ``STAGING_DIR_HOST`` can
6570 have the following values:
6571
6572 - For recipes building for the target machine, the value is
6573 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
6574
6575 - For native recipes building for the build host, the value is empty
6576 given the assumption that when building for the build host, the
6577 build host's own directories should be used.
6578
6579 .. note::
6580
6581 ``-native`` recipes are not installed into host paths like such
6582 as ``/usr``. Rather, these recipes are installed into
6583 ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes,
6584 standard build environment variables such as
6585 :term:`CPPFLAGS` and
6586 :term:`CFLAGS` are set up so that both host paths
6587 and ``STAGING_DIR_NATIVE`` are searched for libraries and
6588 headers using, for example, GCC's ``-isystem`` option.
6589
6590 Thus, the emphasis is that the ``STAGING_DIR*`` variables
6591 should be viewed as input variables by tasks such as
6592 :ref:`ref-tasks-configure`,
6593 :ref:`ref-tasks-compile`, and
6594 :ref:`ref-tasks-install`. Having the real system
6595 root correspond to ``STAGING_DIR_HOST`` makes conceptual sense
6596 for ``-native`` recipes, as they make use of host headers and
6597 libraries.
6598
6599 STAGING_DIR_NATIVE
6600 Specifies the path to the sysroot directory used when building
6601 components that run on the build host itself.
6602
6603 STAGING_DIR_TARGET
6604 Specifies the path to the sysroot used for the system for which the
6605 component generates code. For components that do not generate code,
6606 which is the majority, ``STAGING_DIR_TARGET`` is set to match
6607 :term:`STAGING_DIR_HOST`.
6608
6609 Some recipes build binaries that can run on the target system but
6610 those binaries in turn generate code for another different system
6611 (e.g. cross-canadian recipes). Using terminology from GNU, the
6612 primary system is referred to as the "HOST" and the secondary, or
6613 different, system is referred to as the "TARGET". Thus, the binaries
6614 run on the "HOST" system and generate binaries for the "TARGET"
6615 system. The ``STAGING_DIR_HOST`` variable points to the sysroot used
6616 for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the
6617 sysroot used for the "TARGET" system.
6618
6619 STAGING_ETCDIR_NATIVE
6620 Specifies the path to the ``/etc`` subdirectory of the sysroot
6621 directory for the build host.
6622
6623 STAGING_EXECPREFIXDIR
6624 Specifies the path to the ``/usr`` subdirectory of the sysroot
6625 directory for the target for which the current recipe is being built
6626 (:term:`STAGING_DIR_HOST`).
6627
6628 STAGING_INCDIR
6629 Specifies the path to the ``/usr/include`` subdirectory of the
6630 sysroot directory for the target for which the current recipe being
6631 built (:term:`STAGING_DIR_HOST`).
6632
6633 STAGING_INCDIR_NATIVE
6634 Specifies the path to the ``/usr/include`` subdirectory of the
6635 sysroot directory for the build host.
6636
6637 STAGING_KERNEL_BUILDDIR
6638 Points to the directory containing the kernel build artifacts.
6639 Recipes building software that needs to access kernel build artifacts
6640 (e.g. ``systemtap-uprobes``) can look in the directory specified with
6641 the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts
6642 after the kernel has been built.
6643
6644 STAGING_KERNEL_DIR
6645 The directory with kernel headers that are required to build
6646 out-of-tree modules.
6647
6648 STAGING_LIBDIR
6649 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
6650 directory for the target for which the current recipe is being built
6651 (:term:`STAGING_DIR_HOST`).
6652
6653 STAGING_LIBDIR_NATIVE
6654 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
6655 directory for the build host.
6656
6657 STAMP
6658 Specifies the base path used to create recipe stamp files. The path
6659 to an actual stamp file is constructed by evaluating this string and
6660 then appending additional information. Currently, the default
6661 assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf``
6662 file is: STAMP =
6663 "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
6664
6665 For information on how BitBake uses stamp files to determine if a
6666 task should be rerun, see the "`Stamp Files and the Rerunning of
6667 Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__"
6668 section in the Yocto Project Overview and Concepts Manual.
6669
6670 See :term:`STAMPS_DIR`,
6671 :term:`MULTIMACH_TARGET_SYS`,
6672 :term:`PN`, :term:`EXTENDPE`,
6673 :term:`PV`, and :term:`PR` for related variable
7189 information. 6674 information.
7190 6675
7191 - *"simpleremote":* Runs the tests on target hardware that is 6676 STAMPS_DIR
7192 already up and running. The hardware can be on the network or it 6677 Specifies the base directory in which the OpenEmbedded build system
7193 can be a device running an image on QEMU. You must also set 6678 places stamps. The default directory is ``${TMPDIR}/stamps``.
7194 ```TEST_TARGET_IP`` <#var-TEST_TARGET_IP>`__ when you use 6679
7195 "simpleremote". 6680 STRIP
7196 6681 The minimal command and arguments to run ``strip``, which is used to
6682 strip symbols.
6683
6684 SUMMARY
6685 The short (72 characters or less) summary of the binary package for
6686 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
6687 ``SUMMARY`` is used to define the
6688 :term:`DESCRIPTION` variable if ``DESCRIPTION`` is
6689 not set in the recipe.
6690
6691 SVNDIR
6692 The directory in which files checked out of a Subversion system are
6693 stored.
6694
6695 SYSLINUX_DEFAULT_CONSOLE
6696 Specifies the kernel boot default console. If you want to use a
6697 console other than the default, set this variable in your recipe as
6698 follows where "X" is the console number you want to use:
6699 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
6700
6701 The :ref:`syslinux <ref-classes-syslinux>` class initially sets
6702 this variable to null but then checks for a value later.
6703
6704 SYSLINUX_OPTS
6705 Lists additional options to add to the syslinux file. You need to set
6706 this variable in your recipe. If you want to list multiple options,
6707 separate the options with a semicolon character (``;``).
6708
6709 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable
6710 to create a set of options.
6711
6712 SYSLINUX_SERIAL
6713 Specifies the alternate serial port or turns it off. To turn off
6714 serial, set this variable to an empty string in your recipe. The
6715 variable's default value is set in the
6716 :ref:`syslinux <ref-classes-syslinux>` class as follows:
6717 SYSLINUX_SERIAL ?= "0 115200"
6718
6719 The class checks for and uses the variable as needed.
6720
6721 SYSLINUX_SPLASH
6722 An ``.LSS`` file used as the background for the VGA boot menu when
6723 you use the boot menu. You need to set this variable in your recipe.
6724
6725 The :ref:`syslinux <ref-classes-syslinux>` class checks for this
6726 variable and if found, the OpenEmbedded build system installs the
6727 splash screen.
6728
6729 SYSLINUX_SERIAL_TTY
6730 Specifies the alternate console=tty... kernel boot argument. The
6731 variable's default value is set in the
6732 :ref:`syslinux <ref-classes-syslinux>` class as follows:
6733 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
6734
6735 The class checks for and uses the variable as needed.
6736
6737 SYSROOT_DESTDIR
6738 Points to the temporary directory under the work directory (default
6739 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
6740 where the files populated into the sysroot are assembled during the
6741 :ref:`ref-tasks-populate_sysroot` task.
6742
6743 SYSROOT_DIRS
6744 Directories that are staged into the sysroot by the
6745 :ref:`ref-tasks-populate_sysroot` task. By
6746 default, the following directories are staged: SYSROOT_DIRS = " \\
6747 ${includedir} \\ ${libdir} \\ ${base_libdir} \\
6748 ${nonarch_base_libdir} \\ ${datadir} \\ "
6749
6750 SYSROOT_DIRS_BLACKLIST
6751 Directories that are not staged into the sysroot by the
6752 :ref:`ref-tasks-populate_sysroot` task. You
6753 can use this variable to exclude certain subdirectories of
6754 directories listed in :term:`SYSROOT_DIRS` from
6755 staging. By default, the following directories are not staged:
6756 SYSROOT_DIRS_BLACKLIST = " \\ ${mandir} \\ ${docdir} \\ ${infodir} \\
6757 ${datadir}/locale \\ ${datadir}/applications \\ ${datadir}/fonts \\
6758 ${datadir}/pixmaps \\ "
6759
6760 SYSROOT_DIRS_NATIVE
6761 Extra directories staged into the sysroot by the
6762 :ref:`ref-tasks-populate_sysroot` task for
6763 ``-native`` recipes, in addition to those specified in
6764 :term:`SYSROOT_DIRS`. By default, the following
6765 extra directories are staged: SYSROOT_DIRS_NATIVE = " \\ ${bindir} \\
6766 ${sbindir} \\ ${base_bindir} \\ ${base_sbindir} \\ ${libexecdir} \\
6767 ${sysconfdir} \\ ${localstatedir} \\ "
6768
7197 .. note:: 6769 .. note::
7198 6770
7199 This argument is defined in 6771 Programs built by
7200 meta/lib/oeqa/controllers/simpleremote.py 6772 -native
6773 recipes run directly from the sysroot (
6774 STAGING_DIR_NATIVE
6775 ), which is why additional directories containing program
6776 executables and supporting files need to be staged.
6777
6778 SYSROOT_PREPROCESS_FUNCS
6779 A list of functions to execute after files are staged into the
6780 sysroot. These functions are usually used to apply additional
6781 processing on the staged files, or to stage additional files.
6782
6783 SYSTEMD_AUTO_ENABLE
6784 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6785 this variable specifies whether the specified service in
6786 :term:`SYSTEMD_SERVICE` should start
6787 automatically or not. By default, the service is enabled to
6788 automatically start at boot time. The default setting is in the
6789 :ref:`systemd <ref-classes-systemd>` class as follows:
6790 SYSTEMD_AUTO_ENABLE ??= "enable"
6791
6792 You can disable the service by setting the variable to "disable".
6793
6794 SYSTEMD_BOOT_CFG
6795 When :term:`EFI_PROVIDER` is set to
6796 "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the
6797 configuration file that should be used. By default, the
6798 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6799 ``SYSTEMD_BOOT_CFG`` as follows: SYSTEMD_BOOT_CFG ?=
6800 "${:term:`S`}/loader.conf"
6801
6802 For information on Systemd-boot, see the `Systemd-boot
6803 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6804
6805 SYSTEMD_BOOT_ENTRIES
6806 When :term:`EFI_PROVIDER` is set to
6807 "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a
6808 list of entry files (``*.conf``) to install that contain one boot
6809 entry per file. By default, the
6810 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6811 ``SYSTEMD_BOOT_ENTRIES`` as follows: SYSTEMD_BOOT_ENTRIES ?= ""
6812
6813 For information on Systemd-boot, see the `Systemd-boot
6814 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6815
6816 SYSTEMD_BOOT_TIMEOUT
6817 When :term:`EFI_PROVIDER` is set to
6818 "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the
6819 boot menu timeout in seconds. By default, the
6820 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6821 ``SYSTEMD_BOOT_TIMEOUT`` as follows: SYSTEMD_BOOT_TIMEOUT ?= "10"
6822
6823 For information on Systemd-boot, see the `Systemd-boot
6824 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6825
6826 SYSTEMD_PACKAGES
6827 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6828 this variable locates the systemd unit files when they are not found
6829 in the main recipe's package. By default, the ``SYSTEMD_PACKAGES``
6830 variable is set such that the systemd unit files are assumed to
6831 reside in the recipes main package: SYSTEMD_PACKAGES ?= "${PN}"
6832
6833 If these unit files are not in this recipe's main package, you need
6834 to use ``SYSTEMD_PACKAGES`` to list the package or packages in which
6835 the build system can find the systemd unit files.
6836
6837 SYSTEMD_SERVICE
6838 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6839 this variable specifies the systemd service name for a package.
6840
6841 When you specify this file in your recipe, use a package name
6842 override to indicate the package to which the value applies. Here is
6843 an example from the connman recipe: SYSTEMD_SERVICE_${PN} =
6844 "connman.service"
6845
6846 SYSVINIT_ENABLED_GETTYS
6847 When using
6848 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__,
6849 specifies a space-separated list of the virtual terminals that should
6850 run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__
6851 (allowing login), assuming :term:`USE_VT` is not set to
6852 "0".
6853
6854 The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only
6855 run a getty on the first virtual terminal).
6856
6857 T
6858 This variable points to a directory were BitBake places temporary
6859 files, which consist mostly of task logs and scripts, when building a
6860 particular recipe. The variable is typically set as follows: T =
6861 "${WORKDIR}/temp"
6862
6863 The :term:`WORKDIR` is the directory into which
6864 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
6865 file sets this variable.
6866
6867 The ``T`` variable is not to be confused with the
6868 :term:`TMPDIR` variable, which points to the root of
6869 the directory tree where BitBake places the output of an entire
6870 build.
6871
6872 TARGET_ARCH
6873 The target machine's architecture. The OpenEmbedded build system
6874 supports many architectures. Here is an example list of architectures
6875 supported. This list is by no means complete as the architecture is
6876 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel
6877
6878 For additional information on machine architectures, see the
6879 :term:`TUNE_ARCH` variable.
6880
6881 TARGET_AS_ARCH
6882 Specifies architecture-specific assembler flags for the target
6883 system. ``TARGET_AS_ARCH`` is initialized from
6884 :term:`TUNE_ASARGS` by default in the BitBake
6885 configuration file (``meta/conf/bitbake.conf``): TARGET_AS_ARCH =
6886 "${TUNE_ASARGS}"
6887
6888 TARGET_CC_ARCH
6889 Specifies architecture-specific C compiler flags for the target
6890 system. ``TARGET_CC_ARCH`` is initialized from
6891 :term:`TUNE_CCARGS` by default.
6892
6893 .. note::
6894
6895 It is a common workaround to append
6896 LDFLAGS
6897 to
6898 TARGET_CC_ARCH
6899 in recipes that build software for the target that would not
6900 otherwise respect the exported
6901 LDFLAGS
6902 variable.
6903
6904 TARGET_CC_KERNEL_ARCH
6905 This is a specific kernel compiler flag for a CPU or Application
6906 Binary Interface (ABI) tune. The flag is used rarely and only for
6907 cases where a userspace :term:`TUNE_CCARGS` is not
6908 compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH``
6909 variable allows the kernel (and associated modules) to use a
6910 different configuration. See the
6911 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
6912 :term:`Source Directory` for an example.
6913
6914 TARGET_CFLAGS
6915 Specifies the flags to pass to the C compiler when building for the
6916 target. When building in the target context,
6917 :term:`CFLAGS` is set to the value of this variable by
6918 default.
6919
6920 Additionally, the SDK's environment setup script sets the ``CFLAGS``
6921 variable in the environment to the ``TARGET_CFLAGS`` value so that
6922 executables built using the SDK also have the flags applied.
6923
6924 TARGET_CPPFLAGS
6925 Specifies the flags to pass to the C pre-processor (i.e. to both the
6926 C and the C++ compilers) when building for the target. When building
6927 in the target context, :term:`CPPFLAGS` is set to the
6928 value of this variable by default.
6929
6930 Additionally, the SDK's environment setup script sets the
6931 ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS``
6932 value so that executables built using the SDK also have the flags
6933 applied.
6934
6935 TARGET_CXXFLAGS
6936 Specifies the flags to pass to the C++ compiler when building for the
6937 target. When building in the target context,
6938 :term:`CXXFLAGS` is set to the value of this variable
6939 by default.
6940
6941 Additionally, the SDK's environment setup script sets the
6942 ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS``
6943 value so that executables built using the SDK also have the flags
6944 applied.
6945
6946 TARGET_FPU
6947 Specifies the method for handling FPU code. For FPU-less targets,
6948 which include most ARM CPUs, the variable must be set to "soft". If
6949 not, the kernel emulation gets used, which results in a performance
6950 penalty.
6951
6952 TARGET_LD_ARCH
6953 Specifies architecture-specific linker flags for the target system.
6954 ``TARGET_LD_ARCH`` is initialized from
6955 :term:`TUNE_LDARGS` by default in the BitBake
6956 configuration file (``meta/conf/bitbake.conf``): TARGET_LD_ARCH =
6957 "${TUNE_LDARGS}"
6958
6959 TARGET_LDFLAGS
6960 Specifies the flags to pass to the linker when building for the
6961 target. When building in the target context,
6962 :term:`LDFLAGS` is set to the value of this variable
6963 by default.
6964
6965 Additionally, the SDK's environment setup script sets the
6966 :term:`LDFLAGS` variable in the environment to the
6967 ``TARGET_LDFLAGS`` value so that executables built using the SDK also
6968 have the flags applied.
6969
6970 TARGET_OS
6971 Specifies the target's operating system. The variable can be set to
6972 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
6973 for musl libc. For ARM/EABI targets, "linux-gnueabi" and
6974 "linux-musleabi" possible values exist.
6975
6976 TARGET_PREFIX
6977 Specifies the prefix used for the toolchain binary target tools.
6978
6979 Depending on the type of recipe and the build target,
6980 ``TARGET_PREFIX`` is set as follows:
6981
6982 - For recipes building for the target machine, the value is
6983 "${:term:`TARGET_SYS`}-".
6984
6985 - For native recipes, the build system sets the variable to the
6986 value of ``BUILD_PREFIX``.
6987
6988 - For native SDK recipes (``nativesdk``), the build system sets the
6989 variable to the value of ``SDK_PREFIX``.
6990
6991 TARGET_SYS
6992 Specifies the system, including the architecture and the operating
6993 system, for which the build is occurring in the context of the
6994 current recipe.
6995
6996 The OpenEmbedded build system automatically sets this variable based
6997 on :term:`TARGET_ARCH`,
6998 :term:`TARGET_VENDOR`, and
6999 :term:`TARGET_OS` variables.
7000
7001 .. note::
7002
7003 You do not need to set the
7004 TARGET_SYS
7005 variable yourself.
7006
7007 Consider these two examples:
7008
7009 - Given a native recipe on a 32-bit, x86 machine running Linux, the
7010 value is "i686-linux".
7011
7012 - Given a recipe being built for a little-endian, MIPS target
7013 running Linux, the value might be "mipsel-linux".
7014
7015 TARGET_VENDOR
7016 Specifies the name of the target vendor.
7017
7018 TCLIBC
7019 Specifies the GNU standard C library (``libc``) variant to use during
7020 the build process. This variable replaces ``POKYLIBC``, which is no
7021 longer supported.
7022
7023 You can select "glibc", "musl", "newlib", or "baremetal"
7024
7025 TCLIBCAPPEND
7026 Specifies a suffix to be appended onto the
7027 :term:`TMPDIR` value. The suffix identifies the
7028 ``libc`` variant for building. When you are building for multiple
7029 variants with the same :term:`Build Directory`, this
7030 mechanism ensures that output for different ``libc`` variants is kept
7031 separate to avoid potential conflicts.
7032
7033 In the ``defaultsetup.conf`` file, the default value of
7034 ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky,
7035 which normally only support one ``libc`` variant, set
7036 ``TCLIBCAPPEND`` to "" in their distro configuration file resulting
7037 in no suffix being applied.
7038
7039 TCMODE
7040 Specifies the toolchain selector. ``TCMODE`` controls the
7041 characteristics of the generated packages and images by telling the
7042 OpenEmbedded build system which toolchain profile to use. By default,
7043 the OpenEmbedded build system builds its own internal toolchain. The
7044 variable's default value is "default", which uses that internal
7045 toolchain.
7046
7047 .. note::
7048
7049 If
7050 TCMODE
7051 is set to a value other than "default", then it is your
7052 responsibility to ensure that the toolchain is compatible with the
7053 default toolchain. Using older or newer versions of these
7054 components might cause build problems. See the Release Notes for
7055 the Yocto Project release for the specific components with which
7056 the toolchain must be compatible. To access the Release Notes, go
7057 to the
7058 Downloads
7059 page on the Yocto Project website and click on the "RELEASE
7060 INFORMATION" link for the appropriate release.
7061
7062 The ``TCMODE`` variable is similar to :term:`TCLIBC`,
7063 which controls the variant of the GNU standard C library (``libc``)
7064 used during the build process: ``glibc`` or ``musl``.
7065
7066 With additional layers, it is possible to use a pre-compiled external
7067 toolchain. One example is the Sourcery G++ Toolchain. The support for
7068 this toolchain resides in the separate Mentor Graphics
7069 ``meta-sourcery`` layer at
7070 http://github.com/MentorEmbedded/meta-sourcery/.
7071
7072 The layer's ``README`` file contains information on how to use the
7073 Sourcery G++ Toolchain as an external toolchain. In summary, you must
7074 be sure to add the layer to your ``bblayers.conf`` file in front of
7075 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable
7076 in your ``local.conf`` file to the location in which you installed
7077 the toolchain.
7078
7079 The fundamentals used for this example apply to any external
7080 toolchain. You can use ``meta-sourcery`` as a template for adding
7081 support for other external toolchains.
7082
7083 TEST_EXPORT_DIR
7084 The location the OpenEmbedded build system uses to export tests when
7085 the :term:`TEST_EXPORT_ONLY` variable is set
7086 to "1".
7087
7088 The ``TEST_EXPORT_DIR`` variable defaults to
7089 ``"${TMPDIR}/testimage/${PN}"``.
7090
7091 TEST_EXPORT_ONLY
7092 Specifies to export the tests only. Set this variable to "1" if you
7093 do not want to run the tests but you want them to be exported in a
7094 manner that you to run them outside of the build system.
7095
7096 TEST_LOG_DIR
7097 Holds the SSH log and the boot log for QEMU machines. The
7098 ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``.
7099
7100 .. note::
7101
7102 Actual test results reside in the task log (
7103 log.do_testimage
7104 ), which is in the
7105 ${WORKDIR}/temp/
7106 directory.
7107
7108 TEST_POWERCONTROL_CMD
7109 For automated hardware testing, specifies the command to use to
7110 control the power of the target machine under test. Typically, this
7111 command would point to a script that performs the appropriate action
7112 (e.g. interacting with a web-enabled power strip). The specified
7113 command should expect to receive as the last argument "off", "on" or
7114 "cycle" specifying to power off, on, or cycle (power off and then
7115 power on) the device, respectively.
7116
7117 TEST_POWERCONTROL_EXTRA_ARGS
7118 For automated hardware testing, specifies additional arguments to
7119 pass through to the command specified in
7120 :term:`TEST_POWERCONTROL_CMD`. Setting
7121 ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you
7122 wish, for example, to separate the machine-specific and
7123 non-machine-specific parts of the arguments.
7124
7125 TEST_QEMUBOOT_TIMEOUT
7126 The time in seconds allowed for an image to boot before automated
7127 runtime tests begin to run against an image. The default timeout
7128 period to allow the boot process to reach the login prompt is 500
7129 seconds. You can specify a different value in the ``local.conf``
7130 file.
7131
7132 For more information on testing images, see the "`Performing
7133 Automated Runtime
7134 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
7135 section in the Yocto Project Development Tasks Manual.
7136
7137 TEST_SERIALCONTROL_CMD
7138 For automated hardware testing, specifies the command to use to
7139 connect to the serial console of the target machine under test. This
7140 command simply needs to connect to the serial console and forward
7141 that connection to standard input and output as any normal terminal
7142 program does.
7143
7144 For example, to use the Picocom terminal program on serial device
7145 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:
7146 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
7147
7148 TEST_SERIALCONTROL_EXTRA_ARGS
7149 For automated hardware testing, specifies additional arguments to
7150 pass through to the command specified in
7151 :term:`TEST_SERIALCONTROL_CMD`. Setting
7152 ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you
7153 wish, for example, to separate the machine-specific and
7154 non-machine-specific parts of the command.
7155
7156 TEST_SERVER_IP
7157 The IP address of the build machine (host machine). This IP address
7158 is usually automatically detected. However, if detection fails, this
7159 variable needs to be set to the IP address of the build machine (i.e.
7160 where the build is taking place).
7161
7162 .. note::
7163
7164 The
7165 TEST_SERVER_IP
7166 variable is only used for a small number of tests such as the
7167 "dnf" test suite, which needs to download packages from
7168 WORKDIR/oe-rootfs-repo
7201 . 7169 .
7202 7170
7203 For information on running tests on hardware, see the "`Enabling 7171 TEST_TARGET
7204 Runtime Tests on 7172 Specifies the target controller to use when running tests against a
7205 Hardware <&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests>`__" 7173 test image. The default controller to use is "qemu": TEST_TARGET =
7206 section in the Yocto Project Development Tasks Manual. 7174 "qemu"
7207 7175
7208TEST_TARGET_IP 7176 A target controller is a class that defines how an image gets
7209 The IP address of your hardware under test. The ``TEST_TARGET_IP`` 7177 deployed on a target and how a target is started. A layer can extend
7210 variable has no effect when ```TEST_TARGET`` <#var-TEST_TARGET>`__ is 7178 the controllers by adding a module in the layer's
7211 set to "qemu". 7179 ``/lib/oeqa/controllers`` directory and by inheriting the
7212 7180 ``BaseTarget`` class, which is an abstract class that cannot be used
7213 When you specify the IP address, you can also include a port. Here is 7181 as a value of ``TEST_TARGET``.
7214 an example: TEST_TARGET_IP = "192.168.1.4:2201" Specifying a port is 7182
7215 useful when SSH is started on a non-standard port or in cases when 7183 You can provide the following arguments with ``TEST_TARGET``:
7216 your hardware under test is behind a firewall or network that is not 7184
7217 directly accessible from your host and you need to do port address 7185 - *"qemu":* Boots a QEMU image and runs the tests. See the
7218 translation. 7186 "`Enabling Runtime Tests on
7219 7187 QEMU <&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests>`__" section
7220TEST_SUITES 7188 in the Yocto Project Development Tasks Manual for more
7221 An ordered list of tests (modules) to run against an image when 7189 information.
7222 performing automated runtime testing. 7190
7223 7191 - *"simpleremote":* Runs the tests on target hardware that is
7224 The OpenEmbedded build system provides a core set of tests that can 7192 already up and running. The hardware can be on the network or it
7225 be used against images. 7193 can be a device running an image on QEMU. You must also set
7226 7194 :term:`TEST_TARGET_IP` when you use
7227 .. note:: 7195 "simpleremote".
7228 7196
7229 Currently, there is only support for running these tests under 7197 .. note::
7230 QEMU. 7198
7231 7199 This argument is defined in
7232 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 7200 meta/lib/oeqa/controllers/simpleremote.py
7233 your own tests to the list of tests by appending ``TEST_SUITES`` as 7201 .
7234 follows: TEST_SUITES_append = " mytest" Alternatively, you can 7202
7235 provide the "auto" option to have all applicable tests run against 7203 For information on running tests on hardware, see the "`Enabling
7236 the image. TEST_SUITES_append = " auto" Using this option causes the 7204 Runtime Tests on
7237 build system to automatically run tests that are applicable to the 7205 Hardware <&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests>`__"
7238 image. Tests that are not applicable are skipped. 7206 section in the Yocto Project Development Tasks Manual.
7239 7207
7240 The order in which tests are run is important. Tests that depend on 7208 TEST_TARGET_IP
7241 another test must appear later in the list than the test on which 7209 The IP address of your hardware under test. The ``TEST_TARGET_IP``
7242 they depend. For example, if you append the list of tests with two 7210 variable has no effect when :term:`TEST_TARGET` is
7243 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 7211 set to "qemu".
7244 ``test_A``, then you must order the tests as follows: TEST_SUITES = " 7212
7245 test_A test_B" 7213 When you specify the IP address, you can also include a port. Here is
7246 7214 an example: TEST_TARGET_IP = "192.168.1.4:2201" Specifying a port is
7247 For more information on testing images, see the "`Performing 7215 useful when SSH is started on a non-standard port or in cases when
7248 Automated Runtime 7216 your hardware under test is behind a firewall or network that is not
7249 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" 7217 directly accessible from your host and you need to do port address
7250 section in the Yocto Project Development Tasks Manual. 7218 translation.
7251 7219
7252TESTIMAGE_AUTO 7220 TEST_SUITES
7253 Automatically runs the series of automated tests for images when an 7221 An ordered list of tests (modules) to run against an image when
7254 image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes 7222 performing automated runtime testing.
7255 any image that successfully builds to automatically boot under QEMU. 7223
7256 Using the variable also adds in dependencies so that any SDK for 7224 The OpenEmbedded build system provides a core set of tests that can
7257 which testing is requested is automatically built first. 7225 be used against images.
7258 7226
7259 These tests are written in Python making use of the ``unittest`` 7227 .. note::
7260 module, and the majority of them run commands on the target system 7228
7261 over ``ssh``. You can set this variable to "1" in your ``local.conf`` 7229 Currently, there is only support for running these tests under
7262 file in the `Build Directory <#build-directory>`__ to have the 7230 QEMU.
7263 OpenEmbedded build system automatically run these tests after an 7231
7264 image successfully builds: TESTIMAGE_AUTO = "1" For more information 7232 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
7265 on enabling, running, and writing these tests, see the "`Performing 7233 your own tests to the list of tests by appending ``TEST_SUITES`` as
7266 Automated Runtime 7234 follows: TEST_SUITES_append = " mytest" Alternatively, you can
7267 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" 7235 provide the "auto" option to have all applicable tests run against
7268 section in the Yocto Project Development Tasks Manual and the 7236 the image. TEST_SUITES_append = " auto" Using this option causes the
7269 "```testimage*.bbclass`` <#ref-classes-testimage*>`__" section. 7237 build system to automatically run tests that are applicable to the
7270 7238 image. Tests that are not applicable are skipped.
7271THISDIR 7239
7272 The directory in which the file BitBake is currently parsing is 7240 The order in which tests are run is important. Tests that depend on
7273 located. Do not manually set this variable. 7241 another test must appear later in the list than the test on which
7274 7242 they depend. For example, if you append the list of tests with two
7275TIME 7243 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
7276 The time the build was started. Times appear using the hour, minute, 7244 ``test_A``, then you must order the tests as follows: TEST_SUITES = "
7277 and second (HMS) format (e.g. "140159" for one minute and fifty-nine 7245 test_A test_B"
7278 seconds past 1400 hours). 7246
7279 7247 For more information on testing images, see the "`Performing
7280TMPDIR 7248 Automated Runtime
7281 This variable is the base directory the OpenEmbedded build system 7249 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
7282 uses for all build output and intermediate files (other than the 7250 section in the Yocto Project Development Tasks Manual.
7283 shared state cache). By default, the ``TMPDIR`` variable points to 7251
7284 ``tmp`` within the `Build Directory <#build-directory>`__. 7252 TESTIMAGE_AUTO
7285 7253 Automatically runs the series of automated tests for images when an
7286 If you want to establish this directory in a location other than the 7254 image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes
7287 default, you can uncomment and edit the following statement in the 7255 any image that successfully builds to automatically boot under QEMU.
7288 ``conf/local.conf`` file in the `Source 7256 Using the variable also adds in dependencies so that any SDK for
7289 Directory <#source-directory>`__: #TMPDIR = "${TOPDIR}/tmp" An 7257 which testing is requested is automatically built first.
7290 example use for this scenario is to set ``TMPDIR`` to a local disk, 7258
7291 which does not use NFS, while having the Build Directory use NFS. 7259 These tests are written in Python making use of the ``unittest``
7292 7260 module, and the majority of them run commands on the target system
7293 The filesystem used by ``TMPDIR`` must have standard filesystem 7261 over ``ssh``. You can set this variable to "1" in your ``local.conf``
7294 semantics (i.e. mixed-case files are unique, POSIX file locking, and 7262 file in the :term:`Build Directory` to have the
7295 persistent inodes). Due to various issues with NFS and bugs in some 7263 OpenEmbedded build system automatically run these tests after an
7296 implementations, NFS does not meet this minimum requirement. 7264 image successfully builds: TESTIMAGE_AUTO = "1" For more information
7297 Consequently, ``TMPDIR`` cannot be on NFS. 7265 on enabling, running, and writing these tests, see the "`Performing
7298 7266 Automated Runtime
7299TOOLCHAIN_HOST_TASK 7267 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
7300 This variable lists packages the OpenEmbedded build system uses when 7268 section in the Yocto Project Development Tasks Manual and the
7301 building an SDK, which contains a cross-development environment. The 7269 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section.
7302 packages specified by this variable are part of the toolchain set 7270
7303 that runs on the ```SDKMACHINE`` <#var-SDKMACHINE>`__, and each 7271 THISDIR
7304 package should usually have the prefix ``nativesdk-``. For example, 7272 The directory in which the file BitBake is currently parsing is
7305 consider the following command when building an SDK: $ bitbake -c 7273 located. Do not manually set this variable.
7306 populate_sdk imagename In this case, a default list of packages is 7274
7307 set in this variable, but you can add additional packages to the 7275 TIME
7308 list. See the "`Adding Individual Packages to the Standard 7276 The time the build was started. Times appear using the hour, minute,
7309 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section 7277 and second (HMS) format (e.g. "140159" for one minute and fifty-nine
7310 in the Yocto Project Application Development and the Extensible 7278 seconds past 1400 hours).
7311 Software Development Kit (eSDK) manual for more information. 7279
7312 7280 TMPDIR
7313 For background information on cross-development toolchains in the 7281 This variable is the base directory the OpenEmbedded build system
7314 Yocto Project development environment, see the "`Cross-Development 7282 uses for all build output and intermediate files (other than the
7315 Toolchain 7283 shared state cache). By default, the ``TMPDIR`` variable points to
7316 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__" 7284 ``tmp`` within the :term:`Build Directory`.
7317 section in the Yocto Project Overview and Concepts Manual. For 7285
7318 information on setting up a cross-development environment, see the 7286 If you want to establish this directory in a location other than the
7319 `Yocto Project Application Development and the Extensible Software 7287 default, you can uncomment and edit the following statement in the
7320 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. 7288 ``conf/local.conf`` file in the :term:`Source Directory`:
7321 7289 #TMPDIR = "${TOPDIR}/tmp" An
7322TOOLCHAIN_OUTPUTNAME 7290 example use for this scenario is to set ``TMPDIR`` to a local disk,
7323 This variable defines the name used for the toolchain output. The 7291 which does not use NFS, while having the Build Directory use NFS.
7324 ```populate_sdk_base`` <#ref-classes-populate-sdk-*>`__ class sets 7292
7325 the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: 7293 The filesystem used by ``TMPDIR`` must have standard filesystem
7326 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" See 7294 semantics (i.e. mixed-case files are unique, POSIX file locking, and
7327 the ```SDK_NAME`` <#var-SDK_NAME>`__ and 7295 persistent inodes). Due to various issues with NFS and bugs in some
7328 ```SDK_VERSION`` <#var-SDK_VERSION>`__ variables for additional 7296 implementations, NFS does not meet this minimum requirement.
7329 information. 7297 Consequently, ``TMPDIR`` cannot be on NFS.
7330 7298
7331TOOLCHAIN_TARGET_TASK 7299 TOOLCHAIN_HOST_TASK
7332 This variable lists packages the OpenEmbedded build system uses when 7300 This variable lists packages the OpenEmbedded build system uses when
7333 it creates the target part of an SDK (i.e. the part built for the 7301 building an SDK, which contains a cross-development environment. The
7334 target hardware), which includes libraries and headers. Use this 7302 packages specified by this variable are part of the toolchain set
7335 variable to add individual packages to the part of the SDK that runs 7303 that runs on the :term:`SDKMACHINE`, and each
7336 on the target. See the "`Adding Individual Packages to the Standard 7304 package should usually have the prefix ``nativesdk-``. For example,
7337 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section 7305 consider the following command when building an SDK: $ bitbake -c
7338 in the Yocto Project Application Development and the Extensible 7306 populate_sdk imagename In this case, a default list of packages is
7339 Software Development Kit (eSDK) manual for more information. 7307 set in this variable, but you can add additional packages to the
7340 7308 list. See the "`Adding Individual Packages to the Standard
7341 For background information on cross-development toolchains in the 7309 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section
7342 Yocto Project development environment, see the "`Cross-Development 7310 in the Yocto Project Application Development and the Extensible
7343 Toolchain 7311 Software Development Kit (eSDK) manual for more information.
7344 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__" 7312
7345 section in the Yocto Project Overview and Concepts Manual. For 7313 For background information on cross-development toolchains in the
7346 information on setting up a cross-development environment, see the 7314 Yocto Project development environment, see the "`Cross-Development
7347 `Yocto Project Application Development and the Extensible Software 7315 Toolchain
7348 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. 7316 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
7349 7317 section in the Yocto Project Overview and Concepts Manual. For
7350TOPDIR 7318 information on setting up a cross-development environment, see the
7351 The top-level `Build Directory <#build-directory>`__. BitBake 7319 `Yocto Project Application Development and the Extensible Software
7352 automatically sets this variable when you initialize your build 7320 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
7353 environment using ````` <#structure-core-script>`__. 7321
7354 7322 TOOLCHAIN_OUTPUTNAME
7355TRANSLATED_TARGET_ARCH 7323 This variable defines the name used for the toolchain output. The
7356 A sanitized version of ```TARGET_ARCH`` <#var-TARGET_ARCH>`__. This 7324 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
7357 variable is used where the architecture is needed in a value where 7325 the ``TOOLCHAIN_OUTPUTNAME`` variable as follows:
7358 underscores are not allowed, for example within package filenames. In 7326 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" See
7359 this case, dash characters replace any underscore characters used in 7327 the :term:`SDK_NAME` and
7360 ``TARGET_ARCH``. 7328 :term:`SDK_VERSION` variables for additional
7361 7329 information.
7362 Do not edit this variable. 7330
7363 7331 TOOLCHAIN_TARGET_TASK
7364TUNE_ARCH 7332 This variable lists packages the OpenEmbedded build system uses when
7365 The GNU canonical architecture for a specific architecture (i.e. 7333 it creates the target part of an SDK (i.e. the part built for the
7366 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 7334 target hardware), which includes libraries and headers. Use this
7367 this value to setup configuration. 7335 variable to add individual packages to the part of the SDK that runs
7368 7336 on the target. See the "`Adding Individual Packages to the Standard
7369 ``TUNE_ARCH`` definitions are specific to a given architecture. The 7337 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section
7370 definitions can be a single static definition, or can be dynamically 7338 in the Yocto Project Application Development and the Extensible
7371 adjusted. You can see details for a given CPU family by looking at 7339 Software Development Kit (eSDK) manual for more information.
7372 the architecture's ``README`` file. For example, the 7340
7373 ``meta/conf/machine/include/mips/README`` file in the `Source 7341 For background information on cross-development toolchains in the
7374 Directory <#source-directory>`__ provides information for 7342 Yocto Project development environment, see the "`Cross-Development
7375 ``TUNE_ARCH`` specific to the ``mips`` architecture. 7343 Toolchain
7376 7344 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
7377 ``TUNE_ARCH`` is tied closely to 7345 section in the Yocto Project Overview and Concepts Manual. For
7378 ```TARGET_ARCH`` <#var-TARGET_ARCH>`__, which defines the target 7346 information on setting up a cross-development environment, see the
7379 machine's architecture. The BitBake configuration file 7347 `Yocto Project Application Development and the Extensible Software
7380 (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: 7348 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
7381 TARGET_ARCH = "${TUNE_ARCH}" 7349
7382 7350 TOPDIR
7383 The following list, which is by no means complete since architectures 7351 The top-level :term:`Build Directory`. BitBake
7384 are configurable, shows supported machine architectures: arm i586 7352 automatically sets this variable when you initialize your build
7385 x86_64 powerpc powerpc64 mips mipsel 7353 environment using ````` <#structure-core-script>`__.
7386 7354
7387TUNE_ASARGS 7355 TRANSLATED_TARGET_ARCH
7388 Specifies architecture-specific assembler flags for the target 7356 A sanitized version of :term:`TARGET_ARCH`. This
7389 system. The set of flags is based on the selected tune features. 7357 variable is used where the architecture is needed in a value where
7390 ``TUNE_ASARGS`` is set using the tune include files, which are 7358 underscores are not allowed, for example within package filenames. In
7391 typically under ``meta/conf/machine/include/`` and are influenced 7359 this case, dash characters replace any underscore characters used in
7392 through ```TUNE_FEATURES`` <#var-TUNE_FEATURES>`__. For example, the 7360 ``TARGET_ARCH``.
7393 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 7361
7394 for the x86 architecture as follows: TUNE_ASARGS += 7362 Do not edit this variable.
7395 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 7363
7396 7364 TUNE_ARCH
7397 .. note:: 7365 The GNU canonical architecture for a specific architecture (i.e.
7398 7366 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
7399 Board Support Packages (BSPs) select the tune. The selected tune, 7367 this value to setup configuration.
7400 in turn, affects the tune variables themselves (i.e. the tune can 7368
7401 supply its own set of flags). 7369 ``TUNE_ARCH`` definitions are specific to a given architecture. The
7402 7370 definitions can be a single static definition, or can be dynamically
7403TUNE_CCARGS 7371 adjusted. You can see details for a given CPU family by looking at
7404 Specifies architecture-specific C compiler flags for the target 7372 the architecture's ``README`` file. For example, the
7405 system. The set of flags is based on the selected tune features. 7373 ``meta/conf/machine/include/mips/README`` file in the
7406 ``TUNE_CCARGS`` is set using the tune include files, which are 7374 :term:`Source Directory` provides information for
7407 typically under ``meta/conf/machine/include/`` and are influenced 7375 ``TUNE_ARCH`` specific to the ``mips`` architecture.
7408 through ```TUNE_FEATURES`` <#var-TUNE_FEATURES>`__. 7376
7409 7377 ``TUNE_ARCH`` is tied closely to
7410 .. note:: 7378 :term:`TARGET_ARCH`, which defines the target
7411 7379 machine's architecture. The BitBake configuration file
7412 Board Support Packages (BSPs) select the tune. The selected tune, 7380 (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows:
7413 in turn, affects the tune variables themselves (i.e. the tune can 7381 TARGET_ARCH = "${TUNE_ARCH}"
7414 supply its own set of flags). 7382
7415 7383 The following list, which is by no means complete since architectures
7416TUNE_LDARGS 7384 are configurable, shows supported machine architectures: arm i586
7417 Specifies architecture-specific linker flags for the target system. 7385 x86_64 powerpc powerpc64 mips mipsel
7418 The set of flags is based on the selected tune features. 7386
7419 ``TUNE_LDARGS`` is set using the tune include files, which are 7387 TUNE_ASARGS
7420 typically under ``meta/conf/machine/include/`` and are influenced 7388 Specifies architecture-specific assembler flags for the target
7421 through ```TUNE_FEATURES`` <#var-TUNE_FEATURES>`__. For example, the 7389 system. The set of flags is based on the selected tune features.
7422 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 7390 ``TUNE_ASARGS`` is set using the tune include files, which are
7423 for the x86 architecture as follows: TUNE_LDARGS += 7391 typically under ``meta/conf/machine/include/`` and are influenced
7424 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", 7392 through :term:`TUNE_FEATURES`. For example, the
7425 d)}" 7393 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
7426 7394 for the x86 architecture as follows: TUNE_ASARGS +=
7427 .. note:: 7395 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
7428 7396
7429 Board Support Packages (BSPs) select the tune. The selected tune, 7397 .. note::
7430 in turn, affects the tune variables themselves (i.e. the tune can 7398
7431 supply its own set of flags). 7399 Board Support Packages (BSPs) select the tune. The selected tune,
7432 7400 in turn, affects the tune variables themselves (i.e. the tune can
7433TUNE_FEATURES 7401 supply its own set of flags).
7434 Features used to "tune" a compiler for optimal use given a specific 7402
7435 processor. The features are defined within the tune files and allow 7403 TUNE_CCARGS
7436 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on 7404 Specifies architecture-specific C compiler flags for the target
7437 the features. 7405 system. The set of flags is based on the selected tune features.
7438 7406 ``TUNE_CCARGS`` is set using the tune include files, which are
7439 The OpenEmbedded build system verifies the features to be sure they 7407 typically under ``meta/conf/machine/include/`` and are influenced
7440 are not conflicting and that they are supported. 7408 through :term:`TUNE_FEATURES`.
7441 7409
7442 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 7410 .. note::
7443 ``TUNE_FEATURES`` as follows: TUNE_FEATURES ??= 7411
7444 "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" See the 7412 Board Support Packages (BSPs) select the tune. The selected tune,
7445 ```DEFAULTTUNE`` <#var-DEFAULTTUNE>`__ variable for more information. 7413 in turn, affects the tune variables themselves (i.e. the tune can
7446 7414 supply its own set of flags).
7447TUNE_PKGARCH 7415
7448 The package architecture understood by the packaging system to define 7416 TUNE_LDARGS
7449 the architecture, ABI, and tuning of output packages. The specific 7417 Specifies architecture-specific linker flags for the target system.
7450 tune is defined using the "_tune" override as follows: 7418 The set of flags is based on the selected tune features.
7451 TUNE_PKGARCH_tune-tune = "tune" 7419 ``TUNE_LDARGS`` is set using the tune include files, which are
7452 7420 typically under ``meta/conf/machine/include/`` and are influenced
7453 These tune-specific package architectures are defined in the machine 7421 through :term:`TUNE_FEATURES`. For example, the
7454 include files. Here is an example of the "core2-32" tuning as used in 7422 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
7455 the ``meta/conf/machine/include/tune-core2.inc`` file: 7423 for the x86 architecture as follows: TUNE_LDARGS +=
7456 TUNE_PKGARCH_tune-core2-32 = "core2-32" 7424 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "",
7457 7425 d)}"
7458TUNEABI 7426
7459 An underlying Application Binary Interface (ABI) used by a particular 7427 .. note::
7460 tuning in a given toolchain layer. Providers that use prebuilt 7428
7461 libraries can use the ``TUNEABI``, 7429 Board Support Packages (BSPs) select the tune. The selected tune,
7462 ```TUNEABI_OVERRIDE`` <#var-TUNEABI_OVERRIDE>`__, and 7430 in turn, affects the tune variables themselves (i.e. the tune can
7463 ```TUNEABI_WHITELIST`` <#var-TUNEABI_WHITELIST>`__ variables to check 7431 supply its own set of flags).
7464 compatibility of tunings against their selection of libraries. 7432
7465 7433 TUNE_FEATURES
7466 If ``TUNEABI`` is undefined, then every tuning is allowed. See the 7434 Features used to "tune" a compiler for optimal use given a specific
7467 ```sanity`` <#ref-classes-sanity>`__ class to see how the variable is 7435 processor. The features are defined within the tune files and allow
7468 used. 7436 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
7469 7437 the features.
7470TUNEABI_OVERRIDE 7438
7471 If set, the OpenEmbedded system ignores the 7439 The OpenEmbedded build system verifies the features to be sure they
7472 ```TUNEABI_WHITELIST`` <#var-TUNEABI_WHITELIST>`__ variable. 7440 are not conflicting and that they are supported.
7473 Providers that use prebuilt libraries can use the 7441
7474 ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and 7442 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
7475 ```TUNEABI`` <#var-TUNEABI>`__ variables to check compatibility of a 7443 ``TUNE_FEATURES`` as follows: TUNE_FEATURES ??=
7476 tuning against their selection of libraries. 7444 "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" See the
7477 7445 :term:`DEFAULTTUNE` variable for more information.
7478 See the ```sanity`` <#ref-classes-sanity>`__ class to see how the 7446
7479 variable is used. 7447 TUNE_PKGARCH
7480 7448 The package architecture understood by the packaging system to define
7481TUNEABI_WHITELIST 7449 the architecture, ABI, and tuning of output packages. The specific
7482 A whitelist of permissible ```TUNEABI`` <#var-TUNEABI>`__ values. If 7450 tune is defined using the "_tune" override as follows:
7483 ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers 7451 TUNE_PKGARCH_tune-tune = "tune"
7484 that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, 7452
7485 ```TUNEABI_OVERRIDE`` <#var-TUNEABI_OVERRIDE>`__, and ``TUNEABI`` 7453 These tune-specific package architectures are defined in the machine
7486 variables to check compatibility of a tuning against their selection 7454 include files. Here is an example of the "core2-32" tuning as used in
7487 of libraries. 7455 the ``meta/conf/machine/include/tune-core2.inc`` file:
7488 7456 TUNE_PKGARCH_tune-core2-32 = "core2-32"
7489 See the ```sanity`` <#ref-classes-sanity>`__ class to see how the 7457
7490 variable is used. 7458 TUNEABI
7491 7459 An underlying Application Binary Interface (ABI) used by a particular
7492TUNECONFLICTS[feature] 7460 tuning in a given toolchain layer. Providers that use prebuilt
7493 Specifies CPU or Application Binary Interface (ABI) tuning features 7461 libraries can use the ``TUNEABI``,
7494 that conflict with feature. 7462 :term:`TUNEABI_OVERRIDE`, and
7495 7463 :term:`TUNEABI_WHITELIST` variables to check
7496 Known tuning conflicts are specified in the machine include files in 7464 compatibility of tunings against their selection of libraries.
7497 the `Source Directory <#source-directory>`__. Here is an example from 7465
7498 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 7466 If ``TUNEABI`` is undefined, then every tuning is allowed. See the
7499 that lists the "o32" and "n64" features as conflicting with the "n32" 7467 :ref:`sanity <ref-classes-sanity>` class to see how the variable is
7500 feature: TUNECONFLICTS[n32] = "o32 n64" 7468 used.
7501 7469
7502TUNEVALID[feature] 7470 TUNEABI_OVERRIDE
7503 Specifies a valid CPU or Application Binary Interface (ABI) tuning 7471 If set, the OpenEmbedded system ignores the
7504 feature. The specified feature is stored as a flag. Valid features 7472 :term:`TUNEABI_WHITELIST` variable.
7505 are specified in the machine include files (e.g. 7473 Providers that use prebuilt libraries can use the
7506 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 7474 ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and
7507 from that file: TUNEVALID[bigendian] = "Enable big-endian mode." 7475 :term:`TUNEABI` variables to check compatibility of a
7508 7476 tuning against their selection of libraries.
7509 See the machine include files in the `Source 7477
7510 Directory <#source-directory>`__ for these features. 7478 See the :ref:`sanity <ref-classes-sanity>` class to see how the
7511 7479 variable is used.
7512UBOOT_CONFIG 7480
7513 Configures the ```UBOOT_MACHINE`` <#var-UBOOT_MACHINE>`__ and can 7481 TUNEABI_WHITELIST
7514 also define ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ for individual 7482 A whitelist of permissible :term:`TUNEABI` values. If
7515 cases. 7483 ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers
7516 7484 that use prebuilt libraries can use the ``TUNEABI_WHITELIST``,
7517 Following is an example from the ``meta-fsl-arm`` layer. UBOOT_CONFIG 7485 :term:`TUNEABI_OVERRIDE`, and ``TUNEABI``
7518 ??= "sd" UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" 7486 variables to check compatibility of a tuning against their selection
7519 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" 7487 of libraries.
7520 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" 7488
7521 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" In this example, 7489 See the :ref:`sanity <ref-classes-sanity>` class to see how the
7522 "sd" is selected as the configuration of the possible four for the 7490 variable is used.
7523 ``UBOOT_MACHINE``. The "sd" configuration defines 7491
7524 "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the 7492 TUNECONFLICTS[feature]
7525 "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image. 7493 Specifies CPU or Application Binary Interface (ABI) tuning features
7526 7494 that conflict with feature.
7527 For more information on how the ``UBOOT_CONFIG`` is handled, see the 7495
7528 ```uboot-config`` <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass>`__ 7496 Known tuning conflicts are specified in the machine include files in
7529 class. 7497 the :term:`Source Directory`. Here is an example from
7530 7498 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
7531UBOOT_ENTRYPOINT 7499 that lists the "o32" and "n64" features as conflicting with the "n32"
7532 Specifies the entry point for the U-Boot image. During U-Boot image 7500 feature: TUNECONFLICTS[n32] = "o32 n64"
7533 creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a 7501
7534 command-line parameter to the ``uboot-mkimage`` utility. 7502 TUNEVALID[feature]
7535 7503 Specifies a valid CPU or Application Binary Interface (ABI) tuning
7536UBOOT_LOADADDRESS 7504 feature. The specified feature is stored as a flag. Valid features
7537 Specifies the load address for the U-Boot image. During U-Boot image 7505 are specified in the machine include files (e.g.
7538 creation, the ``UBOOT_LOADADDRESS`` variable is passed as a 7506 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
7539 command-line parameter to the ``uboot-mkimage`` utility. 7507 from that file: TUNEVALID[bigendian] = "Enable big-endian mode."
7540 7508
7541UBOOT_LOCALVERSION 7509 See the machine include files in the :term:`Source Directory`
7542 Appends a string to the name of the local version of the U-Boot 7510 for these features.
7543 image. For example, assuming the version of the U-Boot image built 7511
7544 was "2013.10", the full version string reported by U-Boot would be 7512 UBOOT_CONFIG
7545 "2013.10-yocto" given the following statement: UBOOT_LOCALVERSION = 7513 Configures the :term:`UBOOT_MACHINE` and can
7546 "-yocto" 7514 also define :term:`IMAGE_FSTYPES` for individual
7547 7515 cases.
7548UBOOT_MACHINE 7516
7549 Specifies the value passed on the ``make`` command line when building 7517 Following is an example from the ``meta-fsl-arm`` layer. UBOOT_CONFIG
7550 a U-Boot image. The value indicates the target platform 7518 ??= "sd" UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
7551 configuration. You typically set this variable from the machine 7519 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
7552 configuration file (i.e. ``conf/machine/machine_name.conf``). 7520 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
7553 7521 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" In this example,
7554 Please see the "Selection of Processor Architecture and Board Type" 7522 "sd" is selected as the configuration of the possible four for the
7555 section in the U-Boot README for valid values for this variable. 7523 ``UBOOT_MACHINE``. The "sd" configuration defines
7556 7524 "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the
7557UBOOT_MAKE_TARGET 7525 "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image.
7558 Specifies the target called in the ``Makefile``. The default target 7526
7559 is "all". 7527 For more information on how the ``UBOOT_CONFIG`` is handled, see the
7560 7528 ```uboot-config`http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass
7561UBOOT_MKIMAGE_DTCOPTS
7562 Options for the device tree compiler passed to mkimage '-D'
7563 feature while creating FIT image in ``kernel-fitimage`` class.
7564
7565UBOOT_RD_LOADADDRESS
7566 Specifies the load address for the RAM disk image.
7567 During FIT image creation, the
7568 ``UBOOT_RD_LOADADDRESS`` variable is used
7569 in ``kernel-fitimage`` class to specify the
7570 load address to be used in creating the Image Tree Source for
7571 the FIT image.
7572
7573UBOOT_RD_ENTRYPOINT
7574 Specifies the entrypoint for the RAM disk image.
7575 During FIT image creation, the
7576 ``UBOOT_RD_ENTRYPOINT`` variable is used
7577 in ``kernel-fitimage`` class to specify the
7578 entrypoint to be used in creating the Image Tree Source for
7579 the FIT image.
7580
7581UBOOT_SUFFIX
7582 Points to the generated U-Boot extension. For example, ``u-boot.sb``
7583 has a ``.sb`` extension.
7584
7585 The default U-Boot extension is ``.bin``
7586
7587UBOOT_TARGET
7588 Specifies the target used for building U-Boot. The target is passed
7589 directly as part of the "make" command (e.g. SPL and AIS). If you do
7590 not specifically set this variable, the OpenEmbedded build process
7591 passes and uses "all" for the target during the U-Boot building
7592 process.
7593
7594UBOOT_SIGN_ENABLE
7595 Enable signing of FIT image. The default value is "0".
7596
7597UBOOT_SIGN_KEYDIR
7598 Location of the directory containing the RSA key and
7599 certificate used for signing FIT image.
7600
7601UBOOT_SIGN_KEYNAME
7602 The name of keys used for signing U-boot FIT image stored in
7603 :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt
7604 certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have
7605 :term:`UBOOT_SIGN_KEYNAME` set to "dev".
7606
7607UNKNOWN_CONFIGURE_WHITELIST
7608 Specifies a list of options that, if reported by the configure script
7609 as being invalid, should not generate a warning during the
7610 ```do_configure`` <#ref-tasks-configure>`__ task. Normally, invalid
7611 configure options are simply not passed to the configure script (e.g.
7612 should be removed from ```EXTRA_OECONF`` <#var-EXTRA_OECONF>`__ or
7613 ```PACKAGECONFIG_CONFARGS`` <#var-PACKAGECONFIG_CONFARGS>`__).
7614 However, common options, for example, exist that are passed to all
7615 configure scripts at a class level that might not be valid for some
7616 configure scripts. It follows that no benefit exists in seeing a
7617 warning about these options. For these cases, the options are added
7618 to ``UNKNOWN_CONFIGURE_WHITELIST``.
7619
7620 The configure arguments check that uses
7621 ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the
7622 ```insane`` <#ref-classes-insane>`__ class and is only enabled if the
7623 recipe inherits the ```autotools`` <#ref-classes-autotools>`__ class.
7624
7625UPDATERCPN
7626 For recipes inheriting the
7627 ```update-rc.d`` <#ref-classes-update-rc.d>`__ class, ``UPDATERCPN``
7628 specifies the package that contains the initscript that is enabled.
7629
7630 The default value is "${PN}". Given that almost all recipes that
7631 install initscripts package them in the main package for the recipe,
7632 you rarely need to set this variable in individual recipes.
7633
7634UPSTREAM_CHECK_GITTAGREGEX
7635 You can perform a per-recipe check for what the latest upstream
7636 source code version is by calling ``bitbake -c checkpkg`` recipe. If
7637 the recipe source code is provided from Git repositories, the
7638 OpenEmbedded build system determines the latest upstream version by
7639 picking the latest tag from the list of all repository tags.
7640
7641 You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a
7642 regular expression to filter only the relevant tags should the
7643 default filter not work correctly. UPSTREAM_CHECK_GITTAGREGEX =
7644 "git_tag_regex"
7645
7646UPSTREAM_CHECK_REGEX
7647 Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different
7648 regular expression instead of the default one when the package
7649 checking system is parsing the page found using
7650 ```UPSTREAM_CHECK_URI`` <#var-UPSTREAM_CHECK_URI>`__.
7651 UPSTREAM_CHECK_REGEX = "package_regex"
7652
7653UPSTREAM_CHECK_URI
7654 You can perform a per-recipe check for what the latest upstream
7655 source code version is by calling ``bitbake -c checkpkg`` recipe. If
7656 the source code is provided from tarballs, the latest version is
7657 determined by fetching the directory listing where the tarball is and
7658 attempting to find a later tarball. When this approach does not work,
7659 you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that
7660 contains the link to the latest tarball. UPSTREAM_CHECK_URI =
7661 "recipe_url"
7662
7663USE_DEVFS
7664 Determines if ``devtmpfs`` is used for ``/dev`` population. The
7665 default value used for ``USE_DEVFS`` is "1" when no value is
7666 specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a
7667 statically populated ``/dev`` directory.
7668
7669 See the "`Selecting a Device
7670 Manager <&YOCTO_DOCS_DEV_URL;#selecting-dev-manager>`__" section in
7671 the Yocto Project Development Tasks Manual for information on how to
7672 use this variable.
7673
7674USE_VT
7675 When using
7676 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__,
7677 determines whether or not to run a
7678 `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any
7679 virtual terminals in order to enable logging in through those
7680 terminals.
7681
7682 The default value used for ``USE_VT`` is "1" when no default value is
7683 specifically set. Typically, you would set ``USE_VT`` to "0" in the
7684 machine configuration file for machines that do not have a graphical
7685 display attached and therefore do not need virtual terminal
7686 functionality.
7687
7688USER_CLASSES
7689 A list of classes to globally inherit. These classes are used by the
7690 OpenEmbedded build system to enable extra features (e.g.
7691 ``buildstats``, ``image-mklibs``, and so forth).
7692
7693 The default list is set in your ``local.conf`` file: USER_CLASSES ?=
7694 "buildstats image-mklibs image-prelink" For more information, see
7695 ``meta-poky/conf/local.conf.sample`` in the `Source
7696 Directory <#source-directory>`__.
7697
7698USERADD_ERROR_DYNAMIC
7699 If set to ``error``, forces the OpenEmbedded build system to produce
7700 an error if the user identification (``uid``) and group
7701 identification (``gid``) values are not defined in any of the files
7702 listed in ```USERADD_UID_TABLES`` <#var-USERADD_UID_TABLES>`__ and
7703 ```USERADD_GID_TABLES`` <#var-USERADD_GID_TABLES>`__. If set to
7704 ``warn``, a warning will be issued instead.
7705
7706 The default behavior for the build system is to dynamically apply
7707 ``uid`` and ``gid`` values. Consequently, the
7708 ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan
7709 on using statically assigned ``gid`` and ``uid`` values, you should
7710 set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf``
7711 file as follows: USERADD_ERROR_DYNAMIC = "error" Overriding the
7712 default behavior implies you are going to also take steps to set
7713 static ``uid`` and ``gid`` values through use of the
7714 ```USERADDEXTENSION`` <#var-USERADDEXTENSION>`__,
7715 ```USERADD_UID_TABLES`` <#var-USERADD_UID_TABLES>`__, and
7716 ```USERADD_GID_TABLES`` <#var-USERADD_GID_TABLES>`__ variables.
7717
7718 .. note::
7719
7720 There is a difference in behavior between setting
7721 USERADD_ERROR_DYNAMIC
7722 to
7723 error
7724 and setting it to
7725 warn
7726 . When it is set to
7727 warn
7728 , the build system will report a warning for every undefined
7729 uid
7730 and
7731 gid
7732 in any recipe. But when it is set to
7733 error
7734 , it will only report errors for recipes that are actually built.
7735 This saves you from having to add static IDs for recipes that you
7736 know will never be built.
7737
7738USERADD_GID_TABLES
7739 Specifies a password file to use for obtaining static group
7740 identification (``gid``) values when the OpenEmbedded build system
7741 adds a group to the system during package installation.
7742
7743 When applying static group identification (``gid``) values, the
7744 OpenEmbedded build system looks in ```BBPATH`` <#var-BBPATH>`__ for a
7745 ``files/group`` file and then applies those ``uid`` values. Set the
7746 variable as follows in your ``local.conf`` file: USERADD_GID_TABLES =
7747 "files/group"
7748
7749 .. note::
7750
7751 Setting the
7752 USERADDEXTENSION
7753 variable to "useradd-staticids" causes the build system to use
7754 static
7755 gid
7756 values.
7757
7758USERADD_PACKAGES
7759 When inheriting the ```useradd`` <#ref-classes-useradd>`__ class,
7760 this variable specifies the individual packages within the recipe
7761 that require users and/or groups to be added.
7762
7763 You must set this variable if the recipe inherits the class. For
7764 example, the following enables adding a user for the main package in
7765 a recipe: USERADD_PACKAGES = "${PN}"
7766
7767 .. note::
7768
7769 It follows that if you are going to use the
7770 USERADD_PACKAGES
7771 variable, you need to set one or more of the
7772 USERADD_PARAM
7773 ,
7774 GROUPADD_PARAM
7775 , or
7776 GROUPMEMS_PARAM
7777 variables.
7778
7779USERADD_PARAM
7780 When inheriting the ```useradd`` <#ref-classes-useradd>`__ class,
7781 this variable specifies for a package what parameters should pass to
7782 the ``useradd`` command if you add a user to the system when the
7783 package is installed.
7784
7785 Here is an example from the ``dbus`` recipe: USERADD_PARAM_${PN} =
7786 "--system --home ${localstatedir}/lib/dbus \\ --no-create-home
7787 --shell /bin/false \\ --user-group messagebus" For information on the
7788 standard Linux shell command ``useradd``, see
7789 ` <http://linux.die.net/man/8/useradd>`__.
7790
7791USERADD_UID_TABLES
7792 Specifies a password file to use for obtaining static user
7793 identification (``uid``) values when the OpenEmbedded build system
7794 adds a user to the system during package installation.
7795
7796 When applying static user identification (``uid``) values, the
7797 OpenEmbedded build system looks in ```BBPATH`` <#var-BBPATH>`__ for a
7798 ``files/passwd`` file and then applies those ``uid`` values. Set the
7799 variable as follows in your ``local.conf`` file: USERADD_UID_TABLES =
7800 "files/passwd"
7801
7802 .. note::
7803
7804 Setting the
7805 USERADDEXTENSION
7806 variable to "useradd-staticids" causes the build system to use
7807 static
7808 uid
7809 values.
7810
7811USERADDEXTENSION
7812 When set to "useradd-staticids", causes the OpenEmbedded build system
7813 to base all user and group additions on a static ``passwd`` and
7814 ``group`` files found in ```BBPATH`` <#var-BBPATH>`__.
7815
7816 To use static user identification (``uid``) and group identification
7817 (``gid``) values, set the variable as follows in your ``local.conf``
7818 file: USERADDEXTENSION = "useradd-staticids"
7819
7820 .. note::
7821
7822 Setting this variable to use static
7823 uid
7824 and
7825 gid
7826 values causes the OpenEmbedded build system to employ the
7827 useradd-staticids
7828 class. 7529 class.
7829 7530
7830 If you use static ``uid`` and ``gid`` information, you must also 7531 UBOOT_ENTRYPOINT
7831 specify the ``files/passwd`` and ``files/group`` files by setting the 7532 Specifies the entry point for the U-Boot image. During U-Boot image
7832 ```USERADD_UID_TABLES`` <#var-USERADD_UID_TABLES>`__ and 7533 creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a
7833 ```USERADD_GID_TABLES`` <#var-USERADD_GID_TABLES>`__ variables. 7534 command-line parameter to the ``uboot-mkimage`` utility.
7834 Additionally, you should also set the 7535
7835 ```USERADD_ERROR_DYNAMIC`` <#var-USERADD_ERROR_DYNAMIC>`__ variable. 7536 UBOOT_LOADADDRESS
7836 7537 Specifies the load address for the U-Boot image. During U-Boot image
7837VOLATILE_LOG_DIR 7538 creation, the ``UBOOT_LOADADDRESS`` variable is passed as a
7838 Specifies the persistence of the target's ``/var/log`` directory, 7539 command-line parameter to the ``uboot-mkimage`` utility.
7839 which is used to house postinstall target log files. 7540
7840 7541 UBOOT_LOCALVERSION
7841 By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the 7542 Appends a string to the name of the local version of the U-Boot
7842 file is not persistent. You can override this setting by setting the 7543 image. For example, assuming the version of the U-Boot image built
7843 variable to "no" to make the log directory persistent. 7544 was "2013.10", the full version string reported by U-Boot would be
7844 7545 "2013.10-yocto" given the following statement: UBOOT_LOCALVERSION =
7845WARN_QA 7546 "-yocto"
7846 Specifies the quality assurance checks whose failures are reported as 7547
7847 warnings by the OpenEmbedded build system. You set this variable in 7548 UBOOT_MACHINE
7848 your distribution configuration file. For a list of the checks you 7549 Specifies the value passed on the ``make`` command line when building
7849 can control with this variable, see the 7550 a U-Boot image. The value indicates the target platform
7850 "```insane.bbclass`` <#ref-classes-insane>`__" section. 7551 configuration. You typically set this variable from the machine
7851 7552 configuration file (i.e. ``conf/machine/machine_name.conf``).
7852WKS_FILE_DEPENDS 7553
7853 When placed in the recipe that builds your image, this variable lists 7554 Please see the "Selection of Processor Architecture and Board Type"
7854 build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only 7555 section in the U-Boot README for valid values for this variable.
7855 applicable when Wic images are active (i.e. when 7556
7856 ```IMAGE_FSTYPES`` <#var-IMAGE_FSTYPES>`__ contains entries related 7557 UBOOT_MAKE_TARGET
7857 to Wic). If your recipe does not create Wic images, the variable has 7558 Specifies the target called in the ``Makefile``. The default target
7858 no effect. 7559 is "all".
7859 7560
7860 The ``WKS_FILE_DEPENDS`` variable is similar to the 7561 UBOOT_MKIMAGE_DTCOPTS
7861 ```DEPENDS`` <#var-DEPENDS>`__ variable. When you use the variable in 7562 Options for the device tree compiler passed to mkimage '-D'
7862 your recipe that builds the Wic image, dependencies you list in the 7563 feature while creating FIT image in ``kernel-fitimage`` class.
7863 ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. 7564
7864 7565 UBOOT_RD_LOADADDRESS
7865 With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to 7566 Specifies the load address for the RAM disk image.
7866 specify a list of additional dependencies (e.g. native tools, 7567 During FIT image creation, the
7867 bootloaders, and so forth), that are required to build Wic images. 7568 ``UBOOT_RD_LOADADDRESS`` variable is used
7868 Following is an example: WKS_FILE_DEPENDS = "some-native-tool" In the 7569 in ``kernel-fitimage`` class to specify the
7869 previous example, some-native-tool would be replaced with an actual 7570 load address to be used in creating the Image Tree Source for
7870 native tool on which the build would depend. 7571 the FIT image.
7871 7572
7872WKS_FILE 7573 UBOOT_RD_ENTRYPOINT
7873 Specifies the location of the Wic kickstart file that is used by the 7574 Specifies the entrypoint for the RAM disk image.
7874 OpenEmbedded build system to create a partitioned image 7575 During FIT image creation, the
7875 (image\ ``.wic``). For information on how to create a partitioned 7576 ``UBOOT_RD_ENTRYPOINT`` variable is used
7876 image, see the "`Creating Partitioned Images Using 7577 in ``kernel-fitimage`` class to specify the
7877 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__" 7578 entrypoint to be used in creating the Image Tree Source for
7878 section in the Yocto Project Development Tasks Manual. For details on 7579 the FIT image.
7879 the kickstart file format, see the "`OpenEmbedded Kickstart 7580
7880 (``.wks``) Reference <#ref-kickstart>`__" Chapter. 7581 UBOOT_SUFFIX
7881 7582 Points to the generated U-Boot extension. For example, ``u-boot.sb``
7882WORKDIR 7583 has a ``.sb`` extension.
7883 The pathname of the work directory in which the OpenEmbedded build 7584
7884 system builds a recipe. This directory is located within the 7585 The default U-Boot extension is ``.bin``
7885 ```TMPDIR`` <#var-TMPDIR>`__ directory structure and is specific to 7586
7886 the recipe being built and the system for which it is being built. 7587 UBOOT_TARGET
7887 7588 Specifies the target used for building U-Boot. The target is passed
7888 The ``WORKDIR`` directory is defined as follows: 7589 directly as part of the "make" command (e.g. SPL and AIS). If you do
7889 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 7590 not specifically set this variable, the OpenEmbedded build process
7890 The actual directory depends on several things: 7591 passes and uses "all" for the target during the U-Boot building
7891 7592 process.
7892 - TMPDIR 7593
7893 : The top-level build output directory 7594 UBOOT_SIGN_ENABLE
7894 - MULTIMACH_TARGET_SYS 7595 Enable signing of FIT image. The default value is "0".
7895 : The target system identifier 7596
7896 - PN 7597 UBOOT_SIGN_KEYDIR
7897 : The recipe name 7598 Location of the directory containing the RSA key and
7898 - EXTENDPE 7599 certificate used for signing FIT image.
7899 : The epoch - (if 7600
7900 PE 7601 UBOOT_SIGN_KEYNAME
7901 is not specified, which is usually the case for most recipes, then 7602 The name of keys used for signing U-boot FIT image stored in
7902 EXTENDPE 7603 :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt
7903 is blank) 7604 certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have
7904 - PV 7605 :term:`UBOOT_SIGN_KEYNAME` set to "dev".
7905 : The recipe version 7606
7906 - PR 7607 UNKNOWN_CONFIGURE_WHITELIST
7907 : The recipe revision 7608 Specifies a list of options that, if reported by the configure script
7908 7609 as being invalid, should not generate a warning during the
7909 As an example, assume a Source Directory top-level folder name 7610 :ref:`ref-tasks-configure` task. Normally, invalid
7910 ``poky``, a default Build Directory at ``poky/build``, and a 7611 configure options are simply not passed to the configure script (e.g.
7911 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 7612 should be removed from :term:`EXTRA_OECONF` or
7912 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 7613 :term:`PACKAGECONFIG_CONFARGS`).
7913 directory the build system uses to build the package would be as 7614 However, common options, for example, exist that are passed to all
7914 follows: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 7615 configure scripts at a class level that might not be valid for some
7915 7616 configure scripts. It follows that no benefit exists in seeing a
7916XSERVER 7617 warning about these options. For these cases, the options are added
7917 Specifies the packages that should be installed to provide an X 7618 to ``UNKNOWN_CONFIGURE_WHITELIST``.
7918 server and drivers for the current machine, assuming your image 7619
7919 directly includes ``packagegroup-core-x11-xserver`` or, perhaps 7620 The configure arguments check that uses
7920 indirectly, includes "x11-base" in 7621 ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the
7921 ```IMAGE_FEATURES`` <#var-IMAGE_FEATURES>`__. 7622 :ref:`insane <ref-classes-insane>` class and is only enabled if the
7922 7623 recipe inherits the :ref:`autotools <ref-classes-autotools>` class.
7923 The default value of ``XSERVER``, if not specified in the machine 7624
7924 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 7625 UPDATERCPN
7626 For recipes inheriting the
7627 :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN``
7628 specifies the package that contains the initscript that is enabled.
7629
7630 The default value is "${PN}". Given that almost all recipes that
7631 install initscripts package them in the main package for the recipe,
7632 you rarely need to set this variable in individual recipes.
7633
7634 UPSTREAM_CHECK_GITTAGREGEX
7635 You can perform a per-recipe check for what the latest upstream
7636 source code version is by calling ``bitbake -c checkpkg`` recipe. If
7637 the recipe source code is provided from Git repositories, the
7638 OpenEmbedded build system determines the latest upstream version by
7639 picking the latest tag from the list of all repository tags.
7640
7641 You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a
7642 regular expression to filter only the relevant tags should the
7643 default filter not work correctly. UPSTREAM_CHECK_GITTAGREGEX =
7644 "git_tag_regex"
7645
7646 UPSTREAM_CHECK_REGEX
7647 Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different
7648 regular expression instead of the default one when the package
7649 checking system is parsing the page found using
7650 :term:`UPSTREAM_CHECK_URI`.
7651 UPSTREAM_CHECK_REGEX = "package_regex"
7652
7653 UPSTREAM_CHECK_URI
7654 You can perform a per-recipe check for what the latest upstream
7655 source code version is by calling ``bitbake -c checkpkg`` recipe. If
7656 the source code is provided from tarballs, the latest version is
7657 determined by fetching the directory listing where the tarball is and
7658 attempting to find a later tarball. When this approach does not work,
7659 you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that
7660 contains the link to the latest tarball. UPSTREAM_CHECK_URI =
7661 "recipe_url"
7662
7663 USE_DEVFS
7664 Determines if ``devtmpfs`` is used for ``/dev`` population. The
7665 default value used for ``USE_DEVFS`` is "1" when no value is
7666 specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a
7667 statically populated ``/dev`` directory.
7668
7669 See the "`Selecting a Device
7670 Manager <&YOCTO_DOCS_DEV_URL;#selecting-dev-manager>`__" section in
7671 the Yocto Project Development Tasks Manual for information on how to
7672 use this variable.
7673
7674 USE_VT
7675 When using
7676 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__,
7677 determines whether or not to run a
7678 `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any
7679 virtual terminals in order to enable logging in through those
7680 terminals.
7681
7682 The default value used for ``USE_VT`` is "1" when no default value is
7683 specifically set. Typically, you would set ``USE_VT`` to "0" in the
7684 machine configuration file for machines that do not have a graphical
7685 display attached and therefore do not need virtual terminal
7686 functionality.
7687
7688 USER_CLASSES
7689 A list of classes to globally inherit. These classes are used by the
7690 OpenEmbedded build system to enable extra features (e.g.
7691 ``buildstats``, ``image-mklibs``, and so forth).
7692
7693 The default list is set in your ``local.conf`` file: USER_CLASSES ?=
7694 "buildstats image-mklibs image-prelink" For more information, see
7695 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`.
7696
7697 USERADD_ERROR_DYNAMIC
7698 If set to ``error``, forces the OpenEmbedded build system to produce
7699 an error if the user identification (``uid``) and group
7700 identification (``gid``) values are not defined in any of the files
7701 listed in :term:`USERADD_UID_TABLES` and
7702 :term:`USERADD_GID_TABLES`. If set to
7703 ``warn``, a warning will be issued instead.
7704
7705 The default behavior for the build system is to dynamically apply
7706 ``uid`` and ``gid`` values. Consequently, the
7707 ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan
7708 on using statically assigned ``gid`` and ``uid`` values, you should
7709 set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf``
7710 file as follows: USERADD_ERROR_DYNAMIC = "error" Overriding the
7711 default behavior implies you are going to also take steps to set
7712 static ``uid`` and ``gid`` values through use of the
7713 :term:`USERADDEXTENSION`,
7714 :term:`USERADD_UID_TABLES`, and
7715 :term:`USERADD_GID_TABLES` variables.
7716
7717 .. note::
7718
7719 There is a difference in behavior between setting
7720 USERADD_ERROR_DYNAMIC
7721 to
7722 error
7723 and setting it to
7724 warn
7725 . When it is set to
7726 warn
7727 , the build system will report a warning for every undefined
7728 uid
7729 and
7730 gid
7731 in any recipe. But when it is set to
7732 error
7733 , it will only report errors for recipes that are actually built.
7734 This saves you from having to add static IDs for recipes that you
7735 know will never be built.
7736
7737 USERADD_GID_TABLES
7738 Specifies a password file to use for obtaining static group
7739 identification (``gid``) values when the OpenEmbedded build system
7740 adds a group to the system during package installation.
7741
7742 When applying static group identification (``gid``) values, the
7743 OpenEmbedded build system looks in :term:`BBPATH` for a
7744 ``files/group`` file and then applies those ``uid`` values. Set the
7745 variable as follows in your ``local.conf`` file: USERADD_GID_TABLES =
7746 "files/group"
7747
7748 .. note::
7749
7750 Setting the
7751 USERADDEXTENSION
7752 variable to "useradd-staticids" causes the build system to use
7753 static
7754 gid
7755 values.
7756
7757 USERADD_PACKAGES
7758 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
7759 this variable specifies the individual packages within the recipe
7760 that require users and/or groups to be added.
7761
7762 You must set this variable if the recipe inherits the class. For
7763 example, the following enables adding a user for the main package in
7764 a recipe: USERADD_PACKAGES = "${PN}"
7765
7766 .. note::
7767
7768 It follows that if you are going to use the
7769 USERADD_PACKAGES
7770 variable, you need to set one or more of the
7771 USERADD_PARAM
7772 ,
7773 GROUPADD_PARAM
7774 , or
7775 GROUPMEMS_PARAM
7776 variables.
7777
7778 USERADD_PARAM
7779 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
7780 this variable specifies for a package what parameters should pass to
7781 the ``useradd`` command if you add a user to the system when the
7782 package is installed.
7783
7784 Here is an example from the ``dbus`` recipe: USERADD_PARAM_${PN} =
7785 "--system --home ${localstatedir}/lib/dbus \\ --no-create-home
7786 --shell /bin/false \\ --user-group messagebus" For information on the
7787 standard Linux shell command ``useradd``, see
7788 http://linux.die.net/man/8/useradd.
7789
7790 USERADD_UID_TABLES
7791 Specifies a password file to use for obtaining static user
7792 identification (``uid``) values when the OpenEmbedded build system
7793 adds a user to the system during package installation.
7794
7795 When applying static user identification (``uid``) values, the
7796 OpenEmbedded build system looks in :term:`BBPATH` for a
7797 ``files/passwd`` file and then applies those ``uid`` values. Set the
7798 variable as follows in your ``local.conf`` file: USERADD_UID_TABLES =
7799 "files/passwd"
7800
7801 .. note::
7802
7803 Setting the
7804 USERADDEXTENSION
7805 variable to "useradd-staticids" causes the build system to use
7806 static
7807 uid
7808 values.
7809
7810 USERADDEXTENSION
7811 When set to "useradd-staticids", causes the OpenEmbedded build system
7812 to base all user and group additions on a static ``passwd`` and
7813 ``group`` files found in :term:`BBPATH`.
7814
7815 To use static user identification (``uid``) and group identification
7816 (``gid``) values, set the variable as follows in your ``local.conf``
7817 file: USERADDEXTENSION = "useradd-staticids"
7818
7819 .. note::
7820
7821 Setting this variable to use static
7822 uid
7823 and
7824 gid
7825 values causes the OpenEmbedded build system to employ the
7826 useradd-staticids
7827 class.
7828
7829 If you use static ``uid`` and ``gid`` information, you must also
7830 specify the ``files/passwd`` and ``files/group`` files by setting the
7831 :term:`USERADD_UID_TABLES` and
7832 :term:`USERADD_GID_TABLES` variables.
7833 Additionally, you should also set the
7834 :term:`USERADD_ERROR_DYNAMIC` variable.
7835
7836 VOLATILE_LOG_DIR
7837 Specifies the persistence of the target's ``/var/log`` directory,
7838 which is used to house postinstall target log files.
7839
7840 By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the
7841 file is not persistent. You can override this setting by setting the
7842 variable to "no" to make the log directory persistent.
7843
7844 WARN_QA
7845 Specifies the quality assurance checks whose failures are reported as
7846 warnings by the OpenEmbedded build system. You set this variable in
7847 your distribution configuration file. For a list of the checks you
7848 can control with this variable, see the
7849 ":ref:`insane.bbclass <ref-classes-insane>`" section.
7850
7851 WKS_FILE_DEPENDS
7852 When placed in the recipe that builds your image, this variable lists
7853 build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only
7854 applicable when Wic images are active (i.e. when
7855 :term:`IMAGE_FSTYPES` contains entries related
7856 to Wic). If your recipe does not create Wic images, the variable has
7857 no effect.
7858
7859 The ``WKS_FILE_DEPENDS`` variable is similar to the
7860 :term:`DEPENDS` variable. When you use the variable in
7861 your recipe that builds the Wic image, dependencies you list in the
7862 ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable.
7863
7864 With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to
7865 specify a list of additional dependencies (e.g. native tools,
7866 bootloaders, and so forth), that are required to build Wic images.
7867 Following is an example: WKS_FILE_DEPENDS = "some-native-tool" In the
7868 previous example, some-native-tool would be replaced with an actual
7869 native tool on which the build would depend.
7870
7871 WKS_FILE
7872 Specifies the location of the Wic kickstart file that is used by the
7873 OpenEmbedded build system to create a partitioned image
7874 (image\ ``.wic``). For information on how to create a partitioned
7875 image, see the "`Creating Partitioned Images Using
7876 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__"
7877 section in the Yocto Project Development Tasks Manual. For details on
7878 the kickstart file format, see the "`OpenEmbedded Kickstart
7879 (``.wks``) Reference <#ref-kickstart>`__" Chapter.
7880
7881 WORKDIR
7882 The pathname of the work directory in which the OpenEmbedded build
7883 system builds a recipe. This directory is located within the
7884 :term:`TMPDIR` directory structure and is specific to
7885 the recipe being built and the system for which it is being built.
7886
7887 The ``WORKDIR`` directory is defined as follows:
7888 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
7889 The actual directory depends on several things:
7890
7891 - TMPDIR
7892 : The top-level build output directory
7893 - MULTIMACH_TARGET_SYS
7894 : The target system identifier
7895 - PN
7896 : The recipe name
7897 - EXTENDPE
7898 : The epoch - (if
7899 PE
7900 is not specified, which is usually the case for most recipes, then
7901 EXTENDPE
7902 is blank)
7903 - PV
7904 : The recipe version
7905 - PR
7906 : The recipe revision
7907
7908 As an example, assume a Source Directory top-level folder name
7909 ``poky``, a default Build Directory at ``poky/build``, and a
7910 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
7911 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
7912 directory the build system uses to build the package would be as
7913 follows: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
7914
7915 XSERVER
7916 Specifies the packages that should be installed to provide an X
7917 server and drivers for the current machine, assuming your image
7918 directly includes ``packagegroup-core-x11-xserver`` or, perhaps
7919 indirectly, includes "x11-base" in
7920 :term:`IMAGE_FEATURES`.
7921
7922 The default value of ``XSERVER``, if not specified in the machine
7923 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
7924