diff options
Diffstat (limited to 'documentation/ref-manual/variables.rst')
-rw-r--r-- | documentation/ref-manual/variables.rst | 8807 |
1 files changed, 8807 insertions, 0 deletions
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst new file mode 100644 index 0000000000..8c6cc46b6c --- /dev/null +++ b/documentation/ref-manual/variables.rst | |||
@@ -0,0 +1,8807 @@ | |||
1 | .. SPDX-License-Identifier: CC-BY-SA-2.0-UK | ||
2 | |||
3 | ****************** | ||
4 | Variables Glossary | ||
5 | ****************** | ||
6 | |||
7 | This chapter lists common variables used in the OpenEmbedded build | ||
8 | system and gives an overview of their function and contents. | ||
9 | |||
10 | :term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>` | ||
11 | :term:`D` :term:`E <EFI_PROVIDER>` :term:`F <FEATURE_PACKAGES>` | ||
12 | :term:`G <GCCPIE>` :term:`H <HOMEPAGE>` :term:`I <ICECC_DISABLED>` | ||
13 | :term:`K <KARCH>` :term:`L <LABELS>` :term:`M <MACHINE>` | ||
14 | :term:`N <NATIVELSBSTRING>` :term:`O <OBJCOPY>` :term:`P` | ||
15 | :term:`R <RANLIB>` :term:`S` :term:`T` | ||
16 | :term:`U <UBOOT_CONFIG>` :term:`V <VOLATILE_LOG_DIR>` | ||
17 | :term:`W <WARN_QA>` :term:`X <XSERVER>` | ||
18 | |||
19 | .. glossary:: | ||
20 | |||
21 | :term:`ABIEXTENSION` | ||
22 | Extension to the Application Binary Interface (ABI) field of the GNU | ||
23 | canonical architecture name (e.g. "eabi"). | ||
24 | |||
25 | ABI extensions are set in the machine include files. For example, the | ||
26 | ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the | ||
27 | following extension: | ||
28 | :: | ||
29 | |||
30 | ABIEXTENSION = "eabi" | ||
31 | |||
32 | :term:`ALLOW_EMPTY` | ||
33 | Specifies whether to produce an output package even if it is empty. | ||
34 | By default, BitBake does not produce empty packages. This default | ||
35 | behavior can cause issues when there is an | ||
36 | :term:`RDEPENDS` or some other hard runtime | ||
37 | requirement on the existence of the package. | ||
38 | |||
39 | Like all package-controlling variables, you must always use them in | ||
40 | conjunction with a package name override, as in: | ||
41 | :: | ||
42 | |||
43 | ALLOW_EMPTY_${PN} = "1" | ||
44 | ALLOW_EMPTY_${PN}-dev = "1" | ||
45 | ALLOW_EMPTY_${PN}-staticdev = "1" | ||
46 | |||
47 | :term:`ALTERNATIVE` | ||
48 | Lists commands in a package that need an alternative binary naming | ||
49 | scheme. Sometimes the same command is provided in multiple packages. | ||
50 | When this occurs, the OpenEmbedded build system needs to use the | ||
51 | alternatives system to create a different binary naming scheme so the | ||
52 | commands can co-exist. | ||
53 | |||
54 | To use the variable, list out the package's commands that also exist | ||
55 | as part of another package. For example, if the ``busybox`` package | ||
56 | has four commands that also exist as part of another package, you | ||
57 | identify them as follows: | ||
58 | :: | ||
59 | |||
60 | ALTERNATIVE_busybox = "sh sed test bracket" | ||
61 | |||
62 | For more information on the alternatives system, see the | ||
63 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
64 | section. | ||
65 | |||
66 | :term:`ALTERNATIVE_LINK_NAME` | ||
67 | Used by the alternatives system to map duplicated commands to actual | ||
68 | locations. For example, if the ``bracket`` command provided by the | ||
69 | ``busybox`` package is duplicated through another package, you must | ||
70 | use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual | ||
71 | location: | ||
72 | :: | ||
73 | |||
74 | ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" | ||
75 | |||
76 | In this example, the binary for the ``bracket`` command (i.e. ``[``) | ||
77 | from the ``busybox`` package resides in ``/usr/bin/``. | ||
78 | |||
79 | .. note:: | ||
80 | |||
81 | If ``ALTERNATIVE_LINK_NAME`` is not defined, it defaults to ``${bindir}/name``. | ||
82 | |||
83 | For more information on the alternatives system, see the | ||
84 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
85 | section. | ||
86 | |||
87 | :term:`ALTERNATIVE_PRIORITY` | ||
88 | Used by the alternatives system to create default priorities for | ||
89 | duplicated commands. You can use the variable to create a single | ||
90 | default regardless of the command name or package, a default for | ||
91 | specific duplicated commands regardless of the package, or a default | ||
92 | for specific commands tied to particular packages. Here are the | ||
93 | available syntax forms: | ||
94 | :: | ||
95 | |||
96 | ALTERNATIVE_PRIORITY = "priority" | ||
97 | ALTERNATIVE_PRIORITY[name] = "priority" | ||
98 | ALTERNATIVE_PRIORITY_pkg[name] = "priority" | ||
99 | |||
100 | For more information on the alternatives system, see the | ||
101 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
102 | section. | ||
103 | |||
104 | :term:`ALTERNATIVE_TARGET` | ||
105 | Used by the alternatives system to create default link locations for | ||
106 | duplicated commands. You can use the variable to create a single | ||
107 | default location for all duplicated commands regardless of the | ||
108 | command name or package, a default for specific duplicated commands | ||
109 | regardless of the package, or a default for specific commands tied to | ||
110 | particular packages. Here are the available syntax forms: | ||
111 | :: | ||
112 | |||
113 | ALTERNATIVE_TARGET = "target" | ||
114 | ALTERNATIVE_TARGET[name] = "target" | ||
115 | ALTERNATIVE_TARGET_pkg[name] = "target" | ||
116 | |||
117 | .. note:: | ||
118 | |||
119 | If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value | ||
120 | from the :term:`ALTERNATIVE_LINK_NAME` variable. | ||
121 | |||
122 | If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the | ||
123 | same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" | ||
124 | appended to it. | ||
125 | |||
126 | Finally, if the file referenced has not been renamed, the | ||
127 | alternatives system will rename it to avoid the need to rename | ||
128 | alternative files in the :ref:`ref-tasks-install` | ||
129 | task while retaining support for the command if necessary. | ||
130 | |||
131 | For more information on the alternatives system, see the | ||
132 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | ||
133 | section. | ||
134 | |||
135 | :term:`ANY_OF_DISTRO_FEATURES` | ||
136 | When inheriting the | ||
137 | :ref:`features_check <ref-classes-features_check>` | ||
138 | class, this variable identifies a list of distribution features where | ||
139 | at least one must be enabled in the current configuration in order | ||
140 | for the OpenEmbedded build system to build the recipe. In other words, | ||
141 | if none of the features listed in ``ANY_OF_DISTRO_FEATURES`` | ||
142 | appear in ``DISTRO_FEATURES`` within the current configuration, then | ||
143 | the recipe will be skipped, and if the build system attempts to build | ||
144 | the recipe then an error will be triggered. | ||
145 | |||
146 | |||
147 | :term:`APPEND` | ||
148 | An override list of append strings for each target specified with | ||
149 | :term:`LABELS`. | ||
150 | |||
151 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
152 | information on how this variable is used. | ||
153 | |||
154 | :term:`AR` | ||
155 | The minimal command and arguments used to run ``ar``. | ||
156 | |||
157 | :term:`ARCHIVER_MODE` | ||
158 | When used with the :ref:`archiver <ref-classes-archiver>` class, | ||
159 | determines the type of information used to create a released archive. | ||
160 | You can use this variable to create archives of patched source, | ||
161 | original source, configured source, and so forth by employing the | ||
162 | following variable flags (varflags): | ||
163 | :: | ||
164 | |||
165 | ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. | ||
166 | ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. | ||
167 | ARCHIVER_MODE[src] = "configured" # Uses configured source files. | ||
168 | ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch. | ||
169 | ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff. | ||
170 | ARCHIVER_MODE[dumpdata] = "1" # Uses environment data. | ||
171 | ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files. | ||
172 | ARCHIVER_MODE[srpm] = "1" # Uses RPM package files. | ||
173 | |||
174 | For information on how the variable works, see the | ||
175 | ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`. | ||
176 | |||
177 | :term:`AS` | ||
178 | Minimal command and arguments needed to run the assembler. | ||
179 | |||
180 | :term:`ASSUME_PROVIDED` | ||
181 | Lists recipe names (:term:`PN` values) BitBake does not | ||
182 | attempt to build. Instead, BitBake assumes these recipes have already | ||
183 | been built. | ||
184 | |||
185 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | ||
186 | tools that should not be built. An example is ``git-native``, which | ||
187 | when specified, allows for the Git binary from the host to be used | ||
188 | rather than building ``git-native``. | ||
189 | |||
190 | :term:`ASSUME_SHLIBS` | ||
191 | Provides additional ``shlibs`` provider mapping information, which | ||
192 | adds to or overwrites the information provided automatically by the | ||
193 | system. Separate multiple entries using spaces. | ||
194 | |||
195 | As an example, use the following form to add an ``shlib`` provider of | ||
196 | shlibname in packagename with the optional version: | ||
197 | :: | ||
198 | |||
199 | shlibname:packagename[_version] | ||
200 | |||
201 | Here is an example that adds a shared library named ``libEGL.so.1`` | ||
202 | as being provided by the ``libegl-implementation`` package: | ||
203 | :: | ||
204 | |||
205 | ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" | ||
206 | |||
207 | :term:`AUTHOR` | ||
208 | The email address used to contact the original author or authors in | ||
209 | order to send patches and forward bugs. | ||
210 | |||
211 | :term:`AUTO_LIBNAME_PKGS` | ||
212 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
213 | which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which | ||
214 | packages should be checked for libraries and renamed according to | ||
215 | Debian library package naming. | ||
216 | |||
217 | The default value is "${PACKAGES}", which causes the debian class to | ||
218 | act on all packages that are explicitly generated by the recipe. | ||
219 | |||
220 | :term:`AUTO_SYSLINUXMENU` | ||
221 | Enables creating an automatic menu for the syslinux bootloader. You | ||
222 | must set this variable in your recipe. The | ||
223 | :ref:`syslinux <ref-classes-syslinux>` class checks this variable. | ||
224 | |||
225 | :term:`AUTOREV` | ||
226 | When ``SRCREV`` is set to the value of this variable, it specifies to | ||
227 | use the latest source revision in the repository. Here is an example: | ||
228 | :: | ||
229 | |||
230 | SRCREV = "${AUTOREV}" | ||
231 | |||
232 | If you use the previous statement to retrieve the latest version of | ||
233 | software, you need to be sure :term:`PV` contains | ||
234 | ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you | ||
235 | have a kernel recipe that inherits the | ||
236 | :ref:`kernel <ref-classes-kernel>` class and you use the previous | ||
237 | statement. In this example, ``${SRCPV}`` does not automatically get | ||
238 | into ``PV``. Consequently, you need to change ``PV`` in your recipe | ||
239 | so that it does contain ``${SRCPV}``. | ||
240 | |||
241 | For more information see the | ||
242 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | ||
243 | section in the Yocto Project Development Tasks Manual. | ||
244 | |||
245 | :term:`AVAILABLE_LICENSES` | ||
246 | List of licenses found in the directories specified by | ||
247 | :term:`COMMON_LICENSE_DIR` and | ||
248 | :term:`LICENSE_PATH`. | ||
249 | |||
250 | .. note:: | ||
251 | |||
252 | It is assumed that all changes to ``COMMON_LICENSE_DIR`` and | ||
253 | ``LICENSE_PATH`` have been done before ``AVAILABLE_LICENSES`` | ||
254 | is defined (in :ref:`ref-classes-license`). | ||
255 | |||
256 | :term:`AVAILTUNES` | ||
257 | The list of defined CPU and Application Binary Interface (ABI) | ||
258 | tunings (i.e. "tunes") available for use by the OpenEmbedded build | ||
259 | system. | ||
260 | |||
261 | The list simply presents the tunes that are available. Not all tunes | ||
262 | may be compatible with a particular machine configuration, or with | ||
263 | each other in a | ||
264 | :ref:`Multilib <dev-manual/common-tasks:combining multiple versions of library files into one image>` | ||
265 | configuration. | ||
266 | |||
267 | To add a tune to the list, be sure to append it with spaces using the | ||
268 | "+=" BitBake operator. Do not simply replace the list by using the | ||
269 | "=" operator. See the | ||
270 | ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake | ||
271 | User Manual for more information. | ||
272 | |||
273 | :term:`B` | ||
274 | The directory within the :term:`Build Directory` in | ||
275 | which the OpenEmbedded build system places generated objects during a | ||
276 | recipe's build process. By default, this directory is the same as the | ||
277 | :term:`S` directory, which is defined as: | ||
278 | :: | ||
279 | |||
280 | S = "${WORKDIR}/${BP}" | ||
281 | |||
282 | You can separate the (``S``) directory and the directory pointed to | ||
283 | by the ``B`` variable. Most Autotools-based recipes support | ||
284 | separating these directories. The build system defaults to using | ||
285 | separate directories for ``gcc`` and some kernel recipes. | ||
286 | |||
287 | :term:`BAD_RECOMMENDATIONS` | ||
288 | Lists "recommended-only" packages to not install. Recommended-only | ||
289 | packages are packages installed only through the | ||
290 | :term:`RRECOMMENDS` variable. You can prevent any | ||
291 | of these "recommended" packages from being installed by listing them | ||
292 | with the ``BAD_RECOMMENDATIONS`` variable: | ||
293 | :: | ||
294 | |||
295 | BAD_RECOMMENDATIONS = "package_name package_name package_name ..." | ||
296 | |||
297 | You can set this variable globally in your ``local.conf`` file or you | ||
298 | can attach it to a specific image recipe by using the recipe name | ||
299 | override: | ||
300 | :: | ||
301 | |||
302 | BAD_RECOMMENDATIONS_pn-target_image = "package_name" | ||
303 | |||
304 | It is important to realize that if you choose to not install packages | ||
305 | using this variable and some other packages are dependent on them | ||
306 | (i.e. listed in a recipe's :term:`RDEPENDS` | ||
307 | variable), the OpenEmbedded build system ignores your request and | ||
308 | will install the packages to avoid dependency errors. | ||
309 | |||
310 | Support for this variable exists only when using the IPK and RPM | ||
311 | packaging backend. Support does not exist for DEB. | ||
312 | |||
313 | See the :term:`NO_RECOMMENDATIONS` and the | ||
314 | :term:`PACKAGE_EXCLUDE` variables for related | ||
315 | information. | ||
316 | |||
317 | :term:`BASE_LIB` | ||
318 | The library directory name for the CPU or Application Binary | ||
319 | Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib | ||
320 | context. See the ":ref:`dev-manual/common-tasks:combining multiple versions of library files into one image`" | ||
321 | section in the Yocto Project Development Tasks Manual for information | ||
322 | on Multilib. | ||
323 | |||
324 | The ``BASE_LIB`` variable is defined in the machine include files in | ||
325 | the :term:`Source Directory`. If Multilib is not | ||
326 | being used, the value defaults to "lib". | ||
327 | |||
328 | :term:`BASE_WORKDIR` | ||
329 | Points to the base of the work directory for all recipes. The default | ||
330 | value is "${TMPDIR}/work". | ||
331 | |||
332 | :term:`BB_ALLOWED_NETWORKS` | ||
333 | Specifies a space-delimited list of hosts that the fetcher is allowed | ||
334 | to use to obtain the required source code. Following are | ||
335 | considerations surrounding this variable: | ||
336 | |||
337 | - This host list is only used if ``BB_NO_NETWORK`` is either not set | ||
338 | or set to "0". | ||
339 | |||
340 | - Limited support for wildcard matching against the beginning of | ||
341 | host names exists. For example, the following setting matches | ||
342 | ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. | ||
343 | :: | ||
344 | |||
345 | BB_ALLOWED_NETWORKS = "*.gnu.org" | ||
346 | |||
347 | .. note:: | ||
348 | |||
349 | The use of the "``*``" character only works at the beginning of | ||
350 | a host name and it must be isolated from the remainder of the | ||
351 | host name. You cannot use the wildcard character in any other | ||
352 | location of the name or combined with the front part of the | ||
353 | name. | ||
354 | |||
355 | For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` | ||
356 | is not. | ||
357 | |||
358 | - Mirrors not in the host list are skipped and logged in debug. | ||
359 | |||
360 | - Attempts to access networks not in the host list cause a failure. | ||
361 | |||
362 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | ||
363 | :term:`PREMIRRORS` is very useful. Adding the host | ||
364 | you want to use to ``PREMIRRORS`` results in the source code being | ||
365 | fetched from an allowed location and avoids raising an error when a | ||
366 | host that is not allowed is in a :term:`SRC_URI` | ||
367 | statement. This is because the fetcher does not attempt to use the | ||
368 | host listed in ``SRC_URI`` after a successful fetch from the | ||
369 | ``PREMIRRORS`` occurs. | ||
370 | |||
371 | :term:`BB_DANGLINGAPPENDS_WARNONLY` | ||
372 | Defines how BitBake handles situations where an append file | ||
373 | (``.bbappend``) has no corresponding recipe file (``.bb``). This | ||
374 | condition often occurs when layers get out of sync (e.g. ``oe-core`` | ||
375 | bumps a recipe version and the old recipe no longer exists and the | ||
376 | other layer has not been updated to the new version of the recipe | ||
377 | yet). | ||
378 | |||
379 | The default fatal behavior is safest because it is the sane reaction | ||
380 | given something is out of sync. It is important to realize when your | ||
381 | changes are no longer being applied. | ||
382 | |||
383 | You can change the default behavior by setting this variable to "1", | ||
384 | "yes", or "true" in your ``local.conf`` file, which is located in the | ||
385 | :term:`Build Directory`: Here is an example: | ||
386 | :: | ||
387 | |||
388 | BB_DANGLINGAPPENDS_WARNONLY = "1" | ||
389 | |||
390 | :term:`BB_DISKMON_DIRS` | ||
391 | Monitors disk space and available inodes during the build and allows | ||
392 | you to control the build based on these parameters. | ||
393 | |||
394 | Disk space monitoring is disabled by default. To enable monitoring, | ||
395 | add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file | ||
396 | found in the :term:`Build Directory`. Use the | ||
397 | following form: | ||
398 | |||
399 | .. code-block:: none | ||
400 | |||
401 | BB_DISKMON_DIRS = "action,dir,threshold [...]" | ||
402 | |||
403 | where: | ||
404 | |||
405 | action is: | ||
406 | ABORT: Immediately abort the build when | ||
407 | a threshold is broken. | ||
408 | STOPTASKS: Stop the build after the currently | ||
409 | executing tasks have finished when | ||
410 | a threshold is broken. | ||
411 | WARN: Issue a warning but continue the | ||
412 | build when a threshold is broken. | ||
413 | Subsequent warnings are issued as | ||
414 | defined by the BB_DISKMON_WARNINTERVAL | ||
415 | variable, which must be defined in | ||
416 | the conf/local.conf file. | ||
417 | |||
418 | dir is: | ||
419 | Any directory you choose. You can specify one or | ||
420 | more directories to monitor by separating the | ||
421 | groupings with a space. If two directories are | ||
422 | on the same device, only the first directory | ||
423 | is monitored. | ||
424 | |||
425 | threshold is: | ||
426 | Either the minimum available disk space, | ||
427 | the minimum number of free inodes, or | ||
428 | both. You must specify at least one. To | ||
429 | omit one or the other, simply omit the value. | ||
430 | Specify the threshold using G, M, K for Gbytes, | ||
431 | Mbytes, and Kbytes, respectively. If you do | ||
432 | not specify G, M, or K, Kbytes is assumed by | ||
433 | default. Do not use GB, MB, or KB. | ||
434 | |||
435 | Here are some examples: | ||
436 | :: | ||
437 | |||
438 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | ||
439 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | ||
440 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" | ||
441 | |||
442 | The first example works only if you also provide the | ||
443 | :term:`BB_DISKMON_WARNINTERVAL` | ||
444 | variable in the ``conf/local.conf``. This example causes the build | ||
445 | system to immediately abort when either the disk space in | ||
446 | ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops | ||
447 | below 100 Kbytes. Because two directories are provided with the | ||
448 | variable, the build system also issue a warning when the disk space | ||
449 | in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number | ||
450 | of free inodes drops below 100 Kbytes. Subsequent warnings are issued | ||
451 | during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` | ||
452 | variable. | ||
453 | |||
454 | The second example stops the build after all currently executing | ||
455 | tasks complete when the minimum disk space in the ``${TMPDIR}`` | ||
456 | directory drops below 1 Gbyte. No disk monitoring occurs for the free | ||
457 | inodes in this case. | ||
458 | |||
459 | The final example immediately aborts the build when the number of | ||
460 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No | ||
461 | disk space monitoring for the directory itself occurs in this case. | ||
462 | |||
463 | :term:`BB_DISKMON_WARNINTERVAL` | ||
464 | Defines the disk space and free inode warning intervals. To set these | ||
465 | intervals, define the variable in your ``conf/local.conf`` file in | ||
466 | the :term:`Build Directory`. | ||
467 | |||
468 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | ||
469 | must also use the :term:`BB_DISKMON_DIRS` | ||
470 | variable and define its action as "WARN". During the build, | ||
471 | subsequent warnings are issued each time disk space or number of free | ||
472 | inodes further reduces by the respective interval. | ||
473 | |||
474 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | ||
475 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | ||
476 | monitoring interval defaults to the following: | ||
477 | :: | ||
478 | |||
479 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
480 | |||
481 | When specifying the variable in your configuration file, use the | ||
482 | following form: | ||
483 | |||
484 | .. code-block:: none | ||
485 | |||
486 | BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval" | ||
487 | |||
488 | where: | ||
489 | |||
490 | disk_space_interval is: | ||
491 | An interval of memory expressed in either | ||
492 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
493 | respectively. You cannot use GB, MB, or KB. | ||
494 | |||
495 | disk_inode_interval is: | ||
496 | An interval of free inodes expressed in either | ||
497 | G, M, or K for Gbytes, Mbytes, or Kbytes, | ||
498 | respectively. You cannot use GB, MB, or KB. | ||
499 | |||
500 | Here is an example: | ||
501 | :: | ||
502 | |||
503 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | ||
504 | BB_DISKMON_WARNINTERVAL = "50M,5K" | ||
505 | |||
506 | These variables cause the | ||
507 | OpenEmbedded build system to issue subsequent warnings each time the | ||
508 | available disk space further reduces by 50 Mbytes or the number of | ||
509 | free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` | ||
510 | directory. Subsequent warnings based on the interval occur each time | ||
511 | a respective interval is reached beyond the initial warning (i.e. 1 | ||
512 | Gbytes and 100 Kbytes). | ||
513 | |||
514 | :term:`BB_GENERATE_MIRROR_TARBALLS` | ||
515 | Causes tarballs of the source control repositories (e.g. Git | ||
516 | repositories), including metadata, to be placed in the | ||
517 | :term:`DL_DIR` directory. | ||
518 | |||
519 | For performance reasons, creating and placing tarballs of these | ||
520 | repositories is not the default action by the OpenEmbedded build | ||
521 | system. | ||
522 | :: | ||
523 | |||
524 | BB_GENERATE_MIRROR_TARBALLS = "1" | ||
525 | |||
526 | Set this variable in your | ||
527 | ``local.conf`` file in the :term:`Build Directory`. | ||
528 | |||
529 | Once you have the tarballs containing your source files, you can | ||
530 | clean up your ``DL_DIR`` directory by deleting any Git or other | ||
531 | source control work directories. | ||
532 | |||
533 | :term:`BB_NUMBER_THREADS` | ||
534 | The maximum number of tasks BitBake should run in parallel at any one | ||
535 | time. The OpenEmbedded build system automatically configures this | ||
536 | variable to be equal to the number of cores on the build system. For | ||
537 | example, a system with a dual core processor that also uses | ||
538 | hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default | ||
539 | to "4". | ||
540 | |||
541 | For single socket systems (i.e. one CPU), you should not have to | ||
542 | override this variable to gain optimal parallelism during builds. | ||
543 | However, if you have very large systems that employ multiple physical | ||
544 | CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable | ||
545 | is not set higher than "20". | ||
546 | |||
547 | For more information on speeding up builds, see the | ||
548 | ":ref:`dev-manual/common-tasks:speeding up a build`" | ||
549 | section in the Yocto Project Development Tasks Manual. | ||
550 | |||
551 | :term:`BB_SERVER_TIMEOUT` | ||
552 | Specifies the time (in seconds) after which to unload the BitBake | ||
553 | server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how | ||
554 | long the BitBake server stays resident between invocations. | ||
555 | |||
556 | For example, the following statement in your ``local.conf`` file | ||
557 | instructs the server to be unloaded after 20 seconds of inactivity: | ||
558 | :: | ||
559 | |||
560 | BB_SERVER_TIMEOUT = "20" | ||
561 | |||
562 | If you want the server to never be unloaded, | ||
563 | set ``BB_SERVER_TIMEOUT`` to "-1". | ||
564 | |||
565 | :term:`BBCLASSEXTEND` | ||
566 | Allows you to extend a recipe so that it builds variants of the | ||
567 | software. Common variants for recipes exist such as "natives" like | ||
568 | ``quilt-native``, which is a copy of Quilt built to run on the build | ||
569 | system; "crosses" such as ``gcc-cross``, which is a compiler built to | ||
570 | run on the build machine but produces binaries that run on the target | ||
571 | :term:`MACHINE`; "nativesdk", which targets the SDK | ||
572 | machine instead of ``MACHINE``; and "mulitlibs" in the form | ||
573 | "``multilib:``\ multilib_name". | ||
574 | |||
575 | To build a different variant of the recipe with a minimal amount of | ||
576 | code, it usually is as simple as adding the following to your recipe: | ||
577 | :: | ||
578 | |||
579 | BBCLASSEXTEND =+ "native nativesdk" | ||
580 | BBCLASSEXTEND =+ "multilib:multilib_name" | ||
581 | |||
582 | .. note:: | ||
583 | |||
584 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | ||
585 | variants by rewriting variable values and applying overrides such | ||
586 | as ``_class-native``. For example, to generate a native version of | ||
587 | a recipe, a :term:`DEPENDS` on "foo" is rewritten | ||
588 | to a ``DEPENDS`` on "foo-native". | ||
589 | |||
590 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | ||
591 | Parsing once adds some limitations. For example, it is not | ||
592 | possible to include a different file depending on the variant, | ||
593 | since ``include`` statements are processed when the recipe is | ||
594 | parsed. | ||
595 | |||
596 | :term:`BBFILE_COLLECTIONS` | ||
597 | Lists the names of configured layers. These names are used to find | ||
598 | the other ``BBFILE_*`` variables. Typically, each layer will append | ||
599 | its name to this variable in its ``conf/layer.conf`` file. | ||
600 | |||
601 | :term:`BBFILE_PATTERN` | ||
602 | Variable that expands to match files from | ||
603 | :term:`BBFILES` in a particular layer. This variable | ||
604 | is used in the ``conf/layer.conf`` file and must be suffixed with the | ||
605 | name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). | ||
606 | |||
607 | :term:`BBFILE_PRIORITY` | ||
608 | Assigns the priority for recipe files in each layer. | ||
609 | |||
610 | This variable is useful in situations where the same recipe appears | ||
611 | in more than one layer. Setting this variable allows you to | ||
612 | prioritize a layer against other layers that contain the same recipe | ||
613 | - effectively letting you control the precedence for the multiple | ||
614 | layers. The precedence established through this variable stands | ||
615 | regardless of a recipe's version (:term:`PV` variable). For | ||
616 | example, a layer that has a recipe with a higher ``PV`` value but for | ||
617 | which the ``BBFILE_PRIORITY`` is set to have a lower precedence still | ||
618 | has a lower precedence. | ||
619 | |||
620 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | ||
621 | higher precedence. For example, the value 6 has a higher precedence | ||
622 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | ||
623 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | ||
624 | for more information. The default priority, if unspecified for a | ||
625 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | ||
626 | if no priorities are defined). | ||
627 | |||
628 | .. tip:: | ||
629 | |||
630 | You can use the command ``bitbake-layers show-layers`` | ||
631 | to list all configured layers along with their priorities. | ||
632 | |||
633 | :term:`BBFILES` | ||
634 | A space-separated list of recipe files BitBake uses to build | ||
635 | software. | ||
636 | |||
637 | When specifying recipe files, you can pattern match using Python's | ||
638 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax. | ||
639 | For details on the syntax, see the documentation by following the | ||
640 | previous link. | ||
641 | |||
642 | :term:`BBFILES_DYNAMIC` | ||
643 | Activates content when identified layers are present. You identify | ||
644 | the layers by the collections that the layers define. | ||
645 | |||
646 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files | ||
647 | whose corresponding ``.bb`` file is in a layer that attempts to | ||
648 | modify other layers through ``.bbappend`` but does not want to | ||
649 | introduce a hard dependency on those other layers. | ||
650 | |||
651 | Use the following form for ``BBFILES_DYNAMIC``: | ||
652 | collection_name:filename_pattern The following example identifies two | ||
653 | collection names and two filename patterns: | ||
654 | :: | ||
655 | |||
656 | BBFILES_DYNAMIC += " \ | ||
657 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | ||
658 | core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \ | ||
659 | " | ||
660 | |||
661 | This next example shows an error message that occurs because invalid | ||
662 | entries are found, which cause parsing to abort: | ||
663 | |||
664 | .. code-block:: none | ||
665 | |||
666 | ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not: | ||
667 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | ||
668 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | ||
669 | |||
670 | :term:`BBINCLUDELOGS` | ||
671 | Variable that controls how BitBake displays logs on build failure. | ||
672 | |||
673 | :term:`BBINCLUDELOGS_LINES` | ||
674 | If :term:`BBINCLUDELOGS` is set, specifies the | ||
675 | maximum number of lines from the task log file to print when | ||
676 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | ||
677 | the entire log is printed. | ||
678 | |||
679 | :term:`BBLAYERS` | ||
680 | Lists the layers to enable during the build. This variable is defined | ||
681 | in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. | ||
682 | Here is an example: | ||
683 | :: | ||
684 | |||
685 | BBLAYERS = " \ | ||
686 | /home/scottrif/poky/meta \ | ||
687 | /home/scottrif/poky/meta-poky \ | ||
688 | /home/scottrif/poky/meta-yocto-bsp \ | ||
689 | /home/scottrif/poky/meta-mykernel \ | ||
690 | " | ||
691 | |||
692 | This example enables four layers, one of which is a custom, | ||
693 | user-defined layer named ``meta-mykernel``. | ||
694 | |||
695 | :term:`BBMASK` | ||
696 | Prevents BitBake from processing recipes and recipe append files. | ||
697 | |||
698 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | ||
699 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | ||
700 | files that match any of the expressions. It is as if BitBake does not | ||
701 | see them at all. Consequently, matching files are not parsed or | ||
702 | otherwise used by BitBake. | ||
703 | |||
704 | The values you provide are passed to Python's regular expression | ||
705 | compiler. Consequently, the syntax follows Python's Regular | ||
706 | Expression (re) syntax. The expressions are compared against the full | ||
707 | paths to the files. For complete syntax information, see Python's | ||
708 | documentation at https://docs.python.org/3/library/re.html#regular-expression-syntax. | ||
709 | |||
710 | The following example uses a complete regular expression to tell | ||
711 | BitBake to ignore all recipe and recipe append files in the | ||
712 | ``meta-ti/recipes-misc/`` directory: | ||
713 | :: | ||
714 | |||
715 | BBMASK = "meta-ti/recipes-misc/" | ||
716 | |||
717 | If you want to mask out multiple directories or recipes, you can | ||
718 | specify multiple regular expression fragments. This next example | ||
719 | masks out multiple directories and individual recipes: :: | ||
720 | |||
721 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | ||
722 | BBMASK += "/meta-oe/recipes-support/" | ||
723 | BBMASK += "/meta-foo/.*/openldap" | ||
724 | BBMASK += "opencv.*\.bbappend" | ||
725 | BBMASK += "lzma" | ||
726 | |||
727 | .. note:: | ||
728 | |||
729 | When specifying a directory name, use the trailing slash character | ||
730 | to ensure you match just that directory name. | ||
731 | |||
732 | :term:`BBMULTICONFIG` | ||
733 | Specifies each additional separate configuration when you are | ||
734 | building targets with multiple configurations. Use this variable in | ||
735 | your ``conf/local.conf`` configuration file. Specify a | ||
736 | multiconfigname for each configuration file you are using. For | ||
737 | example, the following line specifies three configuration files: | ||
738 | :: | ||
739 | |||
740 | BBMULTICONFIG = "configA configB configC" | ||
741 | |||
742 | Each configuration file you | ||
743 | use must reside in the :term:`Build Directory` | ||
744 | ``conf/multiconfig`` directory (e.g. | ||
745 | build_directory\ ``/conf/multiconfig/configA.conf``). | ||
746 | |||
747 | For information on how to use ``BBMULTICONFIG`` in an environment | ||
748 | that supports building targets with multiple configurations, see the | ||
749 | ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" | ||
750 | section in the Yocto Project Development Tasks Manual. | ||
751 | |||
752 | :term:`BBPATH` | ||
753 | Used by BitBake to locate ``.bbclass`` and configuration files. This | ||
754 | variable is analogous to the ``PATH`` variable. | ||
755 | |||
756 | .. note:: | ||
757 | |||
758 | If you run BitBake from a directory outside of the | ||
759 | Build Directory | ||
760 | , you must be sure to set | ||
761 | BBPATH | ||
762 | to point to the Build Directory. Set the variable as you would any | ||
763 | environment variable and then run BitBake: | ||
764 | :: | ||
765 | |||
766 | $ BBPATH = "build_directory" | ||
767 | $ export BBPATH | ||
768 | $ bitbake target | ||
769 | |||
770 | |||
771 | :term:`BBSERVER` | ||
772 | If defined in the BitBake environment, ``BBSERVER`` points to the | ||
773 | BitBake remote server. | ||
774 | |||
775 | Use the following format to export the variable to the BitBake | ||
776 | environment: | ||
777 | :: | ||
778 | |||
779 | export BBSERVER=localhost:$port | ||
780 | |||
781 | By default, ``BBSERVER`` also appears in | ||
782 | :term:`bitbake:BB_HASHBASE_WHITELIST`. | ||
783 | Consequently, ``BBSERVER`` is excluded from checksum and dependency | ||
784 | data. | ||
785 | |||
786 | :term:`BINCONFIG` | ||
787 | When inheriting the | ||
788 | :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, | ||
789 | this variable specifies binary configuration scripts to disable in | ||
790 | favor of using ``pkg-config`` to query the information. The | ||
791 | ``binconfig-disabled`` class will modify the specified scripts to | ||
792 | return an error so that calls to them can be easily found and | ||
793 | replaced. | ||
794 | |||
795 | To add multiple scripts, separate them by spaces. Here is an example | ||
796 | from the ``libpng`` recipe: | ||
797 | :: | ||
798 | |||
799 | BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" | ||
800 | |||
801 | :term:`BINCONFIG_GLOB` | ||
802 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | ||
803 | this variable specifies a wildcard for configuration scripts that | ||
804 | need editing. The scripts are edited to correct any paths that have | ||
805 | been set up during compilation so that they are correct for use when | ||
806 | installed into the sysroot and called by the build processes of other | ||
807 | recipes. | ||
808 | |||
809 | .. note:: | ||
810 | |||
811 | The ``BINCONFIG_GLOB`` variable uses | ||
812 | `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, | ||
813 | which is recognition and expansion of wildcards during pattern | ||
814 | matching. Shell globbing is very similar to | ||
815 | `fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__ | ||
816 | and `glob <https://docs.python.org/3/library/glob.html>`__. | ||
817 | |||
818 | For more information on how this variable works, see | ||
819 | ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. | ||
820 | You can also find general | ||
821 | information on the class in the | ||
822 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | ||
823 | |||
824 | :term:`BP` | ||
825 | The base recipe name and version but without any special recipe name | ||
826 | suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is | ||
827 | comprised of the following: | ||
828 | :: | ||
829 | |||
830 | ${BPN}-${PV} | ||
831 | |||
832 | :term:`BPN` | ||
833 | This variable is a version of the :term:`PN` variable with | ||
834 | common prefixes and suffixes removed, such as ``nativesdk-``, | ||
835 | ``-cross``, ``-native``, and multilib's ``lib64-`` and ``lib32-``. | ||
836 | The exact lists of prefixes and suffixes removed are specified by the | ||
837 | :term:`MLPREFIX` and | ||
838 | :term:`SPECIAL_PKGSUFFIX` variables, | ||
839 | respectively. | ||
840 | |||
841 | :term:`BUGTRACKER` | ||
842 | Specifies a URL for an upstream bug tracking website for a recipe. | ||
843 | The OpenEmbedded build system does not use this variable. Rather, the | ||
844 | variable is a useful pointer in case a bug in the software being | ||
845 | built needs to be manually reported. | ||
846 | |||
847 | :term:`BUILD_ARCH` | ||
848 | Specifies the architecture of the build host (e.g. ``i686``). The | ||
849 | OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the | ||
850 | machine name reported by the ``uname`` command. | ||
851 | |||
852 | :term:`BUILD_AS_ARCH` | ||
853 | Specifies the architecture-specific assembler flags for the build | ||
854 | host. By default, the value of ``BUILD_AS_ARCH`` is empty. | ||
855 | |||
856 | :term:`BUILD_CC_ARCH` | ||
857 | Specifies the architecture-specific C compiler flags for the build | ||
858 | host. By default, the value of ``BUILD_CC_ARCH`` is empty. | ||
859 | |||
860 | :term:`BUILD_CCLD` | ||
861 | Specifies the linker command to be used for the build host when the C | ||
862 | compiler is being used as the linker. By default, ``BUILD_CCLD`` | ||
863 | points to GCC and passes as arguments the value of | ||
864 | :term:`BUILD_CC_ARCH`, assuming | ||
865 | ``BUILD_CC_ARCH`` is set. | ||
866 | |||
867 | :term:`BUILD_CFLAGS` | ||
868 | Specifies the flags to pass to the C compiler when building for the | ||
869 | build host. When building in the ``-native`` context, | ||
870 | :term:`CFLAGS` is set to the value of this variable by | ||
871 | default. | ||
872 | |||
873 | :term:`BUILD_CPPFLAGS` | ||
874 | Specifies the flags to pass to the C preprocessor (i.e. to both the C | ||
875 | and the C++ compilers) when building for the build host. When | ||
876 | building in the ``-native`` context, :term:`CPPFLAGS` | ||
877 | is set to the value of this variable by default. | ||
878 | |||
879 | :term:`BUILD_CXXFLAGS` | ||
880 | Specifies the flags to pass to the C++ compiler when building for the | ||
881 | build host. When building in the ``-native`` context, | ||
882 | :term:`CXXFLAGS` is set to the value of this variable | ||
883 | by default. | ||
884 | |||
885 | :term:`BUILD_FC` | ||
886 | Specifies the Fortran compiler command for the build host. By | ||
887 | default, ``BUILD_FC`` points to Gfortran and passes as arguments the | ||
888 | value of :term:`BUILD_CC_ARCH`, assuming | ||
889 | ``BUILD_CC_ARCH`` is set. | ||
890 | |||
891 | :term:`BUILD_LD` | ||
892 | Specifies the linker command for the build host. By default, | ||
893 | ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments | ||
894 | the value of :term:`BUILD_LD_ARCH`, assuming | ||
895 | ``BUILD_LD_ARCH`` is set. | ||
896 | |||
897 | :term:`BUILD_LD_ARCH` | ||
898 | Specifies architecture-specific linker flags for the build host. By | ||
899 | default, the value of ``BUILD_LD_ARCH`` is empty. | ||
900 | |||
901 | :term:`BUILD_LDFLAGS` | ||
902 | Specifies the flags to pass to the linker when building for the build | ||
903 | host. When building in the ``-native`` context, | ||
904 | :term:`LDFLAGS` is set to the value of this variable | ||
905 | by default. | ||
906 | |||
907 | :term:`BUILD_OPTIMIZATION` | ||
908 | Specifies the optimization flags passed to the C compiler when | ||
909 | building for the build host or the SDK. The flags are passed through | ||
910 | the :term:`BUILD_CFLAGS` and | ||
911 | :term:`BUILDSDK_CFLAGS` default values. | ||
912 | |||
913 | The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 | ||
914 | -pipe". | ||
915 | |||
916 | :term:`BUILD_OS` | ||
917 | Specifies the operating system in use on the build host (e.g. | ||
918 | "linux"). The OpenEmbedded build system sets the value of | ||
919 | ``BUILD_OS`` from the OS reported by the ``uname`` command - the | ||
920 | first word, converted to lower-case characters. | ||
921 | |||
922 | :term:`BUILD_PREFIX` | ||
923 | The toolchain binary prefix used for native recipes. The OpenEmbedded | ||
924 | build system uses the ``BUILD_PREFIX`` value to set the | ||
925 | :term:`TARGET_PREFIX` when building for | ||
926 | ``native`` recipes. | ||
927 | |||
928 | :term:`BUILD_STRIP` | ||
929 | Specifies the command to be used to strip debugging symbols from | ||
930 | binaries produced for the build host. By default, ``BUILD_STRIP`` | ||
931 | points to | ||
932 | ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. | ||
933 | |||
934 | :term:`BUILD_SYS` | ||
935 | Specifies the system, including the architecture and the operating | ||
936 | system, to use when building for the build host (i.e. when building | ||
937 | ``native`` recipes). | ||
938 | |||
939 | The OpenEmbedded build system automatically sets this variable based | ||
940 | on :term:`BUILD_ARCH`, | ||
941 | :term:`BUILD_VENDOR`, and | ||
942 | :term:`BUILD_OS`. You do not need to set the | ||
943 | ``BUILD_SYS`` variable yourself. | ||
944 | |||
945 | :term:`BUILD_VENDOR` | ||
946 | Specifies the vendor name to use when building for the build host. | ||
947 | The default value is an empty string (""). | ||
948 | |||
949 | :term:`BUILDDIR` | ||
950 | Points to the location of the :term:`Build Directory`. | ||
951 | You can define this directory indirectly through the | ||
952 | :ref:`structure-core-script` script by passing in a Build | ||
953 | Directory path when you run the script. If you run the script and do | ||
954 | not provide a Build Directory path, the ``BUILDDIR`` defaults to | ||
955 | ``build`` in the current directory. | ||
956 | |||
957 | :term:`BUILDHISTORY_COMMIT` | ||
958 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
959 | class, this variable specifies whether or not to commit the build | ||
960 | history output in a local Git repository. If set to "1", this local | ||
961 | repository will be maintained automatically by the ``buildhistory`` | ||
962 | class and a commit will be created on every build for changes to each | ||
963 | top-level subdirectory of the build history output (images, packages, | ||
964 | and sdk). If you want to track changes to build history over time, | ||
965 | you should set this value to "1". | ||
966 | |||
967 | By default, the ``buildhistory`` class does not commit the build | ||
968 | history output in a local Git repository: | ||
969 | :: | ||
970 | |||
971 | BUILDHISTORY_COMMIT ?= "0" | ||
972 | |||
973 | :term:`BUILDHISTORY_COMMIT_AUTHOR` | ||
974 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
975 | class, this variable specifies the author to use for each Git commit. | ||
976 | In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the | ||
977 | :term:`BUILDHISTORY_COMMIT` variable must | ||
978 | be set to "1". | ||
979 | |||
980 | Git requires that the value you provide for the | ||
981 | ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name | ||
982 | email@host". Providing an email address or host that is not valid | ||
983 | does not produce an error. | ||
984 | |||
985 | By default, the ``buildhistory`` class sets the variable as follows: | ||
986 | :: | ||
987 | |||
988 | BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" | ||
989 | |||
990 | :term:`BUILDHISTORY_DIR` | ||
991 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
992 | class, this variable specifies the directory in which build history | ||
993 | information is kept. For more information on how the variable works, | ||
994 | see the ``buildhistory.class``. | ||
995 | |||
996 | By default, the ``buildhistory`` class sets the directory as follows: | ||
997 | :: | ||
998 | |||
999 | BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" | ||
1000 | |||
1001 | :term:`BUILDHISTORY_FEATURES` | ||
1002 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
1003 | class, this variable specifies the build history features to be | ||
1004 | enabled. For more information on how build history works, see the | ||
1005 | ":ref:`dev-manual/common-tasks:maintaining build output quality`" | ||
1006 | section in the Yocto Project Development Tasks Manual. | ||
1007 | |||
1008 | You can specify these features in the form of a space-separated list: | ||
1009 | |||
1010 | - *image:* Analysis of the contents of images, which includes the | ||
1011 | list of installed packages among other things. | ||
1012 | |||
1013 | - *package:* Analysis of the contents of individual packages. | ||
1014 | |||
1015 | - *sdk:* Analysis of the contents of the software development kit | ||
1016 | (SDK). | ||
1017 | |||
1018 | - *task:* Save output file signatures for | ||
1019 | :ref:`shared state <overview-manual/concepts:shared state cache>` | ||
1020 | (sstate) tasks. | ||
1021 | This saves one file per task and lists the SHA-256 checksums for | ||
1022 | each file staged (i.e. the output of the task). | ||
1023 | |||
1024 | By default, the ``buildhistory`` class enables the following | ||
1025 | features: | ||
1026 | :: | ||
1027 | |||
1028 | BUILDHISTORY_FEATURES ?= "image package sdk" | ||
1029 | |||
1030 | :term:`BUILDHISTORY_IMAGE_FILES` | ||
1031 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
1032 | class, this variable specifies a list of paths to files copied from | ||
1033 | the image contents into the build history directory under an | ||
1034 | "image-files" directory in the directory for the image, so that you | ||
1035 | can track the contents of each file. The default is to copy | ||
1036 | ``/etc/passwd`` and ``/etc/group``, which allows you to monitor for | ||
1037 | changes in user and group entries. You can modify the list to include | ||
1038 | any file. Specifying an invalid path does not produce an error. | ||
1039 | Consequently, you can include files that might not always be present. | ||
1040 | |||
1041 | By default, the ``buildhistory`` class provides paths to the | ||
1042 | following files: | ||
1043 | :: | ||
1044 | |||
1045 | BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" | ||
1046 | |||
1047 | :term:`BUILDHISTORY_PUSH_REPO` | ||
1048 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | ||
1049 | class, this variable optionally specifies a remote repository to | ||
1050 | which build history pushes Git changes. In order for | ||
1051 | ``BUILDHISTORY_PUSH_REPO`` to work, | ||
1052 | :term:`BUILDHISTORY_COMMIT` must be set to | ||
1053 | "1". | ||
1054 | |||
1055 | The repository should correspond to a remote address that specifies a | ||
1056 | repository as understood by Git, or alternatively to a remote name | ||
1057 | that you have set up manually using ``git remote`` within the local | ||
1058 | repository. | ||
1059 | |||
1060 | By default, the ``buildhistory`` class sets the variable as follows: | ||
1061 | :: | ||
1062 | |||
1063 | BUILDHISTORY_PUSH_REPO ?= "" | ||
1064 | |||
1065 | :term:`BUILDSDK_CFLAGS` | ||
1066 | Specifies the flags to pass to the C compiler when building for the | ||
1067 | SDK. When building in the ``nativesdk-`` context, | ||
1068 | :term:`CFLAGS` is set to the value of this variable by | ||
1069 | default. | ||
1070 | |||
1071 | :term:`BUILDSDK_CPPFLAGS` | ||
1072 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
1073 | C and the C++ compilers) when building for the SDK. When building in | ||
1074 | the ``nativesdk-`` context, :term:`CPPFLAGS` is set | ||
1075 | to the value of this variable by default. | ||
1076 | |||
1077 | :term:`BUILDSDK_CXXFLAGS` | ||
1078 | Specifies the flags to pass to the C++ compiler when building for the | ||
1079 | SDK. When building in the ``nativesdk-`` context, | ||
1080 | :term:`CXXFLAGS` is set to the value of this variable | ||
1081 | by default. | ||
1082 | |||
1083 | :term:`BUILDSDK_LDFLAGS` | ||
1084 | Specifies the flags to pass to the linker when building for the SDK. | ||
1085 | When building in the ``nativesdk-`` context, | ||
1086 | :term:`LDFLAGS` is set to the value of this variable | ||
1087 | by default. | ||
1088 | |||
1089 | :term:`BUILDSTATS_BASE` | ||
1090 | Points to the location of the directory that holds build statistics | ||
1091 | when you use and enable the | ||
1092 | :ref:`buildstats <ref-classes-buildstats>` class. The | ||
1093 | ``BUILDSTATS_BASE`` directory defaults to | ||
1094 | ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. | ||
1095 | |||
1096 | :term:`BUSYBOX_SPLIT_SUID` | ||
1097 | For the BusyBox recipe, specifies whether to split the output | ||
1098 | executable file into two parts: one for features that require | ||
1099 | ``setuid root``, and one for the remaining features (i.e. those that | ||
1100 | do not require ``setuid root``). | ||
1101 | |||
1102 | The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in | ||
1103 | splitting the output executable file. Set the variable to "0" to get | ||
1104 | a single output executable file. | ||
1105 | |||
1106 | :term:`CACHE` | ||
1107 | Specifies the directory BitBake uses to store a cache of the | ||
1108 | :term:`Metadata` so it does not need to be parsed every time | ||
1109 | BitBake is started. | ||
1110 | |||
1111 | :term:`CC` | ||
1112 | The minimal command and arguments used to run the C compiler. | ||
1113 | |||
1114 | :term:`CFLAGS` | ||
1115 | Specifies the flags to pass to the C compiler. This variable is | ||
1116 | exported to an environment variable and thus made visible to the | ||
1117 | software being built during the compilation step. | ||
1118 | |||
1119 | Default initialization for ``CFLAGS`` varies depending on what is | ||
1120 | being built: | ||
1121 | |||
1122 | - :term:`TARGET_CFLAGS` when building for the | ||
1123 | target | ||
1124 | |||
1125 | - :term:`BUILD_CFLAGS` when building for the | ||
1126 | build host (i.e. ``-native``) | ||
1127 | |||
1128 | - :term:`BUILDSDK_CFLAGS` when building for | ||
1129 | an SDK (i.e. ``nativesdk-``) | ||
1130 | |||
1131 | :term:`CLASSOVERRIDE` | ||
1132 | An internal variable specifying the special class override that | ||
1133 | should currently apply (e.g. "class-target", "class-native", and so | ||
1134 | forth). The classes that use this variable (e.g. | ||
1135 | :ref:`native <ref-classes-native>`, | ||
1136 | :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the | ||
1137 | variable to appropriate values. | ||
1138 | |||
1139 | .. note:: | ||
1140 | |||
1141 | ``CLASSOVERRIDE`` gets its default "class-target" value from the | ||
1142 | ``bitbake.conf`` file. | ||
1143 | |||
1144 | As an example, the following override allows you to install extra | ||
1145 | files, but only when building for the target: | ||
1146 | :: | ||
1147 | |||
1148 | do_install_append_class-target() { | ||
1149 | install my-extra-file ${D}${sysconfdir} | ||
1150 | } | ||
1151 | |||
1152 | Here is an example where ``FOO`` is set to | ||
1153 | "native" when building for the build host, and to "other" when not | ||
1154 | building for the build host: | ||
1155 | :: | ||
1156 | |||
1157 | FOO_class-native = "native" | ||
1158 | FOO = "other" | ||
1159 | |||
1160 | The underlying mechanism behind ``CLASSOVERRIDE`` is simply | ||
1161 | that it is included in the default value of | ||
1162 | :term:`OVERRIDES`. | ||
1163 | |||
1164 | :term:`CLEANBROKEN` | ||
1165 | If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the | ||
1166 | ``make clean`` command does not work for the software being built. | ||
1167 | Consequently, the OpenEmbedded build system will not try to run | ||
1168 | ``make clean`` during the :ref:`ref-tasks-configure` | ||
1169 | task, which is the default behavior. | ||
1170 | |||
1171 | :term:`COMBINED_FEATURES` | ||
1172 | Provides a list of hardware features that are enabled in both | ||
1173 | :term:`MACHINE_FEATURES` and | ||
1174 | :term:`DISTRO_FEATURES`. This select list of | ||
1175 | features contains features that make sense to be controlled both at | ||
1176 | the machine and distribution configuration level. For example, the | ||
1177 | "bluetooth" feature requires hardware support but should also be | ||
1178 | optional at the distribution level, in case the hardware supports | ||
1179 | Bluetooth but you do not ever intend to use it. | ||
1180 | |||
1181 | :term:`COMMON_LICENSE_DIR` | ||
1182 | Points to ``meta/files/common-licenses`` in the | ||
1183 | :term:`Source Directory`, which is where generic license | ||
1184 | files reside. | ||
1185 | |||
1186 | :term:`COMPATIBLE_HOST` | ||
1187 | A regular expression that resolves to one or more hosts (when the | ||
1188 | recipe is native) or one or more targets (when the recipe is | ||
1189 | non-native) with which a recipe is compatible. The regular expression | ||
1190 | is matched against :term:`HOST_SYS`. You can use the | ||
1191 | variable to stop recipes from being built for classes of systems with | ||
1192 | which the recipes are not compatible. Stopping these builds is | ||
1193 | particularly useful with kernels. The variable also helps to increase | ||
1194 | parsing speed since the build system skips parsing recipes not | ||
1195 | compatible with the current system. | ||
1196 | |||
1197 | :term:`COMPATIBLE_MACHINE` | ||
1198 | A regular expression that resolves to one or more target machines | ||
1199 | with which a recipe is compatible. The regular expression is matched | ||
1200 | against :term:`MACHINEOVERRIDES`. You can use | ||
1201 | the variable to stop recipes from being built for machines with which | ||
1202 | the recipes are not compatible. Stopping these builds is particularly | ||
1203 | useful with kernels. The variable also helps to increase parsing | ||
1204 | speed since the build system skips parsing recipes not compatible | ||
1205 | with the current machine. | ||
1206 | |||
1207 | :term:`COMPLEMENTARY_GLOB` | ||
1208 | Defines wildcards to match when installing a list of complementary | ||
1209 | packages for all the packages explicitly (or implicitly) installed in | ||
1210 | an image. | ||
1211 | |||
1212 | .. note:: | ||
1213 | |||
1214 | The ``COMPLEMENTARY_GLOB`` variable uses Unix filename pattern matching | ||
1215 | (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), | ||
1216 | which is similar to the Unix style pathname pattern expansion | ||
1217 | (`glob <https://docs.python.org/3/library/glob.html>`__). | ||
1218 | |||
1219 | The resulting list of complementary packages is associated with an | ||
1220 | item that can be added to | ||
1221 | :term:`IMAGE_FEATURES`. An example usage of | ||
1222 | this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` | ||
1223 | will install -dev packages (containing headers and other development | ||
1224 | files) for every package in the image. | ||
1225 | |||
1226 | To add a new feature item pointing to a wildcard, use a variable flag | ||
1227 | to specify the feature item name and use the value to specify the | ||
1228 | wildcard. Here is an example: | ||
1229 | :: | ||
1230 | |||
1231 | COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' | ||
1232 | |||
1233 | :term:`COMPONENTS_DIR` | ||
1234 | Stores sysroot components for each recipe. The OpenEmbedded build | ||
1235 | system uses ``COMPONENTS_DIR`` when constructing recipe-specific | ||
1236 | sysroots for other recipes. | ||
1237 | |||
1238 | The default is | ||
1239 | "``${``\ :term:`STAGING_DIR`\ ``}-components``." | ||
1240 | (i.e. | ||
1241 | "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). | ||
1242 | |||
1243 | :term:`CONF_VERSION` | ||
1244 | Tracks the version of the local configuration file (i.e. | ||
1245 | ``local.conf``). The value for ``CONF_VERSION`` increments each time | ||
1246 | ``build/conf/`` compatibility changes. | ||
1247 | |||
1248 | :term:`CONFFILES` | ||
1249 | Identifies editable or configurable files that are part of a package. | ||
1250 | If the Package Management System (PMS) is being used to update | ||
1251 | packages on the target system, it is possible that configuration | ||
1252 | files you have changed after the original installation and that you | ||
1253 | now want to remain unchanged are overwritten. In other words, | ||
1254 | editable files might exist in the package that you do not want reset | ||
1255 | as part of the package update process. You can use the ``CONFFILES`` | ||
1256 | variable to list the files in the package that you wish to prevent | ||
1257 | the PMS from overwriting during this update process. | ||
1258 | |||
1259 | To use the ``CONFFILES`` variable, provide a package name override | ||
1260 | that identifies the resulting package. Then, provide a | ||
1261 | space-separated list of files. Here is an example: | ||
1262 | :: | ||
1263 | |||
1264 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | ||
1265 | ${sysconfdir}/file2 ${sysconfdir}/file3" | ||
1266 | |||
1267 | A relationship exists between the ``CONFFILES`` and ``FILES`` | ||
1268 | variables. The files listed within ``CONFFILES`` must be a subset of | ||
1269 | the files listed within ``FILES``. Because the configuration files | ||
1270 | you provide with ``CONFFILES`` are simply being identified so that | ||
1271 | the PMS will not overwrite them, it makes sense that the files must | ||
1272 | already be included as part of the package through the ``FILES`` | ||
1273 | variable. | ||
1274 | |||
1275 | .. note:: | ||
1276 | |||
1277 | When specifying paths as part of the ``CONFFILES`` variable, it is | ||
1278 | good practice to use appropriate path variables. | ||
1279 | For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` | ||
1280 | rather than ``/usr/bin``. You can find a list of these variables at | ||
1281 | the top of the ``meta/conf/bitbake.conf`` file in the | ||
1282 | :term:`Source Directory`. | ||
1283 | |||
1284 | :term:`CONFIG_INITRAMFS_SOURCE` | ||
1285 | Identifies the initial RAM filesystem (initramfs) source files. The | ||
1286 | OpenEmbedded build system receives and uses this kernel Kconfig | ||
1287 | variable as an environment variable. By default, the variable is set | ||
1288 | to null (""). | ||
1289 | |||
1290 | The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive | ||
1291 | with a ``.cpio`` suffix or a space-separated list of directories and | ||
1292 | files for building the initramfs image. A cpio archive should contain | ||
1293 | a filesystem archive to be used as an initramfs image. Directories | ||
1294 | should contain a filesystem layout to be included in the initramfs | ||
1295 | image. Files should contain entries according to the format described | ||
1296 | by the ``usr/gen_init_cpio`` program in the kernel tree. | ||
1297 | |||
1298 | If you specify multiple directories and files, the initramfs image | ||
1299 | will be the aggregate of all of them. | ||
1300 | |||
1301 | For information on creating an initramfs, see the | ||
1302 | ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | ||
1303 | in the Yocto Project Development Tasks Manual. | ||
1304 | |||
1305 | :term:`CONFIG_SITE` | ||
1306 | A list of files that contains ``autoconf`` test results relevant to | ||
1307 | the current build. This variable is used by the Autotools utilities | ||
1308 | when running ``configure``. | ||
1309 | |||
1310 | :term:`CONFIGURE_FLAGS` | ||
1311 | The minimal arguments for GNU configure. | ||
1312 | |||
1313 | :term:`CONFLICT_DISTRO_FEATURES` | ||
1314 | When inheriting the | ||
1315 | :ref:`features_check <ref-classes-features_check>` | ||
1316 | class, this variable identifies distribution features that would be | ||
1317 | in conflict should the recipe be built. In other words, if the | ||
1318 | ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also | ||
1319 | appears in ``DISTRO_FEATURES`` within the current configuration, then | ||
1320 | the recipe will be skipped, and if the build system attempts to build | ||
1321 | the recipe then an error will be triggered. | ||
1322 | |||
1323 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1324 | A space-separated list of licenses to exclude from the source | ||
1325 | archived by the :ref:`archiver <ref-classes-archiver>` class. In | ||
1326 | other words, if a license in a recipe's | ||
1327 | :term:`LICENSE` value is in the value of | ||
1328 | ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the | ||
1329 | class. | ||
1330 | |||
1331 | .. note:: | ||
1332 | |||
1333 | The ``COPYLEFT_LICENSE_EXCLUDE`` variable takes precedence over the | ||
1334 | :term:`COPYLEFT_LICENSE_INCLUDE` variable. | ||
1335 | |||
1336 | The default value, which is "CLOSED Proprietary", for | ||
1337 | ``COPYLEFT_LICENSE_EXCLUDE`` is set by the | ||
1338 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1339 | is inherited by the ``archiver`` class. | ||
1340 | |||
1341 | :term:`COPYLEFT_LICENSE_INCLUDE` | ||
1342 | A space-separated list of licenses to include in the source archived | ||
1343 | by the :ref:`archiver <ref-classes-archiver>` class. In other | ||
1344 | words, if a license in a recipe's :term:`LICENSE` | ||
1345 | value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its | ||
1346 | source is archived by the class. | ||
1347 | |||
1348 | The default value is set by the | ||
1349 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1350 | is inherited by the ``archiver`` class. The default value includes | ||
1351 | "GPL*", "LGPL*", and "AGPL*". | ||
1352 | |||
1353 | :term:`COPYLEFT_PN_EXCLUDE` | ||
1354 | A list of recipes to exclude in the source archived by the | ||
1355 | :ref:`archiver <ref-classes-archiver>` class. The | ||
1356 | ``COPYLEFT_PN_EXCLUDE`` variable overrides the license inclusion and | ||
1357 | exclusion caused through the | ||
1358 | :term:`COPYLEFT_LICENSE_INCLUDE` and | ||
1359 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1360 | variables, respectively. | ||
1361 | |||
1362 | The default value, which is "" indicating to not explicitly exclude | ||
1363 | any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the | ||
1364 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1365 | is inherited by the ``archiver`` class. | ||
1366 | |||
1367 | :term:`COPYLEFT_PN_INCLUDE` | ||
1368 | A list of recipes to include in the source archived by the | ||
1369 | :ref:`archiver <ref-classes-archiver>` class. The | ||
1370 | ``COPYLEFT_PN_INCLUDE`` variable overrides the license inclusion and | ||
1371 | exclusion caused through the | ||
1372 | :term:`COPYLEFT_LICENSE_INCLUDE` and | ||
1373 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1374 | variables, respectively. | ||
1375 | |||
1376 | The default value, which is "" indicating to not explicitly include | ||
1377 | any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the | ||
1378 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | ||
1379 | is inherited by the ``archiver`` class. | ||
1380 | |||
1381 | :term:`COPYLEFT_RECIPE_TYPES` | ||
1382 | A space-separated list of recipe types to include in the source | ||
1383 | archived by the :ref:`archiver <ref-classes-archiver>` class. | ||
1384 | Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, | ||
1385 | ``crosssdk``, and ``cross-canadian``. | ||
1386 | |||
1387 | The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` | ||
1388 | is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` | ||
1389 | class, which is inherited by the ``archiver`` class. | ||
1390 | |||
1391 | :term:`COPY_LIC_DIRS` | ||
1392 | If set to "1" along with the | ||
1393 | :term:`COPY_LIC_MANIFEST` variable, the | ||
1394 | OpenEmbedded build system copies into the image the license files, | ||
1395 | which are located in ``/usr/share/common-licenses``, for each | ||
1396 | package. The license files are placed in directories within the image | ||
1397 | itself during build time. | ||
1398 | |||
1399 | .. note:: | ||
1400 | |||
1401 | The ``COPY_LIC_DIRS`` does not offer a path for adding licenses for | ||
1402 | newly installed packages to an image, which might be most suitable for | ||
1403 | read-only filesystems that cannot be upgraded. See the | ||
1404 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. | ||
1405 | You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" | ||
1406 | section in the Yocto Project Development Tasks Manual for | ||
1407 | information on providing license text. | ||
1408 | |||
1409 | :term:`COPY_LIC_MANIFEST` | ||
1410 | If set to "1", the OpenEmbedded build system copies the license | ||
1411 | manifest for the image to | ||
1412 | ``/usr/share/common-licenses/license.manifest`` within the image | ||
1413 | itself during build time. | ||
1414 | |||
1415 | .. note:: | ||
1416 | |||
1417 | The ``COPY_LIC_MANIFEST`` does not offer a path for adding licenses for | ||
1418 | newly installed packages to an image, which might be most suitable for | ||
1419 | read-only filesystems that cannot be upgraded. See the | ||
1420 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. | ||
1421 | You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" | ||
1422 | section in the Yocto Project Development Tasks Manual for | ||
1423 | information on providing license text. | ||
1424 | |||
1425 | :term:`CORE_IMAGE_EXTRA_INSTALL` | ||
1426 | Specifies the list of packages to be added to the image. You should | ||
1427 | only set this variable in the ``local.conf`` configuration file found | ||
1428 | in the :term:`Build Directory`. | ||
1429 | |||
1430 | This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer | ||
1431 | supported. | ||
1432 | |||
1433 | :term:`COREBASE` | ||
1434 | Specifies the parent directory of the OpenEmbedded-Core Metadata | ||
1435 | layer (i.e. ``meta``). | ||
1436 | |||
1437 | It is an important distinction that ``COREBASE`` points to the parent | ||
1438 | of this layer and not the layer itself. Consider an example where you | ||
1439 | have cloned the Poky Git repository and retained the ``poky`` name | ||
1440 | for your local copy of the repository. In this case, ``COREBASE`` | ||
1441 | points to the ``poky`` folder because it is the parent directory of | ||
1442 | the ``poky/meta`` layer. | ||
1443 | |||
1444 | :term:`COREBASE_FILES` | ||
1445 | Lists files from the :term:`COREBASE` directory that | ||
1446 | should be copied other than the layers listed in the | ||
1447 | ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for | ||
1448 | the purpose of copying metadata from the OpenEmbedded build system | ||
1449 | into the extensible SDK. | ||
1450 | |||
1451 | Explicitly listing files in ``COREBASE`` is needed because it | ||
1452 | typically contains build directories and other files that should not | ||
1453 | normally be copied into the extensible SDK. Consequently, the value | ||
1454 | of ``COREBASE_FILES`` is used in order to only copy the files that | ||
1455 | are actually needed. | ||
1456 | |||
1457 | :term:`CPP` | ||
1458 | The minimal command and arguments used to run the C preprocessor. | ||
1459 | |||
1460 | :term:`CPPFLAGS` | ||
1461 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
1462 | C and the C++ compilers). This variable is exported to an environment | ||
1463 | variable and thus made visible to the software being built during the | ||
1464 | compilation step. | ||
1465 | |||
1466 | Default initialization for ``CPPFLAGS`` varies depending on what is | ||
1467 | being built: | ||
1468 | |||
1469 | - :term:`TARGET_CPPFLAGS` when building for | ||
1470 | the target | ||
1471 | |||
1472 | - :term:`BUILD_CPPFLAGS` when building for the | ||
1473 | build host (i.e. ``-native``) | ||
1474 | |||
1475 | - :term:`BUILDSDK_CPPFLAGS` when building | ||
1476 | for an SDK (i.e. ``nativesdk-``) | ||
1477 | |||
1478 | :term:`CROSS_COMPILE` | ||
1479 | The toolchain binary prefix for the target tools. The | ||
1480 | ``CROSS_COMPILE`` variable is the same as the | ||
1481 | :term:`TARGET_PREFIX` variable. | ||
1482 | |||
1483 | .. note:: | ||
1484 | |||
1485 | The OpenEmbedded build system sets the ``CROSS_COMPILE`` | ||
1486 | variable only in certain contexts (e.g. when building for kernel | ||
1487 | and kernel module recipes). | ||
1488 | |||
1489 | :term:`CVSDIR` | ||
1490 | The directory in which files checked out under the CVS system are | ||
1491 | stored. | ||
1492 | |||
1493 | :term:`CXX` | ||
1494 | The minimal command and arguments used to run the C++ compiler. | ||
1495 | |||
1496 | :term:`CXXFLAGS` | ||
1497 | Specifies the flags to pass to the C++ compiler. This variable is | ||
1498 | exported to an environment variable and thus made visible to the | ||
1499 | software being built during the compilation step. | ||
1500 | |||
1501 | Default initialization for ``CXXFLAGS`` varies depending on what is | ||
1502 | being built: | ||
1503 | |||
1504 | - :term:`TARGET_CXXFLAGS` when building for | ||
1505 | the target | ||
1506 | |||
1507 | - :term:`BUILD_CXXFLAGS` when building for the | ||
1508 | build host (i.e. ``-native``) | ||
1509 | |||
1510 | - :term:`BUILDSDK_CXXFLAGS` when building | ||
1511 | for an SDK (i.e. ``nativesdk-``) | ||
1512 | |||
1513 | :term:`D` | ||
1514 | The destination directory. The location in the :term:`Build Directory` | ||
1515 | where components are installed by the | ||
1516 | :ref:`ref-tasks-install` task. This location defaults | ||
1517 | to: | ||
1518 | :: | ||
1519 | |||
1520 | ${WORKDIR}/image | ||
1521 | |||
1522 | .. note:: | ||
1523 | |||
1524 | Tasks that read from or write to this directory should run under | ||
1525 | :ref:`fakeroot <overview-manual/concepts:fakeroot and pseudo>`. | ||
1526 | |||
1527 | :term:`DATE` | ||
1528 | The date the build was started. Dates appear using the year, month, | ||
1529 | and day (YMD) format (e.g. "20150209" for February 9th, 2015). | ||
1530 | |||
1531 | :term:`DATETIME` | ||
1532 | The date and time on which the current build started. The format is | ||
1533 | suitable for timestamps. | ||
1534 | |||
1535 | :term:`DEBIAN_NOAUTONAME` | ||
1536 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
1537 | which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a | ||
1538 | particular package should not be renamed according to Debian library | ||
1539 | package naming. You must use the package name as an override when you | ||
1540 | set this variable. Here is an example from the ``fontconfig`` recipe: | ||
1541 | :: | ||
1542 | |||
1543 | DEBIAN_NOAUTONAME_fontconfig-utils = "1" | ||
1544 | |||
1545 | :term:`DEBIANNAME` | ||
1546 | When the :ref:`debian <ref-classes-debian>` class is inherited, | ||
1547 | which is the default behavior, ``DEBIANNAME`` allows you to override | ||
1548 | the library name for an individual package. Overriding the library | ||
1549 | name in these cases is rare. You must use the package name as an | ||
1550 | override when you set this variable. Here is an example from the | ||
1551 | ``dbus`` recipe: | ||
1552 | :: | ||
1553 | |||
1554 | DEBIANNAME_${PN} = "dbus-1" | ||
1555 | |||
1556 | :term:`DEBUG_BUILD` | ||
1557 | Specifies to build packages with debugging information. This | ||
1558 | influences the value of the ``SELECTED_OPTIMIZATION`` variable. | ||
1559 | |||
1560 | :term:`DEBUG_OPTIMIZATION` | ||
1561 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | ||
1562 | compiling a system for debugging. This variable defaults to "-O | ||
1563 | -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". | ||
1564 | |||
1565 | :term:`DEFAULT_PREFERENCE` | ||
1566 | Specifies a weak bias for recipe selection priority. | ||
1567 | |||
1568 | The most common usage of this is variable is to set it to "-1" within | ||
1569 | a recipe for a development version of a piece of software. Using the | ||
1570 | variable in this way causes the stable version of the recipe to build | ||
1571 | by default in the absence of ``PREFERRED_VERSION`` being used to | ||
1572 | build the development version. | ||
1573 | |||
1574 | .. note:: | ||
1575 | |||
1576 | The bias provided by ``DEFAULT_PREFERENCE`` is weak and is overridden | ||
1577 | by :term:`BBFILE_PRIORITY` if that variable is different between two | ||
1578 | layers that contain different versions of the same recipe. | ||
1579 | |||
1580 | :term:`DEFAULTTUNE` | ||
1581 | The default CPU and Application Binary Interface (ABI) tunings (i.e. | ||
1582 | the "tune") used by the OpenEmbedded build system. The | ||
1583 | ``DEFAULTTUNE`` helps define | ||
1584 | :term:`TUNE_FEATURES`. | ||
1585 | |||
1586 | The default tune is either implicitly or explicitly set by the | ||
1587 | machine (:term:`MACHINE`). However, you can override | ||
1588 | the setting using available tunes as defined with | ||
1589 | :term:`AVAILTUNES`. | ||
1590 | |||
1591 | :term:`DEPENDS` | ||
1592 | Lists a recipe's build-time dependencies. These are dependencies on | ||
1593 | other recipes whose contents (e.g. headers and shared libraries) are | ||
1594 | needed by the recipe at build time. | ||
1595 | |||
1596 | As an example, consider a recipe ``foo`` that contains the following | ||
1597 | assignment: | ||
1598 | :: | ||
1599 | |||
1600 | DEPENDS = "bar" | ||
1601 | |||
1602 | The practical effect of the previous | ||
1603 | assignment is that all files installed by bar will be available in | ||
1604 | the appropriate staging sysroot, given by the | ||
1605 | :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the | ||
1606 | :ref:`ref-tasks-configure` task for ``foo`` runs. | ||
1607 | This mechanism is implemented by having ``do_configure`` depend on | ||
1608 | the :ref:`ref-tasks-populate_sysroot` task of | ||
1609 | each recipe listed in ``DEPENDS``, through a | ||
1610 | ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` | ||
1611 | declaration in the :ref:`base <ref-classes-base>` class. | ||
1612 | |||
1613 | .. note:: | ||
1614 | |||
1615 | It seldom is necessary to reference, for example, ``STAGING_DIR_HOST`` | ||
1616 | explicitly. The standard classes and build-related variables are | ||
1617 | configured to automatically use the appropriate staging sysroots. | ||
1618 | |||
1619 | As another example, ``DEPENDS`` can also be used to add utilities | ||
1620 | that run on the build machine during the build. For example, a recipe | ||
1621 | that makes use of a code generator built by the recipe ``codegen`` | ||
1622 | might have the following: | ||
1623 | :: | ||
1624 | |||
1625 | DEPENDS = "codegen-native" | ||
1626 | |||
1627 | For more | ||
1628 | information, see the :ref:`native <ref-classes-native>` class and | ||
1629 | the :term:`EXTRANATIVEPATH` variable. | ||
1630 | |||
1631 | .. note:: | ||
1632 | |||
1633 | - ``DEPENDS`` is a list of recipe names. Or, to be more precise, | ||
1634 | it is a list of :term:`PROVIDES` names, which | ||
1635 | usually match recipe names. Putting a package name such as | ||
1636 | "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" | ||
1637 | instead, as this will put files from all the packages that make | ||
1638 | up ``foo``, which includes those from ``foo-dev``, into the | ||
1639 | sysroot. | ||
1640 | |||
1641 | - One recipe having another recipe in ``DEPENDS`` does not by | ||
1642 | itself add any runtime dependencies between the packages | ||
1643 | produced by the two recipes. However, as explained in the | ||
1644 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | ||
1645 | section in the Yocto Project Overview and Concepts Manual, | ||
1646 | runtime dependencies will often be added automatically, meaning | ||
1647 | ``DEPENDS`` alone is sufficient for most recipes. | ||
1648 | |||
1649 | - Counterintuitively, ``DEPENDS`` is often necessary even for | ||
1650 | recipes that install precompiled components. For example, if | ||
1651 | ``libfoo`` is a precompiled library that links against | ||
1652 | ``libbar``, then linking against ``libfoo`` requires both | ||
1653 | ``libfoo`` and ``libbar`` to be available in the sysroot. | ||
1654 | Without a ``DEPENDS`` from the recipe that installs ``libfoo`` | ||
1655 | to the recipe that installs ``libbar``, other recipes might | ||
1656 | fail to link against ``libfoo``. | ||
1657 | |||
1658 | For information on runtime dependencies, see the | ||
1659 | :term:`RDEPENDS` variable. You can also see the | ||
1660 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
1661 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
1662 | BitBake User Manual for additional information on tasks and | ||
1663 | dependencies. | ||
1664 | |||
1665 | :term:`DEPLOY_DIR` | ||
1666 | Points to the general area that the OpenEmbedded build system uses to | ||
1667 | place images, packages, SDKs, and other output files that are ready | ||
1668 | to be used outside of the build system. By default, this directory | ||
1669 | resides within the :term:`Build Directory` as | ||
1670 | ``${TMPDIR}/deploy``. | ||
1671 | |||
1672 | For more information on the structure of the Build Directory, see | ||
1673 | ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. | ||
1674 | For more detail on the contents of the ``deploy`` directory, see the | ||
1675 | ":ref:`overview-manual/concepts:images`", | ||
1676 | ":ref:`overview-manual/concepts:package feeds`", and | ||
1677 | ":ref:`overview-manual/concepts:application development sdk`" sections all in the | ||
1678 | Yocto Project Overview and Concepts Manual. | ||
1679 | |||
1680 | :term:`DEPLOY_DIR_DEB` | ||
1681 | Points to the area that the OpenEmbedded build system uses to place | ||
1682 | Debian packages that are ready to be used outside of the build | ||
1683 | system. This variable applies only when | ||
1684 | :term:`PACKAGE_CLASSES` contains | ||
1685 | "package_deb". | ||
1686 | |||
1687 | The BitBake configuration file initially defines the | ||
1688 | ``DEPLOY_DIR_DEB`` variable as a sub-folder of | ||
1689 | :term:`DEPLOY_DIR`: | ||
1690 | :: | ||
1691 | |||
1692 | DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" | ||
1693 | |||
1694 | The :ref:`package_deb <ref-classes-package_deb>` class uses the | ||
1695 | ``DEPLOY_DIR_DEB`` variable to make sure the | ||
1696 | :ref:`ref-tasks-package_write_deb` task | ||
1697 | writes Debian packages into the appropriate folder. For more | ||
1698 | information on how packaging works, see the | ||
1699 | ":ref:`overview-manual/concepts:package feeds`" section | ||
1700 | in the Yocto Project Overview and Concepts Manual. | ||
1701 | |||
1702 | :term:`DEPLOY_DIR_IMAGE` | ||
1703 | Points to the area that the OpenEmbedded build system uses to place | ||
1704 | images and other associated output files that are ready to be | ||
1705 | deployed onto the target machine. The directory is machine-specific | ||
1706 | as it contains the ``${MACHINE}`` name. By default, this directory | ||
1707 | resides within the :term:`Build Directory` as | ||
1708 | ``${DEPLOY_DIR}/images/${MACHINE}/``. | ||
1709 | |||
1710 | For more information on the structure of the Build Directory, see | ||
1711 | ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. | ||
1712 | For more detail on the contents of the ``deploy`` directory, see the | ||
1713 | ":ref:`overview-manual/concepts:images`" and | ||
1714 | ":ref:`overview-manual/concepts:application development sdk`" sections both in | ||
1715 | the Yocto Project Overview and Concepts Manual. | ||
1716 | |||
1717 | :term:`DEPLOY_DIR_IPK` | ||
1718 | Points to the area that the OpenEmbedded build system uses to place | ||
1719 | IPK packages that are ready to be used outside of the build system. | ||
1720 | This variable applies only when | ||
1721 | :term:`PACKAGE_CLASSES` contains | ||
1722 | "package_ipk". | ||
1723 | |||
1724 | The BitBake configuration file initially defines this variable as a | ||
1725 | sub-folder of :term:`DEPLOY_DIR`: | ||
1726 | :: | ||
1727 | |||
1728 | DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" | ||
1729 | |||
1730 | The :ref:`package_ipk <ref-classes-package_ipk>` class uses the | ||
1731 | ``DEPLOY_DIR_IPK`` variable to make sure the | ||
1732 | :ref:`ref-tasks-package_write_ipk` task | ||
1733 | writes IPK packages into the appropriate folder. For more information | ||
1734 | on how packaging works, see the | ||
1735 | ":ref:`overview-manual/concepts:package feeds`" section | ||
1736 | in the Yocto Project Overview and Concepts Manual. | ||
1737 | |||
1738 | :term:`DEPLOY_DIR_RPM` | ||
1739 | Points to the area that the OpenEmbedded build system uses to place | ||
1740 | RPM packages that are ready to be used outside of the build system. | ||
1741 | This variable applies only when | ||
1742 | :term:`PACKAGE_CLASSES` contains | ||
1743 | "package_rpm". | ||
1744 | |||
1745 | The BitBake configuration file initially defines this variable as a | ||
1746 | sub-folder of :term:`DEPLOY_DIR`: | ||
1747 | :: | ||
1748 | |||
1749 | DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" | ||
1750 | |||
1751 | The :ref:`package_rpm <ref-classes-package_rpm>` class uses the | ||
1752 | ``DEPLOY_DIR_RPM`` variable to make sure the | ||
1753 | :ref:`ref-tasks-package_write_rpm` task | ||
1754 | writes RPM packages into the appropriate folder. For more information | ||
1755 | on how packaging works, see the | ||
1756 | ":ref:`overview-manual/concepts:package feeds`" section | ||
1757 | in the Yocto Project Overview and Concepts Manual. | ||
1758 | |||
1759 | :term:`DEPLOY_DIR_TAR` | ||
1760 | Points to the area that the OpenEmbedded build system uses to place | ||
1761 | tarballs that are ready to be used outside of the build system. This | ||
1762 | variable applies only when | ||
1763 | :term:`PACKAGE_CLASSES` contains | ||
1764 | "package_tar". | ||
1765 | |||
1766 | The BitBake configuration file initially defines this variable as a | ||
1767 | sub-folder of :term:`DEPLOY_DIR`: | ||
1768 | :: | ||
1769 | |||
1770 | DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar" | ||
1771 | |||
1772 | The :ref:`package_tar <ref-classes-package_tar>` class uses the | ||
1773 | ``DEPLOY_DIR_TAR`` variable to make sure the | ||
1774 | :ref:`ref-tasks-package_write_tar` task | ||
1775 | writes TAR packages into the appropriate folder. For more information | ||
1776 | on how packaging works, see the | ||
1777 | ":ref:`overview-manual/concepts:package feeds`" section | ||
1778 | in the Yocto Project Overview and Concepts Manual. | ||
1779 | |||
1780 | :term:`DEPLOYDIR` | ||
1781 | When inheriting the :ref:`deploy <ref-classes-deploy>` class, the | ||
1782 | ``DEPLOYDIR`` points to a temporary work area for deployed files that | ||
1783 | is set in the ``deploy`` class as follows: | ||
1784 | :: | ||
1785 | |||
1786 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | ||
1787 | |||
1788 | Recipes inheriting the ``deploy`` class should copy files to be | ||
1789 | deployed into ``DEPLOYDIR``, and the class will take care of copying | ||
1790 | them into :term:`DEPLOY_DIR_IMAGE` | ||
1791 | afterwards. | ||
1792 | |||
1793 | :term:`DESCRIPTION` | ||
1794 | The package description used by package managers. If not set, | ||
1795 | ``DESCRIPTION`` takes the value of the :term:`SUMMARY` | ||
1796 | variable. | ||
1797 | |||
1798 | :term:`DISTRO` | ||
1799 | The short name of the distribution. For information on the long name | ||
1800 | of the distribution, see the :term:`DISTRO_NAME` | ||
1801 | variable. | ||
1802 | |||
1803 | The ``DISTRO`` variable corresponds to a distribution configuration | ||
1804 | file whose root name is the same as the variable's argument and whose | ||
1805 | filename extension is ``.conf``. For example, the distribution | ||
1806 | configuration file for the Poky distribution is named ``poky.conf`` | ||
1807 | and resides in the ``meta-poky/conf/distro`` directory of the | ||
1808 | :term:`Source Directory`. | ||
1809 | |||
1810 | Within that ``poky.conf`` file, the ``DISTRO`` variable is set as | ||
1811 | follows: | ||
1812 | :: | ||
1813 | |||
1814 | DISTRO = "poky" | ||
1815 | |||
1816 | Distribution configuration files are located in a ``conf/distro`` | ||
1817 | directory within the :term:`Metadata` that contains the | ||
1818 | distribution configuration. The value for ``DISTRO`` must not contain | ||
1819 | spaces, and is typically all lower-case. | ||
1820 | |||
1821 | .. note:: | ||
1822 | |||
1823 | If the ``DISTRO`` variable is blank, a set of default configurations | ||
1824 | are used, which are specified within | ||
1825 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. | ||
1826 | |||
1827 | :term:`DISTRO_CODENAME` | ||
1828 | Specifies a codename for the distribution being built. | ||
1829 | |||
1830 | :term:`DISTRO_EXTRA_RDEPENDS` | ||
1831 | Specifies a list of distro-specific packages to add to all images. | ||
1832 | This variable takes affect through ``packagegroup-base`` so the | ||
1833 | variable only really applies to the more full-featured images that | ||
1834 | include ``packagegroup-base``. You can use this variable to keep | ||
1835 | distro policy out of generic images. As with all other distro | ||
1836 | variables, you set this variable in the distro ``.conf`` file. | ||
1837 | |||
1838 | :term:`DISTRO_EXTRA_RRECOMMENDS` | ||
1839 | Specifies a list of distro-specific packages to add to all images if | ||
1840 | the packages exist. The packages might not exist or be empty (e.g. | ||
1841 | kernel modules). The list of packages are automatically installed but | ||
1842 | you can remove them. | ||
1843 | |||
1844 | :term:`DISTRO_FEATURES` | ||
1845 | The software support you want in your distribution for various | ||
1846 | features. You define your distribution features in the distribution | ||
1847 | configuration file. | ||
1848 | |||
1849 | In most cases, the presence or absence of a feature in | ||
1850 | ``DISTRO_FEATURES`` is translated to the appropriate option supplied | ||
1851 | to the configure script during the | ||
1852 | :ref:`ref-tasks-configure` task for recipes that | ||
1853 | optionally support the feature. For example, specifying "x11" in | ||
1854 | ``DISTRO_FEATURES``, causes every piece of software built for the | ||
1855 | target that can optionally support X11 to have its X11 support | ||
1856 | enabled. | ||
1857 | |||
1858 | Two more examples are Bluetooth and NFS support. For a more complete | ||
1859 | list of features that ships with the Yocto Project and that you can | ||
1860 | provide with this variable, see the ":ref:`ref-features-distro`" section. | ||
1861 | |||
1862 | :term:`DISTRO_FEATURES_BACKFILL` | ||
1863 | Features to be added to ``DISTRO_FEATURES`` if not also present in | ||
1864 | ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. | ||
1865 | |||
1866 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | ||
1867 | not intended to be user-configurable. It is best to just reference | ||
1868 | the variable to see which distro features are being backfilled for | ||
1869 | all distro configurations. See the ":ref:`ref-features-backfill`" section | ||
1870 | for more information. | ||
1871 | |||
1872 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | ||
1873 | Features from ``DISTRO_FEATURES_BACKFILL`` that should not be | ||
1874 | backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See | ||
1875 | the ":ref:`ref-features-backfill`" section for more information. | ||
1876 | |||
1877 | :term:`DISTRO_FEATURES_DEFAULT` | ||
1878 | A convenience variable that gives you the default list of distro | ||
1879 | features with the exception of any features specific to the C library | ||
1880 | (``libc``). | ||
1881 | |||
1882 | When creating a custom distribution, you might find it useful to be | ||
1883 | able to reuse the default | ||
1884 | :term:`DISTRO_FEATURES` options without the | ||
1885 | need to write out the full set. Here is an example that uses | ||
1886 | ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: | ||
1887 | :: | ||
1888 | |||
1889 | DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" | ||
1890 | |||
1891 | :term:`DISTRO_FEATURES_FILTER_NATIVE` | ||
1892 | Specifies a list of features that if present in the target | ||
1893 | :term:`DISTRO_FEATURES` value should be | ||
1894 | included in ``DISTRO_FEATURES`` when building native recipes. This | ||
1895 | variable is used in addition to the features filtered using the | ||
1896 | :term:`DISTRO_FEATURES_NATIVE` | ||
1897 | variable. | ||
1898 | |||
1899 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` | ||
1900 | Specifies a list of features that if present in the target | ||
1901 | :term:`DISTRO_FEATURES` value should be | ||
1902 | included in ``DISTRO_FEATURES`` when building nativesdk recipes. This | ||
1903 | variable is used in addition to the features filtered using the | ||
1904 | :term:`DISTRO_FEATURES_NATIVESDK` | ||
1905 | variable. | ||
1906 | |||
1907 | :term:`DISTRO_FEATURES_NATIVE` | ||
1908 | Specifies a list of features that should be included in | ||
1909 | :term:`DISTRO_FEATURES` when building native | ||
1910 | recipes. This variable is used in addition to the features filtered | ||
1911 | using the | ||
1912 | :term:`DISTRO_FEATURES_FILTER_NATIVE` | ||
1913 | variable. | ||
1914 | |||
1915 | :term:`DISTRO_FEATURES_NATIVESDK` | ||
1916 | Specifies a list of features that should be included in | ||
1917 | :term:`DISTRO_FEATURES` when building | ||
1918 | nativesdk recipes. This variable is used in addition to the features | ||
1919 | filtered using the | ||
1920 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` | ||
1921 | variable. | ||
1922 | |||
1923 | :term:`DISTRO_NAME` | ||
1924 | The long name of the distribution. For information on the short name | ||
1925 | of the distribution, see the :term:`DISTRO` variable. | ||
1926 | |||
1927 | The ``DISTRO_NAME`` variable corresponds to a distribution | ||
1928 | configuration file whose root name is the same as the variable's | ||
1929 | argument and whose filename extension is ``.conf``. For example, the | ||
1930 | distribution configuration file for the Poky distribution is named | ||
1931 | ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory | ||
1932 | of the :term:`Source Directory`. | ||
1933 | |||
1934 | Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set | ||
1935 | as follows: | ||
1936 | :: | ||
1937 | |||
1938 | DISTRO_NAME = "Poky (Yocto Project Reference Distro)" | ||
1939 | |||
1940 | Distribution configuration files are located in a ``conf/distro`` | ||
1941 | directory within the :term:`Metadata` that contains the | ||
1942 | distribution configuration. | ||
1943 | |||
1944 | .. note:: | ||
1945 | |||
1946 | If the ``DISTRO_NAME`` variable is blank, a set of default | ||
1947 | configurations are used, which are specified within | ||
1948 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. | ||
1949 | |||
1950 | :term:`DISTRO_VERSION` | ||
1951 | The version of the distribution. | ||
1952 | |||
1953 | :term:`DISTROOVERRIDES` | ||
1954 | A colon-separated list of overrides specific to the current | ||
1955 | distribution. By default, this list includes the value of | ||
1956 | :term:`DISTRO`. | ||
1957 | |||
1958 | You can extend ``DISTROOVERRIDES`` to add extra overrides that should | ||
1959 | apply to the distribution. | ||
1960 | |||
1961 | The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it | ||
1962 | is included in the default value of | ||
1963 | :term:`OVERRIDES`. | ||
1964 | |||
1965 | :term:`DL_DIR` | ||
1966 | The central download directory used by the build process to store | ||
1967 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring | ||
1968 | for everything except Git repositories. If you want tarballs of Git | ||
1969 | repositories, use the | ||
1970 | :term:`BB_GENERATE_MIRROR_TARBALLS` | ||
1971 | variable. | ||
1972 | |||
1973 | You can set this directory by defining the ``DL_DIR`` variable in the | ||
1974 | ``conf/local.conf`` file. This directory is self-maintaining and you | ||
1975 | should not have to touch it. By default, the directory is | ||
1976 | ``downloads`` in the :term:`Build Directory`. | ||
1977 | :: | ||
1978 | |||
1979 | #DL_DIR ?= "${TOPDIR}/downloads" | ||
1980 | |||
1981 | To specify a different download directory, | ||
1982 | simply remove the comment from the line and provide your directory. | ||
1983 | |||
1984 | During a first build, the system downloads many different source code | ||
1985 | tarballs from various upstream projects. Downloading can take a | ||
1986 | while, particularly if your network connection is slow. Tarballs are | ||
1987 | all stored in the directory defined by ``DL_DIR`` and the build | ||
1988 | system looks there first to find source tarballs. | ||
1989 | |||
1990 | .. note:: | ||
1991 | |||
1992 | When wiping and rebuilding, you can preserve this directory to | ||
1993 | speed up this part of subsequent builds. | ||
1994 | |||
1995 | You can safely share this directory between multiple builds on the | ||
1996 | same development machine. For additional information on how the build | ||
1997 | process gets source files when working behind a firewall or proxy | ||
1998 | server, see this specific question in the ":doc:`faq`" | ||
1999 | chapter. You can also refer to the | ||
2000 | ":yocto_wiki:`Working Behind a Network Proxy </Working_Behind_a_Network_Proxy>`" | ||
2001 | Wiki page. | ||
2002 | |||
2003 | :term:`DOC_COMPRESS` | ||
2004 | When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` | ||
2005 | class, this variable sets the compression policy used when the | ||
2006 | OpenEmbedded build system compresses man pages and info pages. By | ||
2007 | default, the compression method used is gz (gzip). Other policies | ||
2008 | available are xz and bz2. | ||
2009 | |||
2010 | For information on policies and on how to use this variable, see the | ||
2011 | comments in the ``meta/classes/compress_doc.bbclass`` file. | ||
2012 | |||
2013 | :term:`EFI_PROVIDER` | ||
2014 | When building bootable images (i.e. where ``hddimg``, ``iso``, or | ||
2015 | ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the | ||
2016 | ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The | ||
2017 | default is "grub-efi", but "systemd-boot" can be used instead. | ||
2018 | |||
2019 | See the :ref:`systemd-boot <ref-classes-systemd-boot>` and | ||
2020 | :ref:`image-live <ref-classes-image-live>` classes for more | ||
2021 | information. | ||
2022 | |||
2023 | :term:`ENABLE_BINARY_LOCALE_GENERATION` | ||
2024 | Variable that controls which locales for ``glibc`` are generated | ||
2025 | during the build (useful if the target device has 64Mbytes of RAM or | ||
2026 | less). | ||
2027 | |||
2028 | :term:`ERR_REPORT_DIR` | ||
2029 | When used with the :ref:`report-error <ref-classes-report-error>` | ||
2030 | class, specifies the path used for storing the debug files created by | ||
2031 | the :ref:`error reporting | ||
2032 | tool <dev-manual/common-tasks:using the error reporting tool>`, which | ||
2033 | allows you to submit build errors you encounter to a central | ||
2034 | database. By default, the value of this variable is | ||
2035 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | ||
2036 | |||
2037 | You can set ``ERR_REPORT_DIR`` to the path you want the error | ||
2038 | reporting tool to store the debug files as follows in your | ||
2039 | ``local.conf`` file: | ||
2040 | :: | ||
2041 | |||
2042 | ERR_REPORT_DIR = "path" | ||
2043 | |||
2044 | :term:`ERROR_QA` | ||
2045 | Specifies the quality assurance checks whose failures are reported as | ||
2046 | errors by the OpenEmbedded build system. You set this variable in | ||
2047 | your distribution configuration file. For a list of the checks you | ||
2048 | can control with this variable, see the | ||
2049 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
2050 | |||
2051 | :term:`EXCLUDE_FROM_SHLIBS` | ||
2052 | Triggers the OpenEmbedded build system's shared libraries resolver to | ||
2053 | exclude an entire package when scanning for shared libraries. | ||
2054 | |||
2055 | .. note:: | ||
2056 | |||
2057 | The shared libraries resolver's functionality results in part from | ||
2058 | the internal function ``package_do_shlibs``, which is part of the | ||
2059 | :ref:`ref-tasks-package` task. You should be aware that the shared | ||
2060 | libraries resolver might implicitly define some dependencies between | ||
2061 | packages. | ||
2062 | |||
2063 | The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the | ||
2064 | :term:`PRIVATE_LIBS` variable, which excludes a | ||
2065 | package's particular libraries only and not the whole package. | ||
2066 | |||
2067 | Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a | ||
2068 | particular package: | ||
2069 | :: | ||
2070 | |||
2071 | EXCLUDE_FROM_SHLIBS = "1" | ||
2072 | |||
2073 | :term:`EXCLUDE_FROM_WORLD` | ||
2074 | Directs BitBake to exclude a recipe from world builds (i.e. | ||
2075 | ``bitbake world``). During world builds, BitBake locates, parses and | ||
2076 | builds all recipes found in every layer exposed in the | ||
2077 | ``bblayers.conf`` configuration file. | ||
2078 | |||
2079 | To exclude a recipe from a world build using this variable, set the | ||
2080 | variable to "1" in the recipe. | ||
2081 | |||
2082 | .. note:: | ||
2083 | |||
2084 | Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a | ||
2085 | world build in order to satisfy dependencies of other recipes. Adding | ||
2086 | a recipe to ``EXCLUDE_FROM_WORLD`` only ensures that the recipe is not | ||
2087 | explicitly added to the list of build targets in a world build. | ||
2088 | |||
2089 | :term:`EXTENDPE` | ||
2090 | Used with file and pathnames to create a prefix for a recipe's | ||
2091 | version based on the recipe's :term:`PE` value. If ``PE`` | ||
2092 | is set and greater than zero for a recipe, ``EXTENDPE`` becomes that | ||
2093 | value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). | ||
2094 | If a recipe's ``PE`` is not set (the default) or is equal to zero, | ||
2095 | ``EXTENDPE`` becomes "". | ||
2096 | |||
2097 | See the :term:`STAMP` variable for an example. | ||
2098 | |||
2099 | :term:`EXTENDPKGV` | ||
2100 | The full package version specification as it appears on the final | ||
2101 | packages produced by a recipe. The variable's value is normally used | ||
2102 | to fix a runtime dependency to the exact same version of another | ||
2103 | package in the same recipe: | ||
2104 | :: | ||
2105 | |||
2106 | RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" | ||
2107 | |||
2108 | The dependency relationships are intended to force the package | ||
2109 | manager to upgrade these types of packages in lock-step. | ||
2110 | |||
2111 | :term:`EXTERNAL_KERNEL_TOOLS` | ||
2112 | When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these | ||
2113 | tools are not in the source tree. | ||
2114 | |||
2115 | When kernel tools are available in the tree, they are preferred over | ||
2116 | any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` | ||
2117 | variable tells the OpenEmbedded build system to prefer the installed | ||
2118 | external tools. See the | ||
2119 | :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in | ||
2120 | ``meta/classes`` to see how the variable is used. | ||
2121 | |||
2122 | :term:`EXTERNALSRC` | ||
2123 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | ||
2124 | class, this variable points to the source tree, which is outside of | ||
2125 | the OpenEmbedded build system. When set, this variable sets the | ||
2126 | :term:`S` variable, which is what the OpenEmbedded build | ||
2127 | system uses to locate unpacked recipe source code. | ||
2128 | |||
2129 | For more information on ``externalsrc.bbclass``, see the | ||
2130 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2131 | can also find information on how to use this variable in the | ||
2132 | ":ref:`dev-manual/common-tasks:building software from an external source`" | ||
2133 | section in the Yocto Project Development Tasks Manual. | ||
2134 | |||
2135 | :term:`EXTERNALSRC_BUILD` | ||
2136 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | ||
2137 | class, this variable points to the directory in which the recipe's | ||
2138 | source code is built, which is outside of the OpenEmbedded build | ||
2139 | system. When set, this variable sets the :term:`B` variable, | ||
2140 | which is what the OpenEmbedded build system uses to locate the Build | ||
2141 | Directory. | ||
2142 | |||
2143 | For more information on ``externalsrc.bbclass``, see the | ||
2144 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2145 | can also find information on how to use this variable in the | ||
2146 | ":ref:`dev-manual/common-tasks:building software from an external source`" | ||
2147 | section in the Yocto Project Development Tasks Manual. | ||
2148 | |||
2149 | :term:`EXTRA_AUTORECONF` | ||
2150 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | ||
2151 | class, you can use ``EXTRA_AUTORECONF`` to specify extra options to | ||
2152 | pass to the ``autoreconf`` command that is executed during the | ||
2153 | :ref:`ref-tasks-configure` task. | ||
2154 | |||
2155 | The default value is "--exclude=autopoint". | ||
2156 | |||
2157 | :term:`EXTRA_IMAGE_FEATURES` | ||
2158 | A list of additional features to include in an image. When listing | ||
2159 | more than one feature, separate them with a space. | ||
2160 | |||
2161 | Typically, you configure this variable in your ``local.conf`` file, | ||
2162 | which is found in the :term:`Build Directory`. | ||
2163 | Although you can use this variable from within a recipe, best | ||
2164 | practices dictate that you do not. | ||
2165 | |||
2166 | .. note:: | ||
2167 | |||
2168 | To enable primary features from within the image recipe, use the | ||
2169 | :term:`IMAGE_FEATURES` variable. | ||
2170 | |||
2171 | Here are some examples of features you can add: | ||
2172 | |||
2173 | - "dbg-pkgs" - Adds -dbg packages for all installed packages including | ||
2174 | symbol information for debugging and profiling. | ||
2175 | |||
2176 | - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and | ||
2177 | enables post-installation logging. See the 'allow-empty-password' and | ||
2178 | 'post-install-logging' features in the ":ref:`ref-features-image`" | ||
2179 | section for more information. | ||
2180 | - "dev-pkgs" - Adds -dev packages for all installed packages. This is | ||
2181 | useful if you want to develop against the libraries in the image. | ||
2182 | - "read-only-rootfs" - Creates an image whose root filesystem is | ||
2183 | read-only. See the | ||
2184 | ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" | ||
2185 | section in the Yocto Project Development Tasks Manual for more | ||
2186 | information | ||
2187 | - "tools-debug" - Adds debugging tools such as gdb and strace. | ||
2188 | - "tools-sdk" - Adds development tools such as gcc, make, | ||
2189 | pkgconfig and so forth. | ||
2190 | - "tools-testapps" - Adds useful testing tools | ||
2191 | such as ts_print, aplay, arecord and so forth. | ||
2192 | |||
2193 | For a complete list of image features that ships with the Yocto | ||
2194 | Project, see the ":ref:`ref-features-image`" section. | ||
2195 | |||
2196 | For an example that shows how to customize your image by using this | ||
2197 | variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" | ||
2198 | section in the Yocto Project Development Tasks Manual. | ||
2199 | |||
2200 | :term:`EXTRA_IMAGECMD` | ||
2201 | Specifies additional options for the image creation command that has | ||
2202 | been specified in :term:`IMAGE_CMD`. When setting | ||
2203 | this variable, use an override for the associated image type. Here is | ||
2204 | an example: | ||
2205 | :: | ||
2206 | |||
2207 | EXTRA_IMAGECMD_ext3 ?= "-i 4096" | ||
2208 | |||
2209 | :term:`EXTRA_IMAGEDEPENDS` | ||
2210 | A list of recipes to build that do not provide packages for | ||
2211 | installing into the root filesystem. | ||
2212 | |||
2213 | Sometimes a recipe is required to build the final image but is not | ||
2214 | needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` | ||
2215 | variable to list these recipes and thus specify the dependencies. A | ||
2216 | typical example is a required bootloader in a machine configuration. | ||
2217 | |||
2218 | .. note:: | ||
2219 | |||
2220 | To add packages to the root filesystem, see the various | ||
2221 | \*:term:`RDEPENDS` and \*:term:`RRECOMMENDS` variables. | ||
2222 | |||
2223 | :term:`EXTRANATIVEPATH` | ||
2224 | A list of subdirectories of | ||
2225 | ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` | ||
2226 | added to the beginning of the environment variable ``PATH``. As an | ||
2227 | example, the following prepends | ||
2228 | "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to | ||
2229 | ``PATH``: | ||
2230 | :: | ||
2231 | |||
2232 | EXTRANATIVEPATH = "foo bar" | ||
2233 | |||
2234 | :term:`EXTRA_OECMAKE` | ||
2235 | Additional `CMake <https://cmake.org/overview/>`__ options. See the | ||
2236 | :ref:`cmake <ref-classes-cmake>` class for additional information. | ||
2237 | |||
2238 | :term:`EXTRA_OECONF` | ||
2239 | Additional ``configure`` script options. See | ||
2240 | :term:`PACKAGECONFIG_CONFARGS` for | ||
2241 | additional information on passing configure script options. | ||
2242 | |||
2243 | :term:`EXTRA_OEMAKE` | ||
2244 | Additional GNU ``make`` options. | ||
2245 | |||
2246 | Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the | ||
2247 | variable to specify any required GNU options. | ||
2248 | |||
2249 | :term:`PARALLEL_MAKE` and | ||
2250 | :term:`PARALLEL_MAKEINST` also make use of | ||
2251 | ``EXTRA_OEMAKE`` to pass the required flags. | ||
2252 | |||
2253 | :term:`EXTRA_OESCONS` | ||
2254 | When inheriting the :ref:`scons <ref-classes-scons>` class, this | ||
2255 | variable specifies additional configuration options you want to pass | ||
2256 | to the ``scons`` command line. | ||
2257 | |||
2258 | :term:`EXTRA_USERS_PARAMS` | ||
2259 | When inheriting the :ref:`extrausers <ref-classes-extrausers>` | ||
2260 | class, this variable provides image level user and group operations. | ||
2261 | This is a more global method of providing user and group | ||
2262 | configuration as compared to using the | ||
2263 | :ref:`useradd <ref-classes-useradd>` class, which ties user and | ||
2264 | group configurations to a specific recipe. | ||
2265 | |||
2266 | The set list of commands you can configure using the | ||
2267 | ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These | ||
2268 | commands map to the normal Unix commands of the same names: | ||
2269 | :: | ||
2270 | |||
2271 | # EXTRA_USERS_PARAMS = "\ | ||
2272 | # useradd -p '' tester; \ | ||
2273 | # groupadd developers; \ | ||
2274 | # userdel nobody; \ | ||
2275 | # groupdel -g video; \ | ||
2276 | # groupmod -g 1020 developers; \ | ||
2277 | # usermod -s /bin/sh tester; \ | ||
2278 | # " | ||
2279 | |||
2280 | :term:`FEATURE_PACKAGES` | ||
2281 | Defines one or more packages to include in an image when a specific | ||
2282 | item is included in :term:`IMAGE_FEATURES`. | ||
2283 | When setting the value, ``FEATURE_PACKAGES`` should have the name of | ||
2284 | the feature item as an override. Here is an example: | ||
2285 | :: | ||
2286 | |||
2287 | FEATURE_PACKAGES_widget = "package1 package2" | ||
2288 | |||
2289 | In this example, if "widget" were added to ``IMAGE_FEATURES``, | ||
2290 | package1 and package2 would be included in the image. | ||
2291 | |||
2292 | .. note:: | ||
2293 | |||
2294 | Packages installed by features defined through ``FEATURE_PACKAGES`` | ||
2295 | are often package groups. While similarly named, you should not | ||
2296 | confuse the ``FEATURE_PACKAGES`` variable with package groups, which | ||
2297 | are discussed elsewhere in the documentation. | ||
2298 | |||
2299 | :term:`FEED_DEPLOYDIR_BASE_URI` | ||
2300 | Points to the base URL of the server and location within the | ||
2301 | document-root that provides the metadata and packages required by | ||
2302 | OPKG to support runtime package management of IPK packages. You set | ||
2303 | this variable in your ``local.conf`` file. | ||
2304 | |||
2305 | Consider the following example: | ||
2306 | :: | ||
2307 | |||
2308 | FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" | ||
2309 | |||
2310 | This example assumes you are serving | ||
2311 | your packages over HTTP and your databases are located in a directory | ||
2312 | named ``BOARD-dir``, which is underneath your HTTP server's | ||
2313 | document-root. In this case, the OpenEmbedded build system generates | ||
2314 | a set of configuration files for you in your target that work with | ||
2315 | the feed. | ||
2316 | |||
2317 | :term:`FILES` | ||
2318 | The list of files and directories that are placed in a package. The | ||
2319 | :term:`PACKAGES` variable lists the packages | ||
2320 | generated by a recipe. | ||
2321 | |||
2322 | To use the ``FILES`` variable, provide a package name override that | ||
2323 | identifies the resulting package. Then, provide a space-separated | ||
2324 | list of files or paths that identify the files you want included as | ||
2325 | part of the resulting package. Here is an example: | ||
2326 | :: | ||
2327 | |||
2328 | FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" | ||
2329 | |||
2330 | .. note:: | ||
2331 | |||
2332 | - When specifying files or paths, you can pattern match using | ||
2333 | Python's | ||
2334 | `glob <https://docs.python.org/3/library/glob.html>`_ | ||
2335 | syntax. For details on the syntax, see the documentation by | ||
2336 | following the previous link. | ||
2337 | |||
2338 | - When specifying paths as part of the ``FILES`` variable, it is | ||
2339 | good practice to use appropriate path variables. For example, | ||
2340 | use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` | ||
2341 | rather than ``/usr/bin``. You can find a list of these | ||
2342 | variables at the top of the ``meta/conf/bitbake.conf`` file in | ||
2343 | the :term:`Source Directory`. You will also | ||
2344 | find the default values of the various ``FILES_*`` variables in | ||
2345 | this file. | ||
2346 | |||
2347 | If some of the files you provide with the ``FILES`` variable are | ||
2348 | editable and you know they should not be overwritten during the | ||
2349 | package update process by the Package Management System (PMS), you | ||
2350 | can identify these files so that the PMS will not overwrite them. See | ||
2351 | the :term:`CONFFILES` variable for information on | ||
2352 | how to identify these files to the PMS. | ||
2353 | |||
2354 | :term:`FILES_SOLIBSDEV` | ||
2355 | Defines the file specification to match | ||
2356 | :term:`SOLIBSDEV`. In other words, | ||
2357 | ``FILES_SOLIBSDEV`` defines the full path name of the development | ||
2358 | symbolic link (symlink) for shared libraries on the target platform. | ||
2359 | |||
2360 | The following statement from the ``bitbake.conf`` shows how it is | ||
2361 | set: | ||
2362 | :: | ||
2363 | |||
2364 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | ||
2365 | |||
2366 | :term:`FILESEXTRAPATHS` | ||
2367 | Extends the search path the OpenEmbedded build system uses when | ||
2368 | looking for files and patches as it processes recipes and append | ||
2369 | files. The default directories BitBake uses when it processes recipes | ||
2370 | are initially defined by the :term:`FILESPATH` | ||
2371 | variable. You can extend ``FILESPATH`` variable by using | ||
2372 | ``FILESEXTRAPATHS``. | ||
2373 | |||
2374 | Best practices dictate that you accomplish this by using | ||
2375 | ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you | ||
2376 | prepend paths as follows: | ||
2377 | :: | ||
2378 | |||
2379 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | ||
2380 | |||
2381 | In the above example, the build system first | ||
2382 | looks for files in a directory that has the same name as the | ||
2383 | corresponding append file. | ||
2384 | |||
2385 | .. note:: | ||
2386 | |||
2387 | When extending ``FILESEXTRAPATHS``, be sure to use the immediate | ||
2388 | expansion (``:=``) operator. Immediate expansion makes sure that | ||
2389 | BitBake evaluates :term:`THISDIR` at the time the | ||
2390 | directive is encountered rather than at some later time when | ||
2391 | expansion might result in a directory that does not contain the | ||
2392 | files you need. | ||
2393 | |||
2394 | Also, include the trailing separating colon character if you are | ||
2395 | prepending. The trailing colon character is necessary because you | ||
2396 | are directing BitBake to extend the path by prepending directories | ||
2397 | to the search path. | ||
2398 | |||
2399 | Here is another common use: | ||
2400 | :: | ||
2401 | |||
2402 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | ||
2403 | |||
2404 | In this example, the build system extends the | ||
2405 | ``FILESPATH`` variable to include a directory named ``files`` that is | ||
2406 | in the same directory as the corresponding append file. | ||
2407 | |||
2408 | This next example specifically adds three paths: | ||
2409 | :: | ||
2410 | |||
2411 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | ||
2412 | |||
2413 | A final example shows how you can extend the search path and include | ||
2414 | a :term:`MACHINE`-specific override, which is useful | ||
2415 | in a BSP layer: | ||
2416 | :: | ||
2417 | |||
2418 | FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" | ||
2419 | |||
2420 | The previous statement appears in the | ||
2421 | ``linux-yocto-dev.bbappend`` file, which is found in the | ||
2422 | :ref:`overview-manual/development-environment:yocto project source repositories` in | ||
2423 | ``meta-intel/common/recipes-kernel/linux``. Here, the machine | ||
2424 | override is a special :term:`PACKAGE_ARCH` | ||
2425 | definition for multiple ``meta-intel`` machines. | ||
2426 | |||
2427 | .. note:: | ||
2428 | |||
2429 | For a layer that supports a single BSP, the override could just be | ||
2430 | the value of ``MACHINE``. | ||
2431 | |||
2432 | By prepending paths in ``.bbappend`` files, you allow multiple append | ||
2433 | files that reside in different layers but are used for the same | ||
2434 | recipe to correctly extend the path. | ||
2435 | |||
2436 | :term:`FILESOVERRIDES` | ||
2437 | A subset of :term:`OVERRIDES` used by the | ||
2438 | OpenEmbedded build system for creating | ||
2439 | :term:`FILESPATH`. The ``FILESOVERRIDES`` variable | ||
2440 | uses overrides to automatically extend the | ||
2441 | :term:`FILESPATH` variable. For an example of how | ||
2442 | that works, see the :term:`FILESPATH` variable | ||
2443 | description. Additionally, you find more information on how overrides | ||
2444 | are handled in the | ||
2445 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" | ||
2446 | section of the BitBake User Manual. | ||
2447 | |||
2448 | By default, the ``FILESOVERRIDES`` variable is defined as: | ||
2449 | :: | ||
2450 | |||
2451 | FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" | ||
2452 | |||
2453 | .. note:: | ||
2454 | |||
2455 | Do not hand-edit the ``FILESOVERRIDES`` variable. The values match up | ||
2456 | with expected overrides and are used in an expected manner by the | ||
2457 | build system. | ||
2458 | |||
2459 | :term:`FILESPATH` | ||
2460 | The default set of directories the OpenEmbedded build system uses | ||
2461 | when searching for patches and files. | ||
2462 | |||
2463 | During the build process, BitBake searches each directory in | ||
2464 | ``FILESPATH`` in the specified order when looking for files and | ||
2465 | patches specified by each ``file://`` URI in a recipe's | ||
2466 | :term:`SRC_URI` statements. | ||
2467 | |||
2468 | The default value for the ``FILESPATH`` variable is defined in the | ||
2469 | ``base.bbclass`` class found in ``meta/classes`` in the | ||
2470 | :term:`Source Directory`: | ||
2471 | :: | ||
2472 | |||
2473 | FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ | ||
2474 | "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" | ||
2475 | |||
2476 | The | ||
2477 | ``FILESPATH`` variable is automatically extended using the overrides | ||
2478 | from the :term:`FILESOVERRIDES` variable. | ||
2479 | |||
2480 | .. note:: | ||
2481 | |||
2482 | - Do not hand-edit the ``FILESPATH`` variable. If you want the | ||
2483 | build system to look in directories other than the defaults, | ||
2484 | extend the ``FILESPATH`` variable by using the | ||
2485 | :term:`FILESEXTRAPATHS` variable. | ||
2486 | |||
2487 | - Be aware that the default ``FILESPATH`` directories do not map | ||
2488 | to directories in custom layers where append files | ||
2489 | (``.bbappend``) are used. If you want the build system to find | ||
2490 | patches or files that reside with your append files, you need | ||
2491 | to extend the ``FILESPATH`` variable by using the | ||
2492 | ``FILESEXTRAPATHS`` variable. | ||
2493 | |||
2494 | You can take advantage of this searching behavior in useful ways. For | ||
2495 | example, consider a case where the following directory structure | ||
2496 | exists for general and machine-specific configurations: | ||
2497 | :: | ||
2498 | |||
2499 | files/defconfig | ||
2500 | files/MACHINEA/defconfig | ||
2501 | files/MACHINEB/defconfig | ||
2502 | |||
2503 | Also in the example, the ``SRC_URI`` statement contains | ||
2504 | "file://defconfig". Given this scenario, you can set | ||
2505 | :term:`MACHINE` to "MACHINEA" and cause the build | ||
2506 | system to use files from ``files/MACHINEA``. Set ``MACHINE`` to | ||
2507 | "MACHINEB" and the build system uses files from ``files/MACHINEB``. | ||
2508 | Finally, for any machine other than "MACHINEA" and "MACHINEB", the | ||
2509 | build system uses files from ``files/defconfig``. | ||
2510 | |||
2511 | You can find out more about the patching process in the | ||
2512 | ":ref:`overview-manual/concepts:patching`" section | ||
2513 | in the Yocto Project Overview and Concepts Manual and the | ||
2514 | ":ref:`dev-manual/common-tasks:patching code`" section in | ||
2515 | the Yocto Project Development Tasks Manual. See the | ||
2516 | :ref:`ref-tasks-patch` task as well. | ||
2517 | |||
2518 | :term:`FILESYSTEM_PERMS_TABLES` | ||
2519 | Allows you to define your own file permissions settings table as part | ||
2520 | of your configuration for the packaging process. For example, suppose | ||
2521 | you need a consistent set of custom permissions for a set of groups | ||
2522 | and users across an entire work project. It is best to do this in the | ||
2523 | packages themselves but this is not always possible. | ||
2524 | |||
2525 | By default, the OpenEmbedded build system uses the ``fs-perms.txt``, | ||
2526 | which is located in the ``meta/files`` folder in the :term:`Source Directory`. | ||
2527 | If you create your own file | ||
2528 | permissions setting table, you should place it in your layer or the | ||
2529 | distro's layer. | ||
2530 | |||
2531 | You define the ``FILESYSTEM_PERMS_TABLES`` variable in the | ||
2532 | ``conf/local.conf`` file, which is found in the :term:`Build Directory`, | ||
2533 | to point to your custom | ||
2534 | ``fs-perms.txt``. You can specify more than a single file permissions | ||
2535 | setting table. The paths you specify to these files must be defined | ||
2536 | within the :term:`BBPATH` variable. | ||
2537 | |||
2538 | For guidance on how to create your own file permissions settings | ||
2539 | table file, examine the existing ``fs-perms.txt``. | ||
2540 | |||
2541 | :term:`FIT_GENERATE_KEYS` | ||
2542 | Decides whether to generate the keys for signing fitImage if they | ||
2543 | don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``. | ||
2544 | The default value is 0. | ||
2545 | |||
2546 | :term:`FIT_HASH_ALG` | ||
2547 | Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. | ||
2548 | |||
2549 | :term:`FIT_KEY_GENRSA_ARGS` | ||
2550 | Arguments to openssl genrsa for generating RSA private key for signing | ||
2551 | fitImage. The default value is "-F4". i.e. the public exponent 65537 to | ||
2552 | use. | ||
2553 | |||
2554 | :term:`FIT_KEY_REQ_ARGS` | ||
2555 | Arguments to openssl req for generating certificate for signing fitImage. | ||
2556 | The default value is "-batch -new". batch for non interactive mode | ||
2557 | and new for generating new keys. | ||
2558 | |||
2559 | :term:`FIT_KEY_SIGN_PKCS` | ||
2560 | Format for public key ceritifcate used in signing fitImage. | ||
2561 | The default value is "x509". | ||
2562 | |||
2563 | :term:`FIT_SIGN_ALG` | ||
2564 | Specifies the signature algorithm used in creating the FIT Image. | ||
2565 | For e.g. rsa2048. | ||
2566 | |||
2567 | :term:`FIT_SIGN_NUMBITS` | ||
2568 | Size of private key in number of bits used in fitImage. The default | ||
2569 | value is "2048". | ||
2570 | |||
2571 | :term:`FONT_EXTRA_RDEPENDS` | ||
2572 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | ||
2573 | this variable specifies the runtime dependencies for font packages. | ||
2574 | By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". | ||
2575 | |||
2576 | :term:`FONT_PACKAGES` | ||
2577 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | ||
2578 | this variable identifies packages containing font files that need to | ||
2579 | be cached by Fontconfig. By default, the ``fontcache`` class assumes | ||
2580 | that fonts are in the recipe's main package (i.e. | ||
2581 | ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you | ||
2582 | need are in a package other than that main package. | ||
2583 | |||
2584 | :term:`FORCE_RO_REMOVE` | ||
2585 | Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` | ||
2586 | during the generation of the root filesystem. | ||
2587 | |||
2588 | Set the variable to "1" to force the removal of these packages. | ||
2589 | |||
2590 | :term:`FULL_OPTIMIZATION` | ||
2591 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | ||
2592 | compiling an optimized system. This variable defaults to "-O2 -pipe | ||
2593 | ${DEBUG_FLAGS}". | ||
2594 | |||
2595 | :term:`GCCPIE` | ||
2596 | Enables Position Independent Executables (PIE) within the GNU C | ||
2597 | Compiler (GCC). Enabling PIE in the GCC makes Return Oriented | ||
2598 | Programming (ROP) attacks much more difficult to execute. | ||
2599 | |||
2600 | By default the ``security_flags.inc`` file enables PIE by setting the | ||
2601 | variable as follows: | ||
2602 | :: | ||
2603 | |||
2604 | GCCPIE ?= "--enable-default-pie" | ||
2605 | |||
2606 | :term:`GCCVERSION` | ||
2607 | Specifies the default version of the GNU C Compiler (GCC) used for | ||
2608 | compilation. By default, ``GCCVERSION`` is set to "8.x" in the | ||
2609 | ``meta/conf/distro/include/tcmode-default.inc`` include file: | ||
2610 | :: | ||
2611 | |||
2612 | GCCVERSION ?= "8.%" | ||
2613 | |||
2614 | You can override this value by setting it in a | ||
2615 | configuration file such as the ``local.conf``. | ||
2616 | |||
2617 | :term:`GDB` | ||
2618 | The minimal command and arguments to run the GNU Debugger. | ||
2619 | |||
2620 | :term:`GITDIR` | ||
2621 | The directory in which a local copy of a Git repository is stored | ||
2622 | when it is cloned. | ||
2623 | |||
2624 | :term:`GLIBC_GENERATE_LOCALES` | ||
2625 | Specifies the list of GLIBC locales to generate should you not wish | ||
2626 | to generate all LIBC locals, which can be time consuming. | ||
2627 | |||
2628 | .. note:: | ||
2629 | |||
2630 | If you specifically remove the locale ``en_US.UTF-8``, you must set | ||
2631 | :term:`IMAGE_LINGUAS` appropriately. | ||
2632 | |||
2633 | You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. | ||
2634 | By default, all locales are generated. | ||
2635 | :: | ||
2636 | |||
2637 | GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" | ||
2638 | |||
2639 | :term:`GROUPADD_PARAM` | ||
2640 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
2641 | this variable specifies for a package what parameters should be | ||
2642 | passed to the ``groupadd`` command if you wish to add a group to the | ||
2643 | system when the package is installed. | ||
2644 | |||
2645 | Here is an example from the ``dbus`` recipe: | ||
2646 | :: | ||
2647 | |||
2648 | GROUPADD_PARAM_${PN} = "-r netdev" | ||
2649 | |||
2650 | For information on the standard Linux shell command | ||
2651 | ``groupadd``, see http://linux.die.net/man/8/groupadd. | ||
2652 | |||
2653 | :term:`GROUPMEMS_PARAM` | ||
2654 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
2655 | this variable specifies for a package what parameters should be | ||
2656 | passed to the ``groupmems`` command if you wish to modify the members | ||
2657 | of a group when the package is installed. | ||
2658 | |||
2659 | For information on the standard Linux shell command ``groupmems``, | ||
2660 | see http://linux.die.net/man/8/groupmems. | ||
2661 | |||
2662 | :term:`GRUB_GFXSERIAL` | ||
2663 | Configures the GNU GRand Unified Bootloader (GRUB) to have graphics | ||
2664 | and serial in the boot menu. Set this variable to "1" in your | ||
2665 | ``local.conf`` or distribution configuration file to enable graphics | ||
2666 | and serial in the menu. | ||
2667 | |||
2668 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
2669 | information on how this variable is used. | ||
2670 | |||
2671 | :term:`GRUB_OPTS` | ||
2672 | Additional options to add to the GNU GRand Unified Bootloader (GRUB) | ||
2673 | configuration. Use a semi-colon character (``;``) to separate | ||
2674 | multiple options. | ||
2675 | |||
2676 | The ``GRUB_OPTS`` variable is optional. See the | ||
2677 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | ||
2678 | on how this variable is used. | ||
2679 | |||
2680 | :term:`GRUB_TIMEOUT` | ||
2681 | Specifies the timeout before executing the default ``LABEL`` in the | ||
2682 | GNU GRand Unified Bootloader (GRUB). | ||
2683 | |||
2684 | The ``GRUB_TIMEOUT`` variable is optional. See the | ||
2685 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | ||
2686 | on how this variable is used. | ||
2687 | |||
2688 | :term:`GTKIMMODULES_PACKAGES` | ||
2689 | When inheriting the | ||
2690 | :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class, | ||
2691 | this variable specifies the packages that contain the GTK+ input | ||
2692 | method modules being installed when the modules are in packages other | ||
2693 | than the main package. | ||
2694 | |||
2695 | :term:`HOMEPAGE` | ||
2696 | Website where more information about the software the recipe is | ||
2697 | building can be found. | ||
2698 | |||
2699 | :term:`HOST_ARCH` | ||
2700 | The name of the target architecture, which is normally the same as | ||
2701 | :term:`TARGET_ARCH`. The OpenEmbedded build system | ||
2702 | supports many architectures. Here is an example list of architectures | ||
2703 | supported. This list is by no means complete as the architecture is | ||
2704 | configurable: | ||
2705 | |||
2706 | - arm | ||
2707 | - i586 | ||
2708 | - x86_64 | ||
2709 | - powerpc | ||
2710 | - powerpc64 | ||
2711 | - mips | ||
2712 | - mipsel | ||
2713 | |||
2714 | :term:`HOST_CC_ARCH` | ||
2715 | Specifies architecture-specific compiler flags that are passed to the | ||
2716 | C compiler. | ||
2717 | |||
2718 | Default initialization for ``HOST_CC_ARCH`` varies depending on what | ||
2719 | is being built: | ||
2720 | |||
2721 | - :term:`TARGET_CC_ARCH` when building for the | ||
2722 | target | ||
2723 | |||
2724 | - :term:`BUILD_CC_ARCH` when building for the build host (i.e. | ||
2725 | ``-native``) | ||
2726 | |||
2727 | - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. | ||
2728 | ``nativesdk-``) | ||
2729 | |||
2730 | :term:`HOST_OS` | ||
2731 | Specifies the name of the target operating system, which is normally | ||
2732 | the same as the :term:`TARGET_OS`. The variable can | ||
2733 | be set to "linux" for ``glibc``-based systems and to "linux-musl" for | ||
2734 | ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and | ||
2735 | "linux-musleabi" values possible. | ||
2736 | |||
2737 | :term:`HOST_PREFIX` | ||
2738 | Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` | ||
2739 | is normally the same as :term:`TARGET_PREFIX`. | ||
2740 | |||
2741 | :term:`HOST_SYS` | ||
2742 | Specifies the system, including the architecture and the operating | ||
2743 | system, for which the build is occurring in the context of the | ||
2744 | current recipe. | ||
2745 | |||
2746 | The OpenEmbedded build system automatically sets this variable based | ||
2747 | on :term:`HOST_ARCH`, | ||
2748 | :term:`HOST_VENDOR`, and | ||
2749 | :term:`HOST_OS` variables. | ||
2750 | |||
2751 | .. note:: | ||
2752 | |||
2753 | You do not need to set the variable yourself. | ||
2754 | |||
2755 | Consider these two examples: | ||
2756 | |||
2757 | - Given a native recipe on a 32-bit x86 machine running Linux, the | ||
2758 | value is "i686-linux". | ||
2759 | |||
2760 | - Given a recipe being built for a little-endian MIPS target running | ||
2761 | Linux, the value might be "mipsel-linux". | ||
2762 | |||
2763 | :term:`HOSTTOOLS` | ||
2764 | A space-separated list (filter) of tools on the build host that | ||
2765 | should be allowed to be called from within build tasks. Using this | ||
2766 | filter helps reduce the possibility of host contamination. If a tool | ||
2767 | specified in the value of ``HOSTTOOLS`` is not found on the build | ||
2768 | host, the OpenEmbedded build system produces an error and the build | ||
2769 | is not started. | ||
2770 | |||
2771 | For additional information, see | ||
2772 | :term:`HOSTTOOLS_NONFATAL`. | ||
2773 | |||
2774 | :term:`HOSTTOOLS_NONFATAL` | ||
2775 | A space-separated list (filter) of tools on the build host that | ||
2776 | should be allowed to be called from within build tasks. Using this | ||
2777 | filter helps reduce the possibility of host contamination. Unlike | ||
2778 | :term:`HOSTTOOLS`, the OpenEmbedded build system | ||
2779 | does not produce an error if a tool specified in the value of | ||
2780 | ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can | ||
2781 | use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. | ||
2782 | |||
2783 | :term:`HOST_VENDOR` | ||
2784 | Specifies the name of the vendor. ``HOST_VENDOR`` is normally the | ||
2785 | same as :term:`TARGET_VENDOR`. | ||
2786 | |||
2787 | :term:`ICECC_DISABLED` | ||
2788 | Disables or enables the ``icecc`` (Icecream) function. For more | ||
2789 | information on this function and best practices for using this | ||
2790 | variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" | ||
2791 | section. | ||
2792 | |||
2793 | Setting this variable to "1" in your ``local.conf`` disables the | ||
2794 | function: | ||
2795 | :: | ||
2796 | |||
2797 | ICECC_DISABLED ??= "1" | ||
2798 | |||
2799 | To enable the function, set the variable as follows: | ||
2800 | :: | ||
2801 | |||
2802 | ICECC_DISABLED = "" | ||
2803 | |||
2804 | :term:`ICECC_ENV_EXEC` | ||
2805 | Points to the ``icecc-create-env`` script that you provide. This | ||
2806 | variable is used by the :ref:`icecc <ref-classes-icecc>` class. You | ||
2807 | set this variable in your ``local.conf`` file. | ||
2808 | |||
2809 | If you do not point to a script that you provide, the OpenEmbedded | ||
2810 | build system uses the default script provided by the | ||
2811 | ``icecc-create-env.bb`` recipe, which is a modified version and not | ||
2812 | the one that comes with ``icecc``. | ||
2813 | |||
2814 | :term:`ICECC_PARALLEL_MAKE` | ||
2815 | Extra options passed to the ``make`` command during the | ||
2816 | :ref:`ref-tasks-compile` task that specify parallel | ||
2817 | compilation. This variable usually takes the form of "-j x", where x | ||
2818 | represents the maximum number of parallel threads ``make`` can run. | ||
2819 | |||
2820 | .. note:: | ||
2821 | |||
2822 | The options passed affect builds on all enabled machines on the | ||
2823 | network, which are machines running the ``iceccd`` daemon. | ||
2824 | |||
2825 | If your enabled machines support multiple cores, coming up with the | ||
2826 | maximum number of parallel threads that gives you the best | ||
2827 | performance could take some experimentation since machine speed, | ||
2828 | network lag, available memory, and existing machine loads can all | ||
2829 | affect build time. Consequently, unlike the | ||
2830 | :term:`PARALLEL_MAKE` variable, there is no | ||
2831 | rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal | ||
2832 | performance. | ||
2833 | |||
2834 | If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not | ||
2835 | use it (i.e. the system does not detect and assign the number of | ||
2836 | cores as is done with ``PARALLEL_MAKE``). | ||
2837 | |||
2838 | :term:`ICECC_PATH` | ||
2839 | The location of the ``icecc`` binary. You can set this variable in | ||
2840 | your ``local.conf`` file. If your ``local.conf`` file does not define | ||
2841 | this variable, the :ref:`icecc <ref-classes-icecc>` class attempts | ||
2842 | to define it by locating ``icecc`` using ``which``. | ||
2843 | |||
2844 | :term:`ICECC_USER_CLASS_BL` | ||
2845 | Identifies user classes that you do not want the Icecream distributed | ||
2846 | compile support to consider. This variable is used by the | ||
2847 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2848 | your ``local.conf`` file. | ||
2849 | |||
2850 | When you list classes using this variable, you are "blacklisting" | ||
2851 | them from distributed compilation across remote hosts. Any classes | ||
2852 | you list will be distributed and compiled locally. | ||
2853 | |||
2854 | :term:`ICECC_USER_PACKAGE_BL` | ||
2855 | Identifies user recipes that you do not want the Icecream distributed | ||
2856 | compile support to consider. This variable is used by the | ||
2857 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2858 | your ``local.conf`` file. | ||
2859 | |||
2860 | When you list packages using this variable, you are "blacklisting" | ||
2861 | them from distributed compilation across remote hosts. Any packages | ||
2862 | you list will be distributed and compiled locally. | ||
2863 | |||
2864 | :term:`ICECC_USER_PACKAGE_WL` | ||
2865 | Identifies user recipes that use an empty | ||
2866 | :term:`PARALLEL_MAKE` variable that you want to | ||
2867 | force remote distributed compilation on using the Icecream | ||
2868 | distributed compile support. This variable is used by the | ||
2869 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2870 | your ``local.conf`` file. | ||
2871 | |||
2872 | :term:`IMAGE_BASENAME` | ||
2873 | The base name of image output files. This variable defaults to the | ||
2874 | recipe name (``${``\ :term:`PN`\ ``}``). | ||
2875 | |||
2876 | :term:`IMAGE_EFI_BOOT_FILES` | ||
2877 | A space-separated list of files installed into the boot partition | ||
2878 | when preparing an image using the Wic tool with the | ||
2879 | ``bootimg-efi`` source plugin. By default, | ||
2880 | the files are | ||
2881 | installed under the same name as the source files. To change the | ||
2882 | installed name, separate it from the original name with a semi-colon | ||
2883 | (;). Source files need to be located in | ||
2884 | :term:`DEPLOY_DIR_IMAGE`. Here are two | ||
2885 | examples: | ||
2886 | :: | ||
2887 | |||
2888 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" | ||
2889 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" | ||
2890 | |||
2891 | Alternatively, source files can be picked up using a glob pattern. In | ||
2892 | this case, the destination file must have the same name as the base | ||
2893 | name of the source file path. To install files into a directory | ||
2894 | within the target location, pass its name after a semi-colon (;). | ||
2895 | Here are two examples: | ||
2896 | :: | ||
2897 | |||
2898 | IMAGE_EFI_BOOT_FILES = "boot/loader/*" | ||
2899 | IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" | ||
2900 | |||
2901 | The first example | ||
2902 | installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` | ||
2903 | into the root of the target partition. The second example installs | ||
2904 | the same files into a ``boot`` directory within the target partition. | ||
2905 | |||
2906 | You can find information on how to use the Wic tool in the | ||
2907 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | ||
2908 | section of the Yocto Project Development Tasks Manual. Reference | ||
2909 | material for Wic is located in the | ||
2910 | ":doc:`/ref-manual/kickstart`" chapter. | ||
2911 | |||
2912 | :term:`IMAGE_BOOT_FILES` | ||
2913 | A space-separated list of files installed into the boot partition | ||
2914 | when preparing an image using the Wic tool with the | ||
2915 | ``bootimg-partition`` source plugin. By default, | ||
2916 | the files are | ||
2917 | installed under the same name as the source files. To change the | ||
2918 | installed name, separate it from the original name with a semi-colon | ||
2919 | (;). Source files need to be located in | ||
2920 | :term:`DEPLOY_DIR_IMAGE`. Here are two | ||
2921 | examples: | ||
2922 | :: | ||
2923 | |||
2924 | IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" | ||
2925 | IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" | ||
2926 | |||
2927 | Alternatively, source files can be picked up using a glob pattern. In | ||
2928 | this case, the destination file must have the same name as the base | ||
2929 | name of the source file path. To install files into a directory | ||
2930 | within the target location, pass its name after a semi-colon (;). | ||
2931 | Here are two examples: | ||
2932 | :: | ||
2933 | |||
2934 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" | ||
2935 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" | ||
2936 | |||
2937 | The first example | ||
2938 | installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` | ||
2939 | into the root of the target partition. The second example installs | ||
2940 | the same files into a ``boot`` directory within the target partition. | ||
2941 | |||
2942 | You can find information on how to use the Wic tool in the | ||
2943 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | ||
2944 | section of the Yocto Project Development Tasks Manual. Reference | ||
2945 | material for Wic is located in the | ||
2946 | ":doc:`/ref-manual/kickstart`" chapter. | ||
2947 | |||
2948 | :term:`IMAGE_CLASSES` | ||
2949 | A list of classes that all images should inherit. You typically use | ||
2950 | this variable to specify the list of classes that register the | ||
2951 | different types of images the OpenEmbedded build system creates. | ||
2952 | |||
2953 | The default value for ``IMAGE_CLASSES`` is ``image_types``. You can | ||
2954 | set this variable in your ``local.conf`` or in a distribution | ||
2955 | configuration file. | ||
2956 | |||
2957 | For more information, see ``meta/classes/image_types.bbclass`` in the | ||
2958 | :term:`Source Directory`. | ||
2959 | |||
2960 | :term:`IMAGE_CMD` | ||
2961 | Specifies the command to create the image file for a specific image | ||
2962 | type, which corresponds to the value set set in | ||
2963 | :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, | ||
2964 | ``btrfs``, and so forth). When setting this variable, you should use | ||
2965 | an override for the associated type. Here is an example: | ||
2966 | :: | ||
2967 | |||
2968 | IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ | ||
2969 | --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ | ||
2970 | ${EXTRA_IMAGECMD}" | ||
2971 | |||
2972 | You typically do not need to set this variable unless you are adding | ||
2973 | support for a new image type. For more examples on how to set this | ||
2974 | variable, see the :ref:`image_types <ref-classes-image_types>` | ||
2975 | class file, which is ``meta/classes/image_types.bbclass``. | ||
2976 | |||
2977 | :term:`IMAGE_DEVICE_TABLES` | ||
2978 | Specifies one or more files that contain custom device tables that | ||
2979 | are passed to the ``makedevs`` command as part of creating an image. | ||
2980 | These files list basic device nodes that should be created under | ||
2981 | ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, | ||
2982 | ``files/device_table-minimal.txt`` is used, which is located by | ||
2983 | :term:`BBPATH`. For details on how you should write | ||
2984 | device table files, see ``meta/files/device_table-minimal.txt`` as an | ||
2985 | example. | ||
2986 | |||
2987 | :term:`IMAGE_FEATURES` | ||
2988 | The primary list of features to include in an image. Typically, you | ||
2989 | configure this variable in an image recipe. Although you can use this | ||
2990 | variable from your ``local.conf`` file, which is found in the | ||
2991 | :term:`Build Directory`, best practices dictate that you do | ||
2992 | not. | ||
2993 | |||
2994 | .. note:: | ||
2995 | |||
2996 | To enable extra features from outside the image recipe, use the | ||
2997 | :term:`EXTRA_IMAGE_FEATURES` variable. | ||
2998 | |||
2999 | For a list of image features that ships with the Yocto Project, see | ||
3000 | the ":ref:`ref-features-image`" section. | ||
3001 | |||
3002 | For an example that shows how to customize your image by using this | ||
3003 | variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" | ||
3004 | section in the Yocto Project Development Tasks Manual. | ||
3005 | |||
3006 | :term:`IMAGE_FSTYPES` | ||
3007 | Specifies the formats the OpenEmbedded build system uses during the | ||
3008 | build when creating the root filesystem. For example, setting | ||
3009 | ``IMAGE_FSTYPES`` as follows causes the build system to create root | ||
3010 | filesystems using two formats: ``.ext3`` and ``.tar.bz2``: | ||
3011 | :: | ||
3012 | |||
3013 | IMAGE_FSTYPES = "ext3 tar.bz2" | ||
3014 | |||
3015 | For the complete list of supported image formats from which you can | ||
3016 | choose, see :term:`IMAGE_TYPES`. | ||
3017 | |||
3018 | .. note:: | ||
3019 | |||
3020 | - If an image recipe uses the "inherit image" line and you are | ||
3021 | setting ``IMAGE_FSTYPES`` inside the recipe, you must set | ||
3022 | ``IMAGE_FSTYPES`` prior to using the "inherit image" line. | ||
3023 | |||
3024 | - Due to the way the OpenEmbedded build system processes this | ||
3025 | variable, you cannot update its contents by using ``_append`` | ||
3026 | or ``_prepend``. You must use the ``+=`` operator to add one or | ||
3027 | more options to the ``IMAGE_FSTYPES`` variable. | ||
3028 | |||
3029 | :term:`IMAGE_INSTALL` | ||
3030 | Used by recipes to specify the packages to install into an image | ||
3031 | through the :ref:`image <ref-classes-image>` class. Use the | ||
3032 | ``IMAGE_INSTALL`` variable with care to avoid ordering issues. | ||
3033 | |||
3034 | Image recipes set ``IMAGE_INSTALL`` to specify the packages to | ||
3035 | install into an image through ``image.bbclass``. Additionally, | ||
3036 | "helper" classes such as the | ||
3037 | :ref:`core-image <ref-classes-core-image>` class exist that can | ||
3038 | take lists used with ``IMAGE_FEATURES`` and turn them into | ||
3039 | auto-generated entries in ``IMAGE_INSTALL`` in addition to its | ||
3040 | default contents. | ||
3041 | |||
3042 | When you use this variable, it is best to use it as follows: | ||
3043 | :: | ||
3044 | |||
3045 | IMAGE_INSTALL_append = " package-name" | ||
3046 | |||
3047 | Be sure to include the space | ||
3048 | between the quotation character and the start of the package name or | ||
3049 | names. | ||
3050 | |||
3051 | .. note:: | ||
3052 | |||
3053 | - When working with a | ||
3054 | :ref:`core-image-minimal-initramfs <ref-manual/images:images>` | ||
3055 | image, do not use the ``IMAGE_INSTALL`` variable to specify | ||
3056 | packages for installation. Instead, use the | ||
3057 | :term:`PACKAGE_INSTALL` variable, which | ||
3058 | allows the initial RAM filesystem (initramfs) recipe to use a | ||
3059 | fixed set of packages and not be affected by ``IMAGE_INSTALL``. | ||
3060 | For information on creating an initramfs, see the | ||
3061 | ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" | ||
3062 | section in the Yocto Project Development Tasks Manual. | ||
3063 | |||
3064 | - Using ``IMAGE_INSTALL`` with the | ||
3065 | :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` | ||
3066 | BitBake operator within the ``/conf/local.conf`` file or from | ||
3067 | within an image recipe is not recommended. Use of this operator | ||
3068 | in these ways can cause ordering issues. Since | ||
3069 | ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default | ||
3070 | value using the | ||
3071 | :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` | ||
3072 | operator, using a ``+=`` operation against ``IMAGE_INSTALL`` | ||
3073 | results in unexpected behavior when used within | ||
3074 | ``conf/local.conf``. Furthermore, the same operation from | ||
3075 | within an image recipe may or may not succeed depending on the | ||
3076 | specific situation. In both these cases, the behavior is | ||
3077 | contrary to how most users expect the ``+=`` operator to work. | ||
3078 | |||
3079 | :term:`IMAGE_LINGUAS` | ||
3080 | Specifies the list of locales to install into the image during the | ||
3081 | root filesystem construction process. The OpenEmbedded build system | ||
3082 | automatically splits locale files, which are used for localization, | ||
3083 | into separate packages. Setting the ``IMAGE_LINGUAS`` variable | ||
3084 | ensures that any locale packages that correspond to packages already | ||
3085 | selected for installation into the image are also installed. Here is | ||
3086 | an example: | ||
3087 | :: | ||
3088 | |||
3089 | IMAGE_LINGUAS = "pt-br de-de" | ||
3090 | |||
3091 | In this example, the build system ensures any Brazilian Portuguese | ||
3092 | and German locale files that correspond to packages in the image are | ||
3093 | installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as | ||
3094 | ``*-locale-pt`` and ``*-locale-de``, since some software packages | ||
3095 | only provide locale files by language and not by country-specific | ||
3096 | language). | ||
3097 | |||
3098 | See the :term:`GLIBC_GENERATE_LOCALES` | ||
3099 | variable for information on generating GLIBC locales. | ||
3100 | |||
3101 | |||
3102 | :term:`IMAGE_LINK_NAME` | ||
3103 | The name of the output image symlink (which does not include | ||
3104 | the version part as :term:`IMAGE_NAME` does). The default value | ||
3105 | is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE` | ||
3106 | variables: | ||
3107 | :: | ||
3108 | |||
3109 | IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}" | ||
3110 | |||
3111 | |||
3112 | :term:`IMAGE_MANIFEST` | ||
3113 | The manifest file for the image. This file lists all the installed | ||
3114 | packages that make up the image. The file contains package | ||
3115 | information on a line-per-package basis as follows: | ||
3116 | :: | ||
3117 | |||
3118 | packagename packagearch version | ||
3119 | |||
3120 | The :ref:`image <ref-classes-image>` class defines the manifest | ||
3121 | file as follows: | ||
3122 | :: | ||
3123 | |||
3124 | IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" | ||
3125 | |||
3126 | The location is | ||
3127 | derived using the :term:`DEPLOY_DIR_IMAGE` | ||
3128 | and :term:`IMAGE_NAME` variables. You can find | ||
3129 | information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" | ||
3130 | section in the Yocto Project Overview and Concepts Manual. | ||
3131 | |||
3132 | :term:`IMAGE_NAME` | ||
3133 | The name of the output image files minus the extension. This variable | ||
3134 | is derived using the :term:`IMAGE_BASENAME`, | ||
3135 | :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX` | ||
3136 | variables: | ||
3137 | :: | ||
3138 | |||
3139 | IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3140 | |||
3141 | :term:`IMAGE_NAME_SUFFIX` | ||
3142 | Suffix used for the image output file name - defaults to ``".rootfs"`` | ||
3143 | to distinguish the image file from other files created during image | ||
3144 | building; however if this suffix is redundant or not desired you can | ||
3145 | clear the value of this variable (set the value to ""). For example, | ||
3146 | this is typically cleared in initramfs image recipes. | ||
3147 | |||
3148 | :term:`IMAGE_OVERHEAD_FACTOR` | ||
3149 | Defines a multiplier that the build system applies to the initial | ||
3150 | image size for cases when the multiplier times the returned disk | ||
3151 | usage value for the image is greater than the sum of | ||
3152 | ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of | ||
3153 | the multiplier applied to the initial image size creates free disk | ||
3154 | space in the image as overhead. By default, the build process uses a | ||
3155 | multiplier of 1.3 for this variable. This default value results in | ||
3156 | 30% free disk space added to the image when this method is used to | ||
3157 | determine the final generated image size. You should be aware that | ||
3158 | post install scripts and the package management system uses disk | ||
3159 | space inside this overhead area. Consequently, the multiplier does | ||
3160 | not produce an image with all the theoretical free disk space. See | ||
3161 | ``IMAGE_ROOTFS_SIZE`` for information on how the build system | ||
3162 | determines the overall image size. | ||
3163 | |||
3164 | The default 30% free disk space typically gives the image enough room | ||
3165 | to boot and allows for basic post installs while still leaving a | ||
3166 | small amount of free disk space. If 30% free space is inadequate, you | ||
3167 | can increase the default value. For example, the following setting | ||
3168 | gives you 50% free space added to the image: | ||
3169 | :: | ||
3170 | |||
3171 | IMAGE_OVERHEAD_FACTOR = "1.5" | ||
3172 | |||
3173 | Alternatively, you can ensure a specific amount of free disk space is | ||
3174 | added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` | ||
3175 | variable. | ||
3176 | |||
3177 | :term:`IMAGE_PKGTYPE` | ||
3178 | Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the | ||
3179 | OpenEmbedded build system. The variable is defined appropriately by | ||
3180 | the :ref:`package_deb <ref-classes-package_deb>`, | ||
3181 | :ref:`package_rpm <ref-classes-package_rpm>`, | ||
3182 | :ref:`package_ipk <ref-classes-package_ipk>`, or | ||
3183 | :ref:`package_tar <ref-classes-package_tar>` class. | ||
3184 | |||
3185 | .. note:: | ||
3186 | |||
3187 | The ``package_tar`` class is broken and is not supported. It is | ||
3188 | recommended that you do not use it. | ||
3189 | |||
3190 | The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and | ||
3191 | :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` | ||
3192 | for packaging up images and SDKs. | ||
3193 | |||
3194 | You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the | ||
3195 | variable is set indirectly through the appropriate | ||
3196 | :ref:`package_* <ref-classes-package>` class using the | ||
3197 | :term:`PACKAGE_CLASSES` variable. The | ||
3198 | OpenEmbedded build system uses the first package type (e.g. DEB, RPM, | ||
3199 | or IPK) that appears with the variable | ||
3200 | |||
3201 | .. note:: | ||
3202 | |||
3203 | Files using the ``.tar`` format are never used as a substitute | ||
3204 | packaging format for DEB, RPM, and IPK formatted files for your image | ||
3205 | or SDK. | ||
3206 | |||
3207 | :term:`IMAGE_POSTPROCESS_COMMAND` | ||
3208 | Specifies a list of functions to call once the OpenEmbedded build | ||
3209 | system creates the final image output files. You can specify | ||
3210 | functions separated by semicolons: | ||
3211 | :: | ||
3212 | |||
3213 | IMAGE_POSTPROCESS_COMMAND += "function; ... " | ||
3214 | |||
3215 | If you need to pass the root filesystem path to a command within the | ||
3216 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
3217 | directory that becomes the root filesystem image. See the | ||
3218 | :term:`IMAGE_ROOTFS` variable for more | ||
3219 | information. | ||
3220 | |||
3221 | :term:`IMAGE_PREPROCESS_COMMAND` | ||
3222 | Specifies a list of functions to call before the OpenEmbedded build | ||
3223 | system creates the final image output files. You can specify | ||
3224 | functions separated by semicolons: | ||
3225 | :: | ||
3226 | |||
3227 | IMAGE_PREPROCESS_COMMAND += "function; ... " | ||
3228 | |||
3229 | If you need to pass the root filesystem path to a command within the | ||
3230 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
3231 | directory that becomes the root filesystem image. See the | ||
3232 | :term:`IMAGE_ROOTFS` variable for more | ||
3233 | information. | ||
3234 | |||
3235 | :term:`IMAGE_ROOTFS` | ||
3236 | The location of the root filesystem while it is under construction | ||
3237 | (i.e. during the :ref:`ref-tasks-rootfs` task). This | ||
3238 | variable is not configurable. Do not change it. | ||
3239 | |||
3240 | :term:`IMAGE_ROOTFS_ALIGNMENT` | ||
3241 | Specifies the alignment for the output image file in Kbytes. If the | ||
3242 | size of the image is not a multiple of this value, then the size is | ||
3243 | rounded up to the nearest multiple of the value. The default value is | ||
3244 | "1". See :term:`IMAGE_ROOTFS_SIZE` for | ||
3245 | additional information. | ||
3246 | |||
3247 | :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
3248 | Defines additional free disk space created in the image in Kbytes. By | ||
3249 | default, this variable is set to "0". This free disk space is added | ||
3250 | to the image after the build system determines the image size as | ||
3251 | described in ``IMAGE_ROOTFS_SIZE``. | ||
3252 | |||
3253 | This variable is particularly useful when you want to ensure that a | ||
3254 | specific amount of free disk space is available on a device after an | ||
3255 | image is installed and running. For example, to be sure 5 Gbytes of | ||
3256 | free disk space is available, set the variable as follows: | ||
3257 | :: | ||
3258 | |||
3259 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | ||
3260 | |||
3261 | For example, the Yocto Project Build Appliance specifically requests | ||
3262 | 40 Gbytes of extra space with the line: | ||
3263 | :: | ||
3264 | |||
3265 | IMAGE_ROOTFS_EXTRA_SPACE = "41943040" | ||
3266 | |||
3267 | :term:`IMAGE_ROOTFS_SIZE` | ||
3268 | Defines the size in Kbytes for the generated image. The OpenEmbedded | ||
3269 | build system determines the final size for the generated image using | ||
3270 | an algorithm that takes into account the initial disk space used for | ||
3271 | the generated image, a requested size for the image, and requested | ||
3272 | additional free disk space to be added to the image. Programatically, | ||
3273 | the build system determines the final size of the generated image as | ||
3274 | follows: | ||
3275 | :: | ||
3276 | |||
3277 | if (image-du * overhead) < rootfs-size: | ||
3278 | internal-rootfs-size = rootfs-size + xspace | ||
3279 | else: | ||
3280 | internal-rootfs-size = (image-du * overhead) + xspace | ||
3281 | where: | ||
3282 | image-du = Returned value of the du command on the image. | ||
3283 | overhead = IMAGE_OVERHEAD_FACTOR | ||
3284 | rootfs-size = IMAGE_ROOTFS_SIZE | ||
3285 | internal-rootfs-size = Initial root filesystem size before any modifications. | ||
3286 | xspace = IMAGE_ROOTFS_EXTRA_SPACE | ||
3287 | |||
3288 | See the :term:`IMAGE_OVERHEAD_FACTOR` | ||
3289 | and :term:`IMAGE_ROOTFS_EXTRA_SPACE` | ||
3290 | variables for related information. | ||
3291 | |||
3292 | :term:`IMAGE_TYPEDEP` | ||
3293 | Specifies a dependency from one image type on another. Here is an | ||
3294 | example from the :ref:`image-live <ref-classes-image-live>` class: | ||
3295 | :: | ||
3296 | |||
3297 | IMAGE_TYPEDEP_live = "ext3" | ||
3298 | |||
3299 | In the previous example, the variable ensures that when "live" is | ||
3300 | listed with the :term:`IMAGE_FSTYPES` variable, | ||
3301 | the OpenEmbedded build system produces an ``ext3`` image first since | ||
3302 | one of the components of the live image is an ``ext3`` formatted | ||
3303 | partition containing the root filesystem. | ||
3304 | |||
3305 | :term:`IMAGE_TYPES` | ||
3306 | Specifies the complete list of supported image types by default: | ||
3307 | |||
3308 | - btrfs | ||
3309 | - container | ||
3310 | - cpio | ||
3311 | - cpio.gz | ||
3312 | - cpio.lz4 | ||
3313 | - cpio.lzma | ||
3314 | - cpio.xz | ||
3315 | - cramfs | ||
3316 | - ext2 | ||
3317 | - ext2.bz2 | ||
3318 | - ext2.gz | ||
3319 | - ext2.lzma | ||
3320 | - ext3 | ||
3321 | - ext3.gz | ||
3322 | - ext4 | ||
3323 | - ext4.gz | ||
3324 | - f2fs | ||
3325 | - hddimg | ||
3326 | - iso | ||
3327 | - jffs2 | ||
3328 | - jffs2.sum | ||
3329 | - multiubi | ||
3330 | - squashfs | ||
3331 | - squashfs-lz4 | ||
3332 | - squashfs-lzo | ||
3333 | - squashfs-xz | ||
3334 | - tar | ||
3335 | - tar.bz2 | ||
3336 | - tar.gz | ||
3337 | - tar.lz4 | ||
3338 | - tar.xz | ||
3339 | - tar.zst | ||
3340 | - ubi | ||
3341 | - ubifs | ||
3342 | - wic | ||
3343 | - wic.bz2 | ||
3344 | - wic.gz | ||
3345 | - wic.lzma | ||
3346 | |||
3347 | For more information about these types of images, see | ||
3348 | ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. | ||
3349 | |||
3350 | :term:`IMAGE_VERSION_SUFFIX` | ||
3351 | Version suffix that is part of the default :term:`IMAGE_NAME` and | ||
3352 | :term:`KERNEL_ARTIFACT_NAME` values. | ||
3353 | Defaults to ``"-${DATETIME}"``, however you could set this to a | ||
3354 | version string that comes from your external build environment if | ||
3355 | desired, and this suffix would then be used consistently across | ||
3356 | the build artifacts. | ||
3357 | |||
3358 | :term:`INC_PR` | ||
3359 | Helps define the recipe revision for recipes that share a common | ||
3360 | ``include`` file. You can think of this variable as part of the | ||
3361 | recipe revision as set from within an include file. | ||
3362 | |||
3363 | Suppose, for example, you have a set of recipes that are used across | ||
3364 | several projects. And, within each of those recipes the revision (its | ||
3365 | :term:`PR` value) is set accordingly. In this case, when | ||
3366 | the revision of those recipes changes, the burden is on you to find | ||
3367 | all those recipes and be sure that they get changed to reflect the | ||
3368 | updated version of the recipe. In this scenario, it can get | ||
3369 | complicated when recipes that are used in many places and provide | ||
3370 | common functionality are upgraded to a new revision. | ||
3371 | |||
3372 | A more efficient way of dealing with this situation is to set the | ||
3373 | ``INC_PR`` variable inside the ``include`` files that the recipes | ||
3374 | share and then expand the ``INC_PR`` variable within the recipes to | ||
3375 | help define the recipe revision. | ||
3376 | |||
3377 | The following provides an example that shows how to use the | ||
3378 | ``INC_PR`` variable given a common ``include`` file that defines the | ||
3379 | variable. Once the variable is defined in the ``include`` file, you | ||
3380 | can use the variable to set the ``PR`` values in each recipe. You | ||
3381 | will notice that when you set a recipe's ``PR`` you can provide more | ||
3382 | granular revisioning by appending values to the ``INC_PR`` variable: | ||
3383 | :: | ||
3384 | |||
3385 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | ||
3386 | recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" | ||
3387 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" | ||
3388 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | ||
3389 | |||
3390 | The | ||
3391 | first line of the example establishes the baseline revision to be | ||
3392 | used for all recipes that use the ``include`` file. The remaining | ||
3393 | lines in the example are from individual recipes and show how the | ||
3394 | ``PR`` value is set. | ||
3395 | |||
3396 | :term:`INCOMPATIBLE_LICENSE` | ||
3397 | Specifies a space-separated list of license names (as they would | ||
3398 | appear in :term:`LICENSE`) that should be excluded | ||
3399 | from the build. Recipes that provide no alternatives to listed | ||
3400 | incompatible licenses are not built. Packages that are individually | ||
3401 | licensed with the specified incompatible licenses will be deleted. | ||
3402 | |||
3403 | .. note:: | ||
3404 | |||
3405 | This functionality is only regularly tested using the following | ||
3406 | setting: | ||
3407 | :: | ||
3408 | |||
3409 | INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" | ||
3410 | |||
3411 | |||
3412 | Although you can use other settings, you might be required to | ||
3413 | remove dependencies on or provide alternatives to components that | ||
3414 | are required to produce a functional system image. | ||
3415 | |||
3416 | .. note:: | ||
3417 | |||
3418 | It is possible to define a list of licenses that are allowed to be | ||
3419 | used instead of the licenses that are excluded. To do this, define | ||
3420 | a variable ``COMPATIBLE_LICENSES`` with the names of the licences | ||
3421 | that are allowed. Then define ``INCOMPATIBLE_LICENSE`` as: | ||
3422 | :: | ||
3423 | |||
3424 | INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" | ||
3425 | |||
3426 | |||
3427 | This will result in ``INCOMPATIBLE_LICENSE`` containing the names of | ||
3428 | all licences from :term:`AVAILABLE_LICENSES` except the ones specified | ||
3429 | in ``COMPATIBLE_LICENSES`` , thus only allowing the latter licences to | ||
3430 | be used. | ||
3431 | |||
3432 | :term:`INHERIT` | ||
3433 | Causes the named class or classes to be inherited globally. Anonymous | ||
3434 | functions in the class or classes are not executed for the base | ||
3435 | configuration and in each individual recipe. The OpenEmbedded build | ||
3436 | system ignores changes to ``INHERIT`` in individual recipes. | ||
3437 | |||
3438 | For more information on ``INHERIT``, see the | ||
3439 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | ||
3440 | section in the Bitbake User Manual. | ||
3441 | |||
3442 | :term:`INHERIT_DISTRO` | ||
3443 | Lists classes that will be inherited at the distribution level. It is | ||
3444 | unlikely that you want to edit this variable. | ||
3445 | |||
3446 | The default value of the variable is set as follows in the | ||
3447 | ``meta/conf/distro/defaultsetup.conf`` file: | ||
3448 | :: | ||
3449 | |||
3450 | INHERIT_DISTRO ?= "debian devshell sstate license" | ||
3451 | |||
3452 | :term:`INHIBIT_DEFAULT_DEPS` | ||
3453 | Prevents the default dependencies, namely the C compiler and standard | ||
3454 | C library (libc), from being added to :term:`DEPENDS`. | ||
3455 | This variable is usually used within recipes that do not require any | ||
3456 | compilation using the C compiler. | ||
3457 | |||
3458 | Set the variable to "1" to prevent the default dependencies from | ||
3459 | being added. | ||
3460 | |||
3461 | :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` | ||
3462 | Prevents the OpenEmbedded build system from splitting out debug | ||
3463 | information during packaging. By default, the build system splits out | ||
3464 | debugging information during the | ||
3465 | :ref:`ref-tasks-package` task. For more information on | ||
3466 | how debug information is split out, see the | ||
3467 | :term:`PACKAGE_DEBUG_SPLIT_STYLE` | ||
3468 | variable. | ||
3469 | |||
3470 | To prevent the build system from splitting out debug information | ||
3471 | during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as | ||
3472 | follows: | ||
3473 | :: | ||
3474 | |||
3475 | INHIBIT_PACKAGE_DEBUG_SPLIT = "1" | ||
3476 | |||
3477 | :term:`INHIBIT_PACKAGE_STRIP` | ||
3478 | If set to "1", causes the build to not strip binaries in resulting | ||
3479 | packages and prevents the ``-dbg`` package from containing the source | ||
3480 | files. | ||
3481 | |||
3482 | By default, the OpenEmbedded build system strips binaries and puts | ||
3483 | the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. | ||
3484 | Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you | ||
3485 | plan to debug in general. | ||
3486 | |||
3487 | :term:`INHIBIT_SYSROOT_STRIP` | ||
3488 | If set to "1", causes the build to not strip binaries in the | ||
3489 | resulting sysroot. | ||
3490 | |||
3491 | By default, the OpenEmbedded build system strips binaries in the | ||
3492 | resulting sysroot. When you specifically set the | ||
3493 | ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit | ||
3494 | this stripping. | ||
3495 | |||
3496 | If you want to use this variable, include the | ||
3497 | :ref:`staging <ref-classes-staging>` class. This class uses a | ||
3498 | ``sys_strip()`` function to test for the variable and acts | ||
3499 | accordingly. | ||
3500 | |||
3501 | .. note:: | ||
3502 | |||
3503 | Use of the ``INHIBIT_SYSROOT_STRIP`` variable occurs in rare and | ||
3504 | special circumstances. For example, suppose you are building | ||
3505 | bare-metal firmware by using an external GCC toolchain. Furthermore, | ||
3506 | even if the toolchain's binaries are strippable, other files exist | ||
3507 | that are needed for the build that are not strippable. | ||
3508 | |||
3509 | :term:`INITRAMFS_FSTYPES` | ||
3510 | Defines the format for the output image of an initial RAM filesystem | ||
3511 | (initramfs), which is used during boot. Supported formats are the | ||
3512 | same as those supported by the | ||
3513 | :term:`IMAGE_FSTYPES` variable. | ||
3514 | |||
3515 | The default value of this variable, which is set in the | ||
3516 | ``meta/conf/bitbake.conf`` configuration file in the | ||
3517 | :term:`Source Directory`, is "cpio.gz". The Linux kernel's | ||
3518 | initramfs mechanism, as opposed to the initial RAM filesystem | ||
3519 | `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects | ||
3520 | an optionally compressed cpio archive. | ||
3521 | |||
3522 | :term:`INITRAMFS_IMAGE` | ||
3523 | Specifies the :term:`PROVIDES` name of an image | ||
3524 | recipe that is used to build an initial RAM filesystem (initramfs) | ||
3525 | image. In other words, the ``INITRAMFS_IMAGE`` variable causes an | ||
3526 | additional recipe to be built as a dependency to whatever root | ||
3527 | filesystem recipe you might be using (e.g. ``core-image-sato``). The | ||
3528 | initramfs image recipe you provide should set | ||
3529 | :term:`IMAGE_FSTYPES` to | ||
3530 | :term:`INITRAMFS_FSTYPES`. | ||
3531 | |||
3532 | An initramfs image provides a temporary root filesystem used for | ||
3533 | early system initialization (e.g. loading of modules needed to locate | ||
3534 | and mount the "real" root filesystem). | ||
3535 | |||
3536 | .. note:: | ||
3537 | |||
3538 | See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` | ||
3539 | recipe in the :term:`Source Directory` | ||
3540 | for an example initramfs recipe. To select this sample recipe as | ||
3541 | the one built to provide the initramfs image, set ``INITRAMFS_IMAGE`` | ||
3542 | to "core-image-minimal-initramfs". | ||
3543 | |||
3544 | You can also find more information by referencing the | ||
3545 | ``meta-poky/conf/local.conf.sample.extended`` configuration file in | ||
3546 | the Source Directory, the :ref:`image <ref-classes-image>` class, | ||
3547 | and the :ref:`kernel <ref-classes-kernel>` class to see how to use | ||
3548 | the ``INITRAMFS_IMAGE`` variable. | ||
3549 | |||
3550 | If ``INITRAMFS_IMAGE`` is empty, which is the default, then no | ||
3551 | initramfs image is built. | ||
3552 | |||
3553 | For more information, you can also see the | ||
3554 | :term:`INITRAMFS_IMAGE_BUNDLE` | ||
3555 | variable, which allows the generated image to be bundled inside the | ||
3556 | kernel image. Additionally, for information on creating an initramfs | ||
3557 | image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | ||
3558 | in the Yocto Project Development Tasks Manual. | ||
3559 | |||
3560 | :term:`INITRAMFS_IMAGE_BUNDLE` | ||
3561 | Controls whether or not the image recipe specified by | ||
3562 | :term:`INITRAMFS_IMAGE` is run through an | ||
3563 | extra pass | ||
3564 | (:ref:`ref-tasks-bundle_initramfs`) during | ||
3565 | kernel compilation in order to build a single binary that contains | ||
3566 | both the kernel image and the initial RAM filesystem (initramfs) | ||
3567 | image. This makes use of the | ||
3568 | :term:`CONFIG_INITRAMFS_SOURCE` kernel | ||
3569 | feature. | ||
3570 | |||
3571 | .. note:: | ||
3572 | |||
3573 | Using an extra compilation pass to bundle the initramfs avoids a | ||
3574 | circular dependency between the kernel recipe and the initramfs | ||
3575 | recipe should the initramfs include kernel modules. Should that be | ||
3576 | the case, the initramfs recipe depends on the kernel for the | ||
3577 | kernel modules, and the kernel depends on the initramfs recipe | ||
3578 | since the initramfs is bundled inside the kernel image. | ||
3579 | |||
3580 | The combined binary is deposited into the ``tmp/deploy`` directory, | ||
3581 | which is part of the :term:`Build Directory`. | ||
3582 | |||
3583 | Setting the variable to "1" in a configuration file causes the | ||
3584 | OpenEmbedded build system to generate a kernel image with the | ||
3585 | initramfs specified in ``INITRAMFS_IMAGE`` bundled within: | ||
3586 | :: | ||
3587 | |||
3588 | INITRAMFS_IMAGE_BUNDLE = "1" | ||
3589 | |||
3590 | By default, the | ||
3591 | :ref:`kernel <ref-classes-kernel>` class sets this variable to a | ||
3592 | null string as follows: | ||
3593 | :: | ||
3594 | |||
3595 | INITRAMFS_IMAGE_BUNDLE ?= "" | ||
3596 | |||
3597 | .. note:: | ||
3598 | |||
3599 | You must set the ``INITRAMFS_IMAGE_BUNDLE`` variable in a | ||
3600 | configuration file. You cannot set the variable in a recipe file. | ||
3601 | |||
3602 | See the | ||
3603 | :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>` | ||
3604 | file for additional information. Also, for information on creating an | ||
3605 | initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | ||
3606 | in the Yocto Project Development Tasks Manual. | ||
3607 | |||
3608 | :term:`INITRAMFS_LINK_NAME` | ||
3609 | The link name of the initial RAM filesystem image. This variable is | ||
3610 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3611 | follows: | ||
3612 | :: | ||
3613 | |||
3614 | INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" | ||
3615 | |||
3616 | The value of the | ||
3617 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3618 | file, has the following value: | ||
3619 | :: | ||
3620 | |||
3621 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3622 | |||
3623 | See the :term:`MACHINE` variable for additional | ||
3624 | information. | ||
3625 | |||
3626 | :term:`INITRAMFS_NAME` | ||
3627 | The base name of the initial RAM filesystem image. This variable is | ||
3628 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3629 | follows: | ||
3630 | :: | ||
3631 | |||
3632 | INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" | ||
3633 | |||
3634 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3635 | variable, which is set in the same file, has the following value: | ||
3636 | :: | ||
3637 | |||
3638 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3639 | |||
3640 | :term:`INITRD` | ||
3641 | Indicates list of filesystem images to concatenate and use as an | ||
3642 | initial RAM disk (``initrd``). | ||
3643 | |||
3644 | The ``INITRD`` variable is an optional variable used with the | ||
3645 | :ref:`image-live <ref-classes-image-live>` class. | ||
3646 | |||
3647 | :term:`INITRD_IMAGE` | ||
3648 | When building a "live" bootable image (i.e. when | ||
3649 | :term:`IMAGE_FSTYPES` contains "live"), | ||
3650 | ``INITRD_IMAGE`` specifies the image recipe that should be built to | ||
3651 | provide the initial RAM disk image. The default value is | ||
3652 | "core-image-minimal-initramfs". | ||
3653 | |||
3654 | See the :ref:`image-live <ref-classes-image-live>` class for more | ||
3655 | information. | ||
3656 | |||
3657 | :term:`INITSCRIPT_NAME` | ||
3658 | The filename of the initialization script as installed to | ||
3659 | ``${sysconfdir}/init.d``. | ||
3660 | |||
3661 | This variable is used in recipes when using ``update-rc.d.bbclass``. | ||
3662 | The variable is mandatory. | ||
3663 | |||
3664 | :term:`INITSCRIPT_PACKAGES` | ||
3665 | A list of the packages that contain initscripts. If multiple packages | ||
3666 | are specified, you need to append the package name to the other | ||
3667 | ``INITSCRIPT_*`` as an override. | ||
3668 | |||
3669 | This variable is used in recipes when using ``update-rc.d.bbclass``. | ||
3670 | The variable is optional and defaults to the :term:`PN` | ||
3671 | variable. | ||
3672 | |||
3673 | :term:`INITSCRIPT_PARAMS` | ||
3674 | Specifies the options to pass to ``update-rc.d``. Here is an example: | ||
3675 | :: | ||
3676 | |||
3677 | INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." | ||
3678 | |||
3679 | In this example, the script has a runlevel of 99, starts the script | ||
3680 | in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. | ||
3681 | |||
3682 | The variable's default value is "defaults", which is set in the | ||
3683 | :ref:`update-rc.d <ref-classes-update-rc.d>` class. | ||
3684 | |||
3685 | The value in ``INITSCRIPT_PARAMS`` is passed through to the | ||
3686 | ``update-rc.d`` command. For more information on valid parameters, | ||
3687 | please see the ``update-rc.d`` manual page at | ||
3688 | https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html | ||
3689 | |||
3690 | :term:`INSANE_SKIP` | ||
3691 | Specifies the QA checks to skip for a specific package within a | ||
3692 | recipe. For example, to skip the check for symbolic link ``.so`` | ||
3693 | files in the main package of a recipe, add the following to the | ||
3694 | recipe. The package name override must be used, which in this example | ||
3695 | is ``${PN}``: | ||
3696 | :: | ||
3697 | |||
3698 | INSANE_SKIP_${PN} += "dev-so" | ||
3699 | |||
3700 | See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a | ||
3701 | list of the valid QA checks you can specify using this variable. | ||
3702 | |||
3703 | :term:`INSTALL_TIMEZONE_FILE` | ||
3704 | By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. | ||
3705 | Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the | ||
3706 | configuration level to disable this behavior. | ||
3707 | |||
3708 | :term:`IPK_FEED_URIS` | ||
3709 | When the IPK backend is in use and package management is enabled on | ||
3710 | the target, you can use this variable to set up ``opkg`` in the | ||
3711 | target image to point to package feeds on a nominated server. Once | ||
3712 | the feed is established, you can perform installations or upgrades | ||
3713 | using the package manager at runtime. | ||
3714 | |||
3715 | :term:`KARCH` | ||
3716 | Defines the kernel architecture used when assembling the | ||
3717 | configuration. Architectures supported for this release are: | ||
3718 | |||
3719 | - powerpc | ||
3720 | - i386 | ||
3721 | - x86_64 | ||
3722 | - arm | ||
3723 | - qemu | ||
3724 | - mips | ||
3725 | |||
3726 | You define the ``KARCH`` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. | ||
3727 | |||
3728 | :term:`KBRANCH` | ||
3729 | A regular expression used by the build process to explicitly identify | ||
3730 | the kernel branch that is validated, patched, and configured during a | ||
3731 | build. You must set this variable to ensure the exact kernel branch | ||
3732 | you want is being used by the build process. | ||
3733 | |||
3734 | Values for this variable are set in the kernel's recipe file and the | ||
3735 | kernel's append file. For example, if you are using the | ||
3736 | ``linux-yocto_4.12`` kernel, the kernel recipe file is the | ||
3737 | ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` | ||
3738 | is set as follows in that kernel recipe file: | ||
3739 | :: | ||
3740 | |||
3741 | KBRANCH ?= "standard/base" | ||
3742 | |||
3743 | This variable is also used from the kernel's append file to identify | ||
3744 | the kernel branch specific to a particular machine or target | ||
3745 | hardware. Continuing with the previous kernel example, the kernel's | ||
3746 | append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the | ||
3747 | BSP layer for a given machine. For example, the append file for the | ||
3748 | Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA | ||
3749 | machines (``meta-yocto-bsp``) is named | ||
3750 | ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. | ||
3751 | Here are the related statements from that append file: | ||
3752 | :: | ||
3753 | |||
3754 | KBRANCH_genericx86 = "standard/base" | ||
3755 | KBRANCH_genericx86-64 = "standard/base" | ||
3756 | KBRANCH_edgerouter = "standard/edgerouter" | ||
3757 | KBRANCH_beaglebone = "standard/beaglebone" | ||
3758 | |||
3759 | The ``KBRANCH`` statements | ||
3760 | identify the kernel branch to use when building for each supported | ||
3761 | BSP. | ||
3762 | |||
3763 | :term:`KBUILD_DEFCONFIG` | ||
3764 | When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` | ||
3765 | class, specifies an "in-tree" kernel configuration file for use | ||
3766 | during a kernel build. | ||
3767 | |||
3768 | Typically, when using a ``defconfig`` to configure a kernel during a | ||
3769 | build, you place the file in your layer in the same manner as you | ||
3770 | would place patch files and configuration fragment files (i.e. | ||
3771 | "out-of-tree"). However, if you want to use a ``defconfig`` file that | ||
3772 | is part of the kernel tree (i.e. "in-tree"), you can use the | ||
3773 | ``KBUILD_DEFCONFIG`` variable and append the | ||
3774 | :term:`KMACHINE` variable to point to the | ||
3775 | ``defconfig`` file. | ||
3776 | |||
3777 | To use the variable, set it in the append file for your kernel recipe | ||
3778 | using the following form: | ||
3779 | :: | ||
3780 | |||
3781 | KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file | ||
3782 | |||
3783 | Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses | ||
3784 | a ``defconfig`` file named "bcm2709_defconfig": | ||
3785 | :: | ||
3786 | |||
3787 | KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" | ||
3788 | |||
3789 | As an alternative, you can use the following within your append file: | ||
3790 | :: | ||
3791 | |||
3792 | KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file | ||
3793 | |||
3794 | For more | ||
3795 | information on how to use the ``KBUILD_DEFCONFIG`` variable, see the | ||
3796 | ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" | ||
3797 | section in the Yocto Project Linux Kernel Development Manual. | ||
3798 | |||
3799 | :term:`KERNEL_ALT_IMAGETYPE` | ||
3800 | Specifies an alternate kernel image type for creation in addition to | ||
3801 | the kernel image type specified using the | ||
3802 | :term:`KERNEL_IMAGETYPE` variable. | ||
3803 | |||
3804 | :term:`KERNEL_ARTIFACT_NAME` | ||
3805 | Specifies the name of all of the build artifacts. You can change the | ||
3806 | name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` | ||
3807 | variable. | ||
3808 | |||
3809 | The value of ``KERNEL_ARTIFACT_NAME``, which is set in the | ||
3810 | ``meta/classes/kernel-artifact-names.bbclass`` file, has the | ||
3811 | following default value: | ||
3812 | :: | ||
3813 | |||
3814 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3815 | |||
3816 | See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`MACHINE` | ||
3817 | and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. | ||
3818 | |||
3819 | :term:`KERNEL_CLASSES` | ||
3820 | A list of classes defining kernel image types that the | ||
3821 | :ref:`kernel <ref-classes-kernel>` class should inherit. You | ||
3822 | typically append this variable to enable extended image types. An | ||
3823 | example is the "kernel-fitimage", which enables fitImage support and | ||
3824 | resides in ``meta/classes/kernel-fitimage.bbclass``. You can register | ||
3825 | custom kernel image types with the ``kernel`` class using this | ||
3826 | variable. | ||
3827 | |||
3828 | :term:`KERNEL_DEVICETREE` | ||
3829 | Specifies the name of the generated Linux kernel device tree (i.e. | ||
3830 | the ``.dtb``) file. | ||
3831 | |||
3832 | .. note:: | ||
3833 | |||
3834 | Legacy support exists for specifying the full path to the device | ||
3835 | tree. However, providing just the ``.dtb`` file is preferred. | ||
3836 | |||
3837 | In order to use this variable, the | ||
3838 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must | ||
3839 | be inherited. | ||
3840 | |||
3841 | :term:`KERNEL_DTB_LINK_NAME` | ||
3842 | The link name of the kernel device tree binary (DTB). This variable | ||
3843 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3844 | follows: | ||
3845 | :: | ||
3846 | |||
3847 | KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3848 | |||
3849 | The | ||
3850 | value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in | ||
3851 | the same file, has the following value: | ||
3852 | :: | ||
3853 | |||
3854 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3855 | |||
3856 | See the :term:`MACHINE` variable for additional | ||
3857 | information. | ||
3858 | |||
3859 | :term:`KERNEL_DTB_NAME` | ||
3860 | The base name of the kernel device tree binary (DTB). This variable | ||
3861 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | ||
3862 | follows: | ||
3863 | :: | ||
3864 | |||
3865 | KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3866 | |||
3867 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3868 | variable, which is set in the same file, has the following value: | ||
3869 | :: | ||
3870 | |||
3871 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3872 | |||
3873 | :term:`KERNEL_EXTRA_ARGS` | ||
3874 | Specifies additional ``make`` command-line arguments the OpenEmbedded | ||
3875 | build system passes on when compiling the kernel. | ||
3876 | |||
3877 | :term:`KERNEL_FEATURES` | ||
3878 | Includes additional kernel metadata. In the OpenEmbedded build | ||
3879 | system, the default Board Support Packages (BSPs) | ||
3880 | :term:`Metadata` is provided through the | ||
3881 | :term:`KMACHINE` and :term:`KBRANCH` | ||
3882 | variables. You can use the ``KERNEL_FEATURES`` variable from within | ||
3883 | the kernel recipe or kernel append file to further add metadata for | ||
3884 | all BSPs or specific BSPs. | ||
3885 | |||
3886 | The metadata you add through this variable includes config fragments | ||
3887 | and features descriptions, which usually includes patches as well as | ||
3888 | config fragments. You typically override the ``KERNEL_FEATURES`` | ||
3889 | variable for a specific machine. In this way, you can provide | ||
3890 | validated, but optional, sets of kernel configurations and features. | ||
3891 | |||
3892 | For example, the following example from the ``linux-yocto-rt_4.12`` | ||
3893 | kernel recipe adds "netfilter" and "taskstats" features to all BSPs | ||
3894 | as well as "virtio" configurations to all QEMU machines. The last two | ||
3895 | statements add specific configurations to targeted machine types: | ||
3896 | :: | ||
3897 | |||
3898 | KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" | ||
3899 | KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" | ||
3900 | KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc" | ||
3901 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" | ||
3902 | KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc" | ||
3903 | |||
3904 | :term:`KERNEL_FIT_LINK_NAME` | ||
3905 | The link name of the kernel flattened image tree (FIT) image. This | ||
3906 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | ||
3907 | file as follows: | ||
3908 | :: | ||
3909 | |||
3910 | KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3911 | |||
3912 | The value of the | ||
3913 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3914 | file, has the following value: | ||
3915 | :: | ||
3916 | |||
3917 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3918 | |||
3919 | See the :term:`MACHINE` variable for additional | ||
3920 | information. | ||
3921 | |||
3922 | :term:`KERNEL_FIT_NAME` | ||
3923 | The base name of the kernel flattened image tree (FIT) image. This | ||
3924 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | ||
3925 | file as follows: | ||
3926 | :: | ||
3927 | |||
3928 | KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3929 | |||
3930 | The value of the :term:`KERNEL_ARTIFACT_NAME` | ||
3931 | variable, which is set in the same file, has the following value: | ||
3932 | :: | ||
3933 | |||
3934 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3935 | |||
3936 | :term:`KERNEL_IMAGE_LINK_NAME` | ||
3937 | The link name for the kernel image. This variable is set in the | ||
3938 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
3939 | :: | ||
3940 | |||
3941 | KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
3942 | |||
3943 | The value of | ||
3944 | the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | ||
3945 | file, has the following value: | ||
3946 | :: | ||
3947 | |||
3948 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
3949 | |||
3950 | See the :term:`MACHINE` variable for additional | ||
3951 | information. | ||
3952 | |||
3953 | :term:`KERNEL_IMAGE_MAXSIZE` | ||
3954 | Specifies the maximum size of the kernel image file in kilobytes. If | ||
3955 | ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is | ||
3956 | checked against the set value during the | ||
3957 | :ref:`ref-tasks-sizecheck` task. The task fails if | ||
3958 | the kernel image file is larger than the setting. | ||
3959 | |||
3960 | ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a | ||
3961 | limited amount of space in which the kernel image must be stored. | ||
3962 | |||
3963 | By default, this variable is not set, which means the size of the | ||
3964 | kernel image is not checked. | ||
3965 | |||
3966 | :term:`KERNEL_IMAGE_NAME` | ||
3967 | The base name of the kernel image. This variable is set in the | ||
3968 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
3969 | :: | ||
3970 | |||
3971 | KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
3972 | |||
3973 | The value of the | ||
3974 | :term:`KERNEL_ARTIFACT_NAME` variable, | ||
3975 | which is set in the same file, has the following value: | ||
3976 | :: | ||
3977 | |||
3978 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3979 | |||
3980 | :term:`KERNEL_IMAGETYPE` | ||
3981 | The type of kernel to build for a device, usually set by the machine | ||
3982 | configuration files and defaults to "zImage". This variable is used | ||
3983 | when building the kernel and is passed to ``make`` as the target to | ||
3984 | build. | ||
3985 | |||
3986 | If you want to build an alternate kernel image type, use the | ||
3987 | :term:`KERNEL_ALT_IMAGETYPE` variable. | ||
3988 | |||
3989 | :term:`KERNEL_MODULE_AUTOLOAD` | ||
3990 | Lists kernel modules that need to be auto-loaded during boot. | ||
3991 | |||
3992 | .. note:: | ||
3993 | |||
3994 | This variable replaces the deprecated :term:`module_autoload` | ||
3995 | variable. | ||
3996 | |||
3997 | You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it | ||
3998 | can be recognized by the kernel recipe or by an out-of-tree kernel | ||
3999 | module recipe (e.g. a machine configuration file, a distribution | ||
4000 | configuration file, an append file for the recipe, or the recipe | ||
4001 | itself). | ||
4002 | |||
4003 | Specify it as follows: | ||
4004 | :: | ||
4005 | |||
4006 | KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" | ||
4007 | |||
4008 | Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build | ||
4009 | system to populate the ``/etc/modules-load.d/modname.conf`` file with | ||
4010 | the list of modules to be auto-loaded on boot. The modules appear | ||
4011 | one-per-line in the file. Here is an example of the most common use | ||
4012 | case: | ||
4013 | :: | ||
4014 | |||
4015 | KERNEL_MODULE_AUTOLOAD += "module_name" | ||
4016 | |||
4017 | For information on how to populate the ``modname.conf`` file with | ||
4018 | ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable. | ||
4019 | |||
4020 | :term:`KERNEL_MODULE_PROBECONF` | ||
4021 | Provides a list of modules for which the OpenEmbedded build system | ||
4022 | expects to find ``module_conf_``\ modname values that specify | ||
4023 | configuration for each of the modules. For information on how to | ||
4024 | provide those module configurations, see the | ||
4025 | :term:`module_conf_* <module_conf>` variable. | ||
4026 | |||
4027 | :term:`KERNEL_PATH` | ||
4028 | The location of the kernel sources. This variable is set to the value | ||
4029 | of the :term:`STAGING_KERNEL_DIR` within | ||
4030 | the :ref:`module <ref-classes-module>` class. For information on | ||
4031 | how this variable is used, see the | ||
4032 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" | ||
4033 | section in the Yocto Project Linux Kernel Development Manual. | ||
4034 | |||
4035 | To help maximize compatibility with out-of-tree drivers used to build | ||
4036 | modules, the OpenEmbedded build system also recognizes and uses the | ||
4037 | :term:`KERNEL_SRC` variable, which is identical to | ||
4038 | the ``KERNEL_PATH`` variable. Both variables are common variables | ||
4039 | used by external Makefiles to point to the kernel source directory. | ||
4040 | |||
4041 | :term:`KERNEL_SRC` | ||
4042 | The location of the kernel sources. This variable is set to the value | ||
4043 | of the :term:`STAGING_KERNEL_DIR` within | ||
4044 | the :ref:`module <ref-classes-module>` class. For information on | ||
4045 | how this variable is used, see the | ||
4046 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" | ||
4047 | section in the Yocto Project Linux Kernel Development Manual. | ||
4048 | |||
4049 | To help maximize compatibility with out-of-tree drivers used to build | ||
4050 | modules, the OpenEmbedded build system also recognizes and uses the | ||
4051 | :term:`KERNEL_PATH` variable, which is identical | ||
4052 | to the ``KERNEL_SRC`` variable. Both variables are common variables | ||
4053 | used by external Makefiles to point to the kernel source directory. | ||
4054 | |||
4055 | :term:`KERNEL_VERSION` | ||
4056 | Specifies the version of the kernel as extracted from ``version.h`` | ||
4057 | or ``utsrelease.h`` within the kernel sources. Effects of setting | ||
4058 | this variable do not take affect until the kernel has been | ||
4059 | configured. Consequently, attempting to refer to this variable in | ||
4060 | contexts prior to configuration will not work. | ||
4061 | |||
4062 | :term:`KERNELDEPMODDEPEND` | ||
4063 | Specifies whether the data referenced through | ||
4064 | :term:`PKGDATA_DIR` is needed or not. The | ||
4065 | ``KERNELDEPMODDEPEND`` does not control whether or not that data | ||
4066 | exists, but simply whether or not it is used. If you do not need to | ||
4067 | use the data, set the ``KERNELDEPMODDEPEND`` variable in your | ||
4068 | ``initramfs`` recipe. Setting the variable there when the data is not | ||
4069 | needed avoids a potential dependency loop. | ||
4070 | |||
4071 | :term:`KFEATURE_DESCRIPTION` | ||
4072 | Provides a short description of a configuration fragment. You use | ||
4073 | this variable in the ``.scc`` file that describes a configuration | ||
4074 | fragment file. Here is the variable used in a file named ``smp.scc`` | ||
4075 | to describe SMP being enabled: | ||
4076 | :: | ||
4077 | |||
4078 | define KFEATURE_DESCRIPTION "Enable SMP" | ||
4079 | |||
4080 | :term:`KMACHINE` | ||
4081 | The machine as known by the kernel. Sometimes the machine name used | ||
4082 | by the kernel does not match the machine name used by the | ||
4083 | OpenEmbedded build system. For example, the machine name that the | ||
4084 | OpenEmbedded build system understands as ``core2-32-intel-common`` | ||
4085 | goes by a different name in the Linux Yocto kernel. The kernel | ||
4086 | understands that machine as ``intel-core2-32``. For cases like these, | ||
4087 | the ``KMACHINE`` variable maps the kernel machine name to the | ||
4088 | OpenEmbedded build system machine name. | ||
4089 | |||
4090 | These mappings between different names occur in the Yocto Linux | ||
4091 | Kernel's ``meta`` branch. As an example take a look in the | ||
4092 | ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: | ||
4093 | :: | ||
4094 | |||
4095 | LINUX_VERSION_core2-32-intel-common = "3.19.0" | ||
4096 | COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" | ||
4097 | SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" | ||
4098 | SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" | ||
4099 | KMACHINE_core2-32-intel-common = "intel-core2-32" | ||
4100 | KBRANCH_core2-32-intel-common = "standard/base" | ||
4101 | KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" | ||
4102 | |||
4103 | The ``KMACHINE`` statement says | ||
4104 | that the kernel understands the machine name as "intel-core2-32". | ||
4105 | However, the OpenEmbedded build system understands the machine as | ||
4106 | "core2-32-intel-common". | ||
4107 | |||
4108 | :term:`KTYPE` | ||
4109 | Defines the kernel type to be used in assembling the configuration. | ||
4110 | The linux-yocto recipes define "standard", "tiny", and "preempt-rt" | ||
4111 | kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" | ||
4112 | section in the | ||
4113 | Yocto Project Linux Kernel Development Manual for more information on | ||
4114 | kernel types. | ||
4115 | |||
4116 | You define the ``KTYPE`` variable in the | ||
4117 | :ref:`kernel-dev/advanced:bsp descriptions`. The | ||
4118 | value you use must match the value used for the | ||
4119 | :term:`LINUX_KERNEL_TYPE` value used by the | ||
4120 | kernel recipe. | ||
4121 | |||
4122 | :term:`LABELS` | ||
4123 | Provides a list of targets for automatic configuration. | ||
4124 | |||
4125 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | ||
4126 | information on how this variable is used. | ||
4127 | |||
4128 | :term:`LAYERDEPENDS` | ||
4129 | Lists the layers, separated by spaces, on which this recipe depends. | ||
4130 | Optionally, you can specify a specific layer version for a dependency | ||
4131 | by adding it to the end of the layer name. Here is an example: | ||
4132 | :: | ||
4133 | |||
4134 | LAYERDEPENDS_mylayer = "anotherlayer (=3)" | ||
4135 | |||
4136 | In this previous example, | ||
4137 | version 3 of "anotherlayer" is compared against | ||
4138 | :term:`LAYERVERSION`\ ``_anotherlayer``. | ||
4139 | |||
4140 | An error is produced if any dependency is missing or the version | ||
4141 | numbers (if specified) do not match exactly. This variable is used in | ||
4142 | the ``conf/layer.conf`` file and must be suffixed with the name of | ||
4143 | the specific layer (e.g. ``LAYERDEPENDS_mylayer``). | ||
4144 | |||
4145 | :term:`LAYERDIR` | ||
4146 | When used inside the ``layer.conf`` configuration file, this variable | ||
4147 | provides the path of the current layer. This variable is not | ||
4148 | available outside of ``layer.conf`` and references are expanded | ||
4149 | immediately when parsing of the file completes. | ||
4150 | |||
4151 | :term:`LAYERRECOMMENDS` | ||
4152 | Lists the layers, separated by spaces, recommended for use with this | ||
4153 | layer. | ||
4154 | |||
4155 | Optionally, you can specify a specific layer version for a | ||
4156 | recommendation by adding the version to the end of the layer name. | ||
4157 | Here is an example: | ||
4158 | :: | ||
4159 | |||
4160 | LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" | ||
4161 | |||
4162 | In this previous example, version 3 of "anotherlayer" is compared | ||
4163 | against ``LAYERVERSION_anotherlayer``. | ||
4164 | |||
4165 | This variable is used in the ``conf/layer.conf`` file and must be | ||
4166 | suffixed with the name of the specific layer (e.g. | ||
4167 | ``LAYERRECOMMENDS_mylayer``). | ||
4168 | |||
4169 | :term:`LAYERSERIES_COMPAT` | ||
4170 | Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which | ||
4171 | a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable | ||
4172 | allows the layer maintainer to indicate which combinations of the | ||
4173 | layer and OE-Core can be expected to work. The variable gives the | ||
4174 | system a way to detect when a layer has not been tested with new | ||
4175 | releases of OE-Core (e.g. the layer is not maintained). | ||
4176 | |||
4177 | To specify the OE-Core versions for which a layer is compatible, use | ||
4178 | this variable in your layer's ``conf/layer.conf`` configuration file. | ||
4179 | For the list, use the Yocto Project | ||
4180 | :yocto_wiki:`Release Name </Releases>` (e.g. | ||
4181 | DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the | ||
4182 | layer, use a space-separated list: | ||
4183 | :: | ||
4184 | |||
4185 | LAYERSERIES_COMPAT_layer_root_name = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE" | ||
4186 | |||
4187 | .. note:: | ||
4188 | |||
4189 | Setting ``LAYERSERIES_COMPAT`` is required by the Yocto Project | ||
4190 | Compatible version 2 standard. | ||
4191 | The OpenEmbedded build system produces a warning if the variable | ||
4192 | is not set for any given layer. | ||
4193 | |||
4194 | See the ":ref:`dev-manual/common-tasks:creating your own layer`" | ||
4195 | section in the Yocto Project Development Tasks Manual. | ||
4196 | |||
4197 | :term:`LAYERVERSION` | ||
4198 | Optionally specifies the version of a layer as a single number. You | ||
4199 | can use this within :term:`LAYERDEPENDS` for | ||
4200 | another layer in order to depend on a specific version of the layer. | ||
4201 | This variable is used in the ``conf/layer.conf`` file and must be | ||
4202 | suffixed with the name of the specific layer (e.g. | ||
4203 | ``LAYERVERSION_mylayer``). | ||
4204 | |||
4205 | :term:`LD` | ||
4206 | The minimal command and arguments used to run the linker. | ||
4207 | |||
4208 | :term:`LDFLAGS` | ||
4209 | Specifies the flags to pass to the linker. This variable is exported | ||
4210 | to an environment variable and thus made visible to the software | ||
4211 | being built during the compilation step. | ||
4212 | |||
4213 | Default initialization for ``LDFLAGS`` varies depending on what is | ||
4214 | being built: | ||
4215 | |||
4216 | - :term:`TARGET_LDFLAGS` when building for the | ||
4217 | target | ||
4218 | |||
4219 | - :term:`BUILD_LDFLAGS` when building for the | ||
4220 | build host (i.e. ``-native``) | ||
4221 | |||
4222 | - :term:`BUILDSDK_LDFLAGS` when building for | ||
4223 | an SDK (i.e. ``nativesdk-``) | ||
4224 | |||
4225 | :term:`LEAD_SONAME` | ||
4226 | Specifies the lead (or primary) compiled library file (i.e. ``.so``) | ||
4227 | that the :ref:`debian <ref-classes-debian>` class applies its | ||
4228 | naming policy to given a recipe that packages multiple libraries. | ||
4229 | |||
4230 | This variable works in conjunction with the ``debian`` class. | ||
4231 | |||
4232 | :term:`LIC_FILES_CHKSUM` | ||
4233 | Checksums of the license text in the recipe source code. | ||
4234 | |||
4235 | This variable tracks changes in license text of the source code | ||
4236 | files. If the license text is changed, it will trigger a build | ||
4237 | failure, which gives the developer an opportunity to review any | ||
4238 | license change. | ||
4239 | |||
4240 | This variable must be defined for all recipes (unless | ||
4241 | :term:`LICENSE` is set to "CLOSED"). | ||
4242 | |||
4243 | For more information, see the ":ref:`dev-manual/common-tasks:tracking license changes`" | ||
4244 | section in the Yocto Project Development Tasks Manual. | ||
4245 | |||
4246 | :term:`LICENSE` | ||
4247 | The list of source licenses for the recipe. Follow these rules: | ||
4248 | |||
4249 | - Do not use spaces within individual license names. | ||
4250 | |||
4251 | - Separate license names using \| (pipe) when there is a choice | ||
4252 | between licenses. | ||
4253 | |||
4254 | - Separate license names using & (ampersand) when multiple licenses | ||
4255 | exist that cover different parts of the source. | ||
4256 | |||
4257 | - You can use spaces between license names. | ||
4258 | |||
4259 | - For standard licenses, use the names of the files in | ||
4260 | ``meta/files/common-licenses/`` or the | ||
4261 | :term:`SPDXLICENSEMAP` flag names defined in | ||
4262 | ``meta/conf/licenses.conf``. | ||
4263 | |||
4264 | Here are some examples: | ||
4265 | :: | ||
4266 | |||
4267 | LICENSE = "LGPLv2.1 | GPLv3" | ||
4268 | LICENSE = "MPL-1 & LGPLv2.1" | ||
4269 | LICENSE = "GPLv2+" | ||
4270 | |||
4271 | The first example is from the | ||
4272 | recipes for Qt, which the user may choose to distribute under either | ||
4273 | the LGPL version 2.1 or GPL version 3. The second example is from | ||
4274 | Cairo where two licenses cover different parts of the source code. | ||
4275 | The final example is from ``sysstat``, which presents a single | ||
4276 | license. | ||
4277 | |||
4278 | You can also specify licenses on a per-package basis to handle | ||
4279 | situations where components of the output have different licenses. | ||
4280 | For example, a piece of software whose code is licensed under GPLv2 | ||
4281 | but has accompanying documentation licensed under the GNU Free | ||
4282 | Documentation License 1.2 could be specified as follows: | ||
4283 | :: | ||
4284 | |||
4285 | LICENSE = "GFDL-1.2 & GPLv2" | ||
4286 | LICENSE_${PN} = "GPLv2" | ||
4287 | LICENSE_${PN}-doc = "GFDL-1.2" | ||
4288 | |||
4289 | :term:`LICENSE_CREATE_PACKAGE` | ||
4290 | Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded | ||
4291 | build system to create an extra package (i.e. | ||
4292 | ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add | ||
4293 | those packages to the | ||
4294 | :term:`RRECOMMENDS`\ ``_${PN}``. | ||
4295 | |||
4296 | The ``${PN}-lic`` package installs a directory in | ||
4297 | ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base | ||
4298 | name, and installs files in that directory that contain license and | ||
4299 | copyright information (i.e. copies of the appropriate license files | ||
4300 | from ``meta/common-licenses`` that match the licenses specified in | ||
4301 | the :term:`LICENSE` variable of the recipe metadata | ||
4302 | and copies of files marked in | ||
4303 | :term:`LIC_FILES_CHKSUM` as containing | ||
4304 | license text). | ||
4305 | |||
4306 | For related information on providing license text, see the | ||
4307 | :term:`COPY_LIC_DIRS` variable, the | ||
4308 | :term:`COPY_LIC_MANIFEST` variable, and the | ||
4309 | ":ref:`dev-manual/common-tasks:providing license text`" | ||
4310 | section in the Yocto Project Development Tasks Manual. | ||
4311 | |||
4312 | :term:`LICENSE_FLAGS` | ||
4313 | Specifies additional flags for a recipe you must whitelist through | ||
4314 | :term:`LICENSE_FLAGS_WHITELIST` in | ||
4315 | order to allow the recipe to be built. When providing multiple flags, | ||
4316 | separate them with spaces. | ||
4317 | |||
4318 | This value is independent of :term:`LICENSE` and is | ||
4319 | typically used to mark recipes that might require additional licenses | ||
4320 | in order to be used in a commercial product. For more information, | ||
4321 | see the | ||
4322 | ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" | ||
4323 | section in the Yocto Project Development Tasks Manual. | ||
4324 | |||
4325 | :term:`LICENSE_FLAGS_WHITELIST` | ||
4326 | Lists license flags that when specified in | ||
4327 | :term:`LICENSE_FLAGS` within a recipe should not | ||
4328 | prevent that recipe from being built. This practice is otherwise | ||
4329 | known as "whitelisting" license flags. For more information, see the | ||
4330 | ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" | ||
4331 | section in the Yocto Project Development Tasks Manual. | ||
4332 | |||
4333 | :term:`LICENSE_PATH` | ||
4334 | Path to additional licenses used during the build. By default, the | ||
4335 | OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the | ||
4336 | directory that holds common license text used during the build. The | ||
4337 | ``LICENSE_PATH`` variable allows you to extend that location to other | ||
4338 | areas that have additional licenses: | ||
4339 | :: | ||
4340 | |||
4341 | LICENSE_PATH += "path-to-additional-common-licenses" | ||
4342 | |||
4343 | :term:`LINUX_KERNEL_TYPE` | ||
4344 | Defines the kernel type to be used in assembling the configuration. | ||
4345 | The linux-yocto recipes define "standard", "tiny", and "preempt-rt" | ||
4346 | kernel types. See the ":ref:`kernel-dev/advanced:kernel types`" | ||
4347 | section in the | ||
4348 | Yocto Project Linux Kernel Development Manual for more information on | ||
4349 | kernel types. | ||
4350 | |||
4351 | If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to | ||
4352 | "standard". Together with :term:`KMACHINE`, the | ||
4353 | ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by | ||
4354 | the kernel tools to find the appropriate description within the | ||
4355 | kernel :term:`Metadata` with which to build out the sources | ||
4356 | and configuration. | ||
4357 | |||
4358 | :term:`LINUX_VERSION` | ||
4359 | The Linux version from ``kernel.org`` on which the Linux kernel image | ||
4360 | being built using the OpenEmbedded build system is based. You define | ||
4361 | this variable in the kernel recipe. For example, the | ||
4362 | ``linux-yocto-3.4.bb`` kernel recipe found in | ||
4363 | ``meta/recipes-kernel/linux`` defines the variables as follows: | ||
4364 | :: | ||
4365 | |||
4366 | LINUX_VERSION ?= "3.4.24" | ||
4367 | |||
4368 | The ``LINUX_VERSION`` variable is used to define :term:`PV` | ||
4369 | for the recipe: | ||
4370 | :: | ||
4371 | |||
4372 | PV = "${LINUX_VERSION}+git${SRCPV}" | ||
4373 | |||
4374 | :term:`LINUX_VERSION_EXTENSION` | ||
4375 | A string extension compiled into the version string of the Linux | ||
4376 | kernel built with the OpenEmbedded build system. You define this | ||
4377 | variable in the kernel recipe. For example, the linux-yocto kernel | ||
4378 | recipes all define the variable as follows: | ||
4379 | :: | ||
4380 | |||
4381 | LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" | ||
4382 | |||
4383 | Defining this variable essentially sets the Linux kernel | ||
4384 | configuration item ``CONFIG_LOCALVERSION``, which is visible through | ||
4385 | the ``uname`` command. Here is an example that shows the extension | ||
4386 | assuming it was set as previously shown: | ||
4387 | :: | ||
4388 | |||
4389 | $ uname -r | ||
4390 | 3.7.0-rc8-custom | ||
4391 | |||
4392 | :term:`LOG_DIR` | ||
4393 | Specifies the directory to which the OpenEmbedded build system writes | ||
4394 | overall log files. The default directory is ``${TMPDIR}/log``. | ||
4395 | |||
4396 | For the directory containing logs specific to each task, see the | ||
4397 | :term:`T` variable. | ||
4398 | |||
4399 | :term:`MACHINE` | ||
4400 | Specifies the target device for which the image is built. You define | ||
4401 | ``MACHINE`` in the ``local.conf`` file found in the | ||
4402 | :term:`Build Directory`. By default, ``MACHINE`` is set to | ||
4403 | "qemux86", which is an x86-based architecture machine to be emulated | ||
4404 | using QEMU: | ||
4405 | :: | ||
4406 | |||
4407 | MACHINE ?= "qemux86" | ||
4408 | |||
4409 | The variable corresponds to a machine configuration file of the same | ||
4410 | name, through which machine-specific configurations are set. Thus, | ||
4411 | when ``MACHINE`` is set to "qemux86" there exists the corresponding | ||
4412 | ``qemux86.conf`` machine configuration file, which can be found in | ||
4413 | the :term:`Source Directory` in | ||
4414 | ``meta/conf/machine``. | ||
4415 | |||
4416 | The list of machines supported by the Yocto Project as shipped | ||
4417 | include the following: | ||
4418 | :: | ||
4419 | |||
4420 | MACHINE ?= "qemuarm" | ||
4421 | MACHINE ?= "qemuarm64" | ||
4422 | MACHINE ?= "qemumips" | ||
4423 | MACHINE ?= "qemumips64" | ||
4424 | MACHINE ?= "qemuppc" | ||
4425 | MACHINE ?= "qemux86" | ||
4426 | MACHINE ?= "qemux86-64" | ||
4427 | MACHINE ?= "genericx86" | ||
4428 | MACHINE ?= "genericx86-64" | ||
4429 | MACHINE ?= "beaglebone" | ||
4430 | MACHINE ?= "edgerouter" | ||
4431 | |||
4432 | The last five are Yocto Project reference hardware | ||
4433 | boards, which are provided in the ``meta-yocto-bsp`` layer. | ||
4434 | |||
4435 | .. note:: | ||
4436 | |||
4437 | Adding additional Board Support Package (BSP) layers to your | ||
4438 | configuration adds new possible settings for ``MACHINE``. | ||
4439 | |||
4440 | :term:`MACHINE_ARCH` | ||
4441 | Specifies the name of the machine-specific architecture. This | ||
4442 | variable is set automatically from :term:`MACHINE` or | ||
4443 | :term:`TUNE_PKGARCH`. You should not hand-edit | ||
4444 | the ``MACHINE_ARCH`` variable. | ||
4445 | |||
4446 | :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` | ||
4447 | A list of required machine-specific packages to install as part of | ||
4448 | the image being built. The build process depends on these packages | ||
4449 | being present. Furthermore, because this is a "machine-essential" | ||
4450 | variable, the list of packages are essential for the machine to boot. | ||
4451 | The impact of this variable affects images based on | ||
4452 | ``packagegroup-core-boot``, including the ``core-image-minimal`` | ||
4453 | image. | ||
4454 | |||
4455 | This variable is similar to the | ||
4456 | ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception | ||
4457 | that the image being built has a build dependency on the variable's | ||
4458 | list of packages. In other words, the image will not build if a file | ||
4459 | in this list is not found. | ||
4460 | |||
4461 | As an example, suppose the machine for which you are building | ||
4462 | requires ``example-init`` to be run during boot to initialize the | ||
4463 | hardware. In this case, you would use the following in the machine's | ||
4464 | ``.conf`` configuration file: | ||
4465 | :: | ||
4466 | |||
4467 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" | ||
4468 | |||
4469 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` | ||
4470 | A list of recommended machine-specific packages to install as part of | ||
4471 | the image being built. The build process does not depend on these | ||
4472 | packages being present. However, because this is a | ||
4473 | "machine-essential" variable, the list of packages are essential for | ||
4474 | the machine to boot. The impact of this variable affects images based | ||
4475 | on ``packagegroup-core-boot``, including the ``core-image-minimal`` | ||
4476 | image. | ||
4477 | |||
4478 | This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` | ||
4479 | variable with the exception that the image being built does not have | ||
4480 | a build dependency on the variable's list of packages. In other | ||
4481 | words, the image will still build if a package in this list is not | ||
4482 | found. Typically, this variable is used to handle essential kernel | ||
4483 | modules, whose functionality may be selected to be built into the | ||
4484 | kernel rather than as a module, in which case a package will not be | ||
4485 | produced. | ||
4486 | |||
4487 | Consider an example where you have a custom kernel where a specific | ||
4488 | touchscreen driver is required for the machine to be usable. However, | ||
4489 | the driver can be built as a module or into the kernel depending on | ||
4490 | the kernel configuration. If the driver is built as a module, you | ||
4491 | want it to be installed. But, when the driver is built into the | ||
4492 | kernel, you still want the build to succeed. This variable sets up a | ||
4493 | "recommends" relationship so that in the latter case, the build will | ||
4494 | not fail due to the missing package. To accomplish this, assuming the | ||
4495 | package for the module was called ``kernel-module-ab123``, you would | ||
4496 | use the following in the machine's ``.conf`` configuration file: | ||
4497 | :: | ||
4498 | |||
4499 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" | ||
4500 | |||
4501 | .. note:: | ||
4502 | |||
4503 | In this example, the ``kernel-module-ab123`` recipe needs to | ||
4504 | explicitly set its :term:`PACKAGES` variable to ensure that BitBake | ||
4505 | does not use the kernel recipe's :term:`PACKAGES_DYNAMIC` variable to | ||
4506 | satisfy the dependency. | ||
4507 | |||
4508 | Some examples of these machine essentials are flash, screen, | ||
4509 | keyboard, mouse, or touchscreen drivers (depending on the machine). | ||
4510 | |||
4511 | :term:`MACHINE_EXTRA_RDEPENDS` | ||
4512 | A list of machine-specific packages to install as part of the image | ||
4513 | being built that are not essential for the machine to boot. However, | ||
4514 | the build process for more fully-featured images depends on the | ||
4515 | packages being present. | ||
4516 | |||
4517 | This variable affects all images based on ``packagegroup-base``, | ||
4518 | which does not include the ``core-image-minimal`` or | ||
4519 | ``core-image-full-cmdline`` images. | ||
4520 | |||
4521 | The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable | ||
4522 | with the exception that the image being built has a build dependency | ||
4523 | on the variable's list of packages. In other words, the image will | ||
4524 | not build if a file in this list is not found. | ||
4525 | |||
4526 | An example is a machine that has WiFi capability but is not essential | ||
4527 | for the machine to boot the image. However, if you are building a | ||
4528 | more fully-featured image, you want to enable the WiFi. The package | ||
4529 | containing the firmware for the WiFi hardware is always expected to | ||
4530 | exist, so it is acceptable for the build process to depend upon | ||
4531 | finding the package. In this case, assuming the package for the | ||
4532 | firmware was called ``wifidriver-firmware``, you would use the | ||
4533 | following in the ``.conf`` file for the machine: | ||
4534 | :: | ||
4535 | |||
4536 | MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" | ||
4537 | |||
4538 | :term:`MACHINE_EXTRA_RRECOMMENDS` | ||
4539 | A list of machine-specific packages to install as part of the image | ||
4540 | being built that are not essential for booting the machine. The image | ||
4541 | being built has no build dependency on this list of packages. | ||
4542 | |||
4543 | This variable affects only images based on ``packagegroup-base``, | ||
4544 | which does not include the ``core-image-minimal`` or | ||
4545 | ``core-image-full-cmdline`` images. | ||
4546 | |||
4547 | This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable | ||
4548 | with the exception that the image being built does not have a build | ||
4549 | dependency on the variable's list of packages. In other words, the | ||
4550 | image will build if a file in this list is not found. | ||
4551 | |||
4552 | An example is a machine that has WiFi capability but is not essential | ||
4553 | For the machine to boot the image. However, if you are building a | ||
4554 | more fully-featured image, you want to enable WiFi. In this case, the | ||
4555 | package containing the WiFi kernel module will not be produced if the | ||
4556 | WiFi driver is built into the kernel, in which case you still want | ||
4557 | the build to succeed instead of failing as a result of the package | ||
4558 | not being found. To accomplish this, assuming the package for the | ||
4559 | module was called ``kernel-module-examplewifi``, you would use the | ||
4560 | following in the ``.conf`` file for the machine: | ||
4561 | :: | ||
4562 | |||
4563 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" | ||
4564 | |||
4565 | :term:`MACHINE_FEATURES` | ||
4566 | Specifies the list of hardware features the | ||
4567 | :term:`MACHINE` is capable of supporting. For related | ||
4568 | information on enabling features, see the | ||
4569 | :term:`DISTRO_FEATURES`, | ||
4570 | :term:`COMBINED_FEATURES`, and | ||
4571 | :term:`IMAGE_FEATURES` variables. | ||
4572 | |||
4573 | For a list of hardware features supported by the Yocto Project as | ||
4574 | shipped, see the ":ref:`ref-features-machine`" section. | ||
4575 | |||
4576 | :term:`MACHINE_FEATURES_BACKFILL` | ||
4577 | Features to be added to ``MACHINE_FEATURES`` if not also present in | ||
4578 | ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. | ||
4579 | |||
4580 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | ||
4581 | not intended to be user-configurable. It is best to just reference | ||
4582 | the variable to see which machine features are being backfilled for | ||
4583 | all machine configurations. See the ":ref:`ref-features-backfill`" | ||
4584 | section for more information. | ||
4585 | |||
4586 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | ||
4587 | Features from ``MACHINE_FEATURES_BACKFILL`` that should not be | ||
4588 | backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See | ||
4589 | the ":ref:`ref-features-backfill`" section for more information. | ||
4590 | |||
4591 | :term:`MACHINEOVERRIDES` | ||
4592 | A colon-separated list of overrides that apply to the current | ||
4593 | machine. By default, this list includes the value of | ||
4594 | :term:`MACHINE`. | ||
4595 | |||
4596 | You can extend ``MACHINEOVERRIDES`` to add extra overrides that | ||
4597 | should apply to a machine. For example, all machines emulated in QEMU | ||
4598 | (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named | ||
4599 | ``meta/conf/machine/include/qemu.inc`` that prepends the following | ||
4600 | override to ``MACHINEOVERRIDES``: | ||
4601 | :: | ||
4602 | |||
4603 | MACHINEOVERRIDES =. "qemuall:" | ||
4604 | |||
4605 | This | ||
4606 | override allows variables to be overridden for all machines emulated | ||
4607 | in QEMU, like in the following example from the ``connman-conf`` | ||
4608 | recipe: | ||
4609 | :: | ||
4610 | |||
4611 | SRC_URI_append_qemuall = " file://wired.config \ | ||
4612 | file://wired-setup \ | ||
4613 | " | ||
4614 | |||
4615 | The underlying mechanism behind | ||
4616 | ``MACHINEOVERRIDES`` is simply that it is included in the default | ||
4617 | value of :term:`OVERRIDES`. | ||
4618 | |||
4619 | :term:`MAINTAINER` | ||
4620 | The email address of the distribution maintainer. | ||
4621 | |||
4622 | :term:`MIRRORS` | ||
4623 | Specifies additional paths from which the OpenEmbedded build system | ||
4624 | gets source code. When the build system searches for source code, it | ||
4625 | first tries the local download directory. If that location fails, the | ||
4626 | build system tries locations defined by | ||
4627 | :term:`PREMIRRORS`, the upstream source, and then | ||
4628 | locations specified by ``MIRRORS`` in that order. | ||
4629 | |||
4630 | Assuming your distribution (:term:`DISTRO`) is "poky", | ||
4631 | the default value for ``MIRRORS`` is defined in the | ||
4632 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
4633 | |||
4634 | :term:`MLPREFIX` | ||
4635 | Specifies a prefix has been added to :term:`PN` to create a | ||
4636 | special version of a recipe or package (i.e. a Multilib version). The | ||
4637 | variable is used in places where the prefix needs to be added to or | ||
4638 | removed from a the name (e.g. the :term:`BPN` variable). | ||
4639 | ``MLPREFIX`` gets set when a prefix has been added to ``PN``. | ||
4640 | |||
4641 | .. note:: | ||
4642 | |||
4643 | The "ML" in ``MLPREFIX`` stands for "MultiLib". This representation is | ||
4644 | historical and comes from a time when ``nativesdk`` was a suffix | ||
4645 | rather than a prefix on the recipe name. When ``nativesdk`` was turned | ||
4646 | into a prefix, it made sense to set ``MLPREFIX`` for it as well. | ||
4647 | |||
4648 | To help understand when ``MLPREFIX`` might be needed, consider when | ||
4649 | :term:`BBCLASSEXTEND` is used to provide a | ||
4650 | ``nativesdk`` version of a recipe in addition to the target version. | ||
4651 | If that recipe declares build-time dependencies on tasks in other | ||
4652 | recipes by using :term:`DEPENDS`, then a dependency on | ||
4653 | "foo" will automatically get rewritten to a dependency on | ||
4654 | "nativesdk-foo". However, dependencies like the following will not | ||
4655 | get rewritten automatically: | ||
4656 | :: | ||
4657 | |||
4658 | do_foo[depends] += "recipe:do_foo" | ||
4659 | |||
4660 | If you want such a dependency to also get transformed, you can do the | ||
4661 | following: | ||
4662 | :: | ||
4663 | |||
4664 | do_foo[depends] += "${MLPREFIX}recipe:do_foo" | ||
4665 | |||
4666 | module_autoload | ||
4667 | This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` | ||
4668 | variable. You should replace all occurrences of ``module_autoload`` | ||
4669 | with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: | ||
4670 | :: | ||
4671 | |||
4672 | module_autoload_rfcomm = "rfcomm" | ||
4673 | |||
4674 | should now be replaced with: | ||
4675 | :: | ||
4676 | |||
4677 | KERNEL_MODULE_AUTOLOAD += "rfcomm" | ||
4678 | |||
4679 | See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. | ||
4680 | |||
4681 | module_conf | ||
4682 | Specifies `modprobe.d <http://linux.die.net/man/5/modprobe.d>`_ | ||
4683 | syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` | ||
4684 | file. | ||
4685 | |||
4686 | You can use this variable anywhere that it can be recognized by the | ||
4687 | kernel recipe or out-of-tree kernel module recipe (e.g. a machine | ||
4688 | configuration file, a distribution configuration file, an append file | ||
4689 | for the recipe, or the recipe itself). If you use this variable, you | ||
4690 | must also be sure to list the module name in the | ||
4691 | :term:`KERNEL_MODULE_AUTOLOAD` | ||
4692 | variable. | ||
4693 | |||
4694 | Here is the general syntax: | ||
4695 | :: | ||
4696 | |||
4697 | module_conf_module_name = "modprobe.d-syntax" | ||
4698 | |||
4699 | You must use the kernel module name override. | ||
4700 | |||
4701 | Run ``man modprobe.d`` in the shell to find out more information on | ||
4702 | the exact syntax you want to provide with ``module_conf``. | ||
4703 | |||
4704 | Including ``module_conf`` causes the OpenEmbedded build system to | ||
4705 | populate the ``/etc/modprobe.d/modname.conf`` file with | ||
4706 | ``modprobe.d`` syntax lines. Here is an example that adds the options | ||
4707 | ``arg1`` and ``arg2`` to a module named ``mymodule``: | ||
4708 | :: | ||
4709 | |||
4710 | module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" | ||
4711 | |||
4712 | For information on how to specify kernel modules to auto-load on | ||
4713 | boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable. | ||
4714 | |||
4715 | :term:`MODULE_TARBALL_DEPLOY` | ||
4716 | Controls creation of the ``modules-*.tgz`` file. Set this variable to | ||
4717 | "0" to disable creation of this file, which contains all of the | ||
4718 | kernel modules resulting from a kernel build. | ||
4719 | |||
4720 | :term:`MODULE_TARBALL_LINK_NAME` | ||
4721 | The link name of the kernel module tarball. This variable is set in | ||
4722 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
4723 | :: | ||
4724 | |||
4725 | MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | ||
4726 | |||
4727 | The value | ||
4728 | of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the | ||
4729 | same file, has the following value: | ||
4730 | :: | ||
4731 | |||
4732 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | ||
4733 | |||
4734 | See the :term:`MACHINE` variable for additional information. | ||
4735 | |||
4736 | :term:`MODULE_TARBALL_NAME` | ||
4737 | The base name of the kernel module tarball. This variable is set in | ||
4738 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | ||
4739 | :: | ||
4740 | |||
4741 | MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" | ||
4742 | |||
4743 | The value of the :term:`KERNEL_ARTIFACT_NAME` variable, | ||
4744 | which is set in the same file, has the following value: | ||
4745 | :: | ||
4746 | |||
4747 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
4748 | |||
4749 | :term:`MULTIMACH_TARGET_SYS` | ||
4750 | Uniquely identifies the type of the target system for which packages | ||
4751 | are being built. This variable allows output for different types of | ||
4752 | target systems to be put into different subdirectories of the same | ||
4753 | output directory. | ||
4754 | |||
4755 | The default value of this variable is: | ||
4756 | :: | ||
4757 | |||
4758 | ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} | ||
4759 | |||
4760 | Some classes (e.g. | ||
4761 | :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the | ||
4762 | ``MULTIMACH_TARGET_SYS`` value. | ||
4763 | |||
4764 | See the :term:`STAMP` variable for an example. See the | ||
4765 | :term:`STAGING_DIR_TARGET` variable for more information. | ||
4766 | |||
4767 | :term:`NATIVELSBSTRING` | ||
4768 | A string identifying the host distribution. Strings consist of the | ||
4769 | host distributor ID followed by the release, as reported by the | ||
4770 | ``lsb_release`` tool or as read from ``/etc/lsb-release``. For | ||
4771 | example, when running a build on Ubuntu 12.10, the value is | ||
4772 | "Ubuntu-12.10". If this information is unable to be determined, the | ||
4773 | value resolves to "Unknown". | ||
4774 | |||
4775 | This variable is used by default to isolate native shared state | ||
4776 | packages for different distributions (e.g. to avoid problems with | ||
4777 | ``glibc`` version incompatibilities). Additionally, the variable is | ||
4778 | checked against | ||
4779 | :term:`SANITY_TESTED_DISTROS` if that | ||
4780 | variable is set. | ||
4781 | |||
4782 | :term:`NM` | ||
4783 | The minimal command and arguments to run ``nm``. | ||
4784 | |||
4785 | :term:`NO_GENERIC_LICENSE` | ||
4786 | Avoids QA errors when you use a non-common, non-CLOSED license in a | ||
4787 | recipe. Packages exist, such as the linux-firmware package, with many | ||
4788 | licenses that are not in any way common. Also, new licenses are added | ||
4789 | occasionally to avoid introducing a lot of common license files, | ||
4790 | which are only applicable to a specific package. | ||
4791 | ``NO_GENERIC_LICENSE`` is used to allow copying a license that does | ||
4792 | not exist in common licenses. | ||
4793 | |||
4794 | The following example shows how to add ``NO_GENERIC_LICENSE`` to a | ||
4795 | recipe: | ||
4796 | :: | ||
4797 | |||
4798 | NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" | ||
4799 | |||
4800 | The following is an example that | ||
4801 | uses the ``LICENSE.Abilis.txt`` file as the license from the fetched | ||
4802 | source: | ||
4803 | :: | ||
4804 | |||
4805 | NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" | ||
4806 | |||
4807 | :term:`NO_RECOMMENDATIONS` | ||
4808 | Prevents installation of all "recommended-only" packages. | ||
4809 | Recommended-only packages are packages installed only through the | ||
4810 | :term:`RRECOMMENDS` variable). Setting the | ||
4811 | ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: | ||
4812 | |||
4813 | NO_RECOMMENDATIONS = "1" | ||
4814 | |||
4815 | You can set this variable globally in your ``local.conf`` file or you | ||
4816 | can attach it to a specific image recipe by using the recipe name | ||
4817 | override: :: | ||
4818 | |||
4819 | NO_RECOMMENDATIONS_pn-target_image = "1" | ||
4820 | |||
4821 | It is important to realize that if you choose to not install packages | ||
4822 | using this variable and some other packages are dependent on them | ||
4823 | (i.e. listed in a recipe's :term:`RDEPENDS` | ||
4824 | variable), the OpenEmbedded build system ignores your request and | ||
4825 | will install the packages to avoid dependency errors. | ||
4826 | |||
4827 | .. note:: | ||
4828 | |||
4829 | Some recommended packages might be required for certain system | ||
4830 | functionality, such as kernel modules. It is up to you to add | ||
4831 | packages with the :term:`IMAGE_INSTALL` variable. | ||
4832 | |||
4833 | Support for this variable exists only when using the IPK and RPM | ||
4834 | packaging backend. Support does not exist for DEB. | ||
4835 | |||
4836 | See the :term:`BAD_RECOMMENDATIONS` and | ||
4837 | the :term:`PACKAGE_EXCLUDE` variables for | ||
4838 | related information. | ||
4839 | |||
4840 | :term:`NOAUTOPACKAGEDEBUG` | ||
4841 | Disables auto package from splitting ``.debug`` files. If a recipe | ||
4842 | requires ``FILES_${PN}-dbg`` to be set manually, the | ||
4843 | ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the | ||
4844 | content of the debug package. For example: | ||
4845 | :: | ||
4846 | |||
4847 | NOAUTOPACKAGEDEBUG = "1" | ||
4848 | FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" | ||
4849 | FILES_${PN}-dbg = "/usr/src/debug/" | ||
4850 | FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" | ||
4851 | |||
4852 | :term:`OBJCOPY` | ||
4853 | The minimal command and arguments to run ``objcopy``. | ||
4854 | |||
4855 | :term:`OBJDUMP` | ||
4856 | The minimal command and arguments to run ``objdump``. | ||
4857 | |||
4858 | :term:`OE_BINCONFIG_EXTRA_MANGLE` | ||
4859 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | ||
4860 | this variable specifies additional arguments passed to the "sed" | ||
4861 | command. The sed command alters any paths in configuration scripts | ||
4862 | that have been set up during compilation. Inheriting this class | ||
4863 | results in all paths in these scripts being changed to point into the | ||
4864 | ``sysroots/`` directory so that all builds that use the script will | ||
4865 | use the correct directories for the cross compiling layout. | ||
4866 | |||
4867 | See the ``meta/classes/binconfig.bbclass`` in the | ||
4868 | :term:`Source Directory` for details on how this class | ||
4869 | applies these additional sed command arguments. For general | ||
4870 | information on the ``binconfig`` class, see the | ||
4871 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | ||
4872 | |||
4873 | :term:`OE_IMPORTS` | ||
4874 | An internal variable used to tell the OpenEmbedded build system what | ||
4875 | Python modules to import for every Python function run by the system. | ||
4876 | |||
4877 | .. note:: | ||
4878 | |||
4879 | Do not set this variable. It is for internal use only. | ||
4880 | |||
4881 | :term:`OE_INIT_ENV_SCRIPT` | ||
4882 | The name of the build environment setup script for the purposes of | ||
4883 | setting up the environment within the extensible SDK. The default | ||
4884 | value is "oe-init-build-env". | ||
4885 | |||
4886 | If you use a custom script to set up your build environment, set the | ||
4887 | ``OE_INIT_ENV_SCRIPT`` variable to its name. | ||
4888 | |||
4889 | :term:`OE_TERMINAL` | ||
4890 | Controls how the OpenEmbedded build system spawns interactive | ||
4891 | terminals on the host development system (e.g. using the BitBake | ||
4892 | command with the ``-c devshell`` command-line option). For more | ||
4893 | information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in | ||
4894 | the Yocto Project Development Tasks Manual. | ||
4895 | |||
4896 | You can use the following values for the ``OE_TERMINAL`` variable: | ||
4897 | |||
4898 | - auto | ||
4899 | - gnome | ||
4900 | - xfce | ||
4901 | - rxvt | ||
4902 | - screen | ||
4903 | - konsole | ||
4904 | - none | ||
4905 | |||
4906 | :term:`OEROOT` | ||
4907 | The directory from which the top-level build environment setup script | ||
4908 | is sourced. The Yocto Project provides a top-level build environment | ||
4909 | setup script: :ref:`structure-core-script`. When you run this | ||
4910 | script, the ``OEROOT`` variable resolves to the directory that | ||
4911 | contains the script. | ||
4912 | |||
4913 | For additional information on how this variable is used, see the | ||
4914 | initialization script. | ||
4915 | |||
4916 | :term:`OLDEST_KERNEL` | ||
4917 | Declares the oldest version of the Linux kernel that the produced | ||
4918 | binaries must support. This variable is passed into the build of the | ||
4919 | Embedded GNU C Library (``glibc``). | ||
4920 | |||
4921 | The default for this variable comes from the | ||
4922 | ``meta/conf/bitbake.conf`` configuration file. You can override this | ||
4923 | default by setting the variable in a custom distribution | ||
4924 | configuration file. | ||
4925 | |||
4926 | :term:`OVERRIDES` | ||
4927 | A colon-separated list of overrides that currently apply. Overrides | ||
4928 | are a BitBake mechanism that allows variables to be selectively | ||
4929 | overridden at the end of parsing. The set of overrides in | ||
4930 | ``OVERRIDES`` represents the "state" during building, which includes | ||
4931 | the current recipe being built, the machine for which it is being | ||
4932 | built, and so forth. | ||
4933 | |||
4934 | As an example, if the string "an-override" appears as an element in | ||
4935 | the colon-separated list in ``OVERRIDES``, then the following | ||
4936 | assignment will override ``FOO`` with the value "overridden" at the | ||
4937 | end of parsing: | ||
4938 | :: | ||
4939 | |||
4940 | FOO_an-override = "overridden" | ||
4941 | |||
4942 | See the | ||
4943 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" | ||
4944 | section in the BitBake User Manual for more information on the | ||
4945 | overrides mechanism. | ||
4946 | |||
4947 | The default value of ``OVERRIDES`` includes the values of the | ||
4948 | :term:`CLASSOVERRIDE`, | ||
4949 | :term:`MACHINEOVERRIDES`, and | ||
4950 | :term:`DISTROOVERRIDES` variables. Another | ||
4951 | important override included by default is ``pn-${PN}``. This override | ||
4952 | allows variables to be set for a single recipe within configuration | ||
4953 | (``.conf``) files. Here is an example: | ||
4954 | :: | ||
4955 | |||
4956 | FOO_pn-myrecipe = "myrecipe-specific value" | ||
4957 | |||
4958 | .. note:: | ||
4959 | |||
4960 | An easy way to see what overrides apply is to search for ``OVERRIDES`` | ||
4961 | in the output of the ``bitbake -e`` command. See the | ||
4962 | ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto | ||
4963 | Project Development Tasks Manual for more information. | ||
4964 | |||
4965 | :term:`P` | ||
4966 | The recipe name and version. ``P`` is comprised of the following: | ||
4967 | :: | ||
4968 | |||
4969 | ${PN}-${PV} | ||
4970 | |||
4971 | :term:`PACKAGE_ADD_METADATA` | ||
4972 | This variable defines additional metdata to add to packages. | ||
4973 | |||
4974 | You may find you need to inject additional metadata into packages. | ||
4975 | This variable allows you to do that by setting the injected data as | ||
4976 | the value. Multiple fields can be added by splitting the content with | ||
4977 | the literal separator "\n". | ||
4978 | |||
4979 | The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable | ||
4980 | to do package type specific settings. It can also be made package | ||
4981 | specific by using the package name as a suffix. | ||
4982 | |||
4983 | You can find out more about applying this variable in the | ||
4984 | ":ref:`dev-manual/common-tasks:adding custom metadata to packages`" | ||
4985 | section in the Yocto Project Development Tasks Manual. | ||
4986 | |||
4987 | :term:`PACKAGE_ARCH` | ||
4988 | The architecture of the resulting package or packages. | ||
4989 | |||
4990 | By default, the value of this variable is set to | ||
4991 | :term:`TUNE_PKGARCH` when building for the | ||
4992 | target, :term:`BUILD_ARCH` when building for the | ||
4993 | build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the | ||
4994 | SDK. | ||
4995 | |||
4996 | .. note:: | ||
4997 | |||
4998 | See :term:`SDK_ARCH` for more information. | ||
4999 | |||
5000 | However, if your recipe's output packages are built specific to the | ||
5001 | target machine rather than generally for the architecture of the | ||
5002 | machine, you should set ``PACKAGE_ARCH`` to the value of | ||
5003 | :term:`MACHINE_ARCH` in the recipe as follows: | ||
5004 | :: | ||
5005 | |||
5006 | PACKAGE_ARCH = "${MACHINE_ARCH}" | ||
5007 | |||
5008 | :term:`PACKAGE_ARCHS` | ||
5009 | Specifies a list of architectures compatible with the target machine. | ||
5010 | This variable is set automatically and should not normally be | ||
5011 | hand-edited. Entries are separated using spaces and listed in order | ||
5012 | of priority. The default value for ``PACKAGE_ARCHS`` is "all any | ||
5013 | noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". | ||
5014 | |||
5015 | :term:`PACKAGE_BEFORE_PN` | ||
5016 | Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so | ||
5017 | that those added packages can pick up files that would normally be | ||
5018 | included in the default package. | ||
5019 | |||
5020 | :term:`PACKAGE_CLASSES` | ||
5021 | This variable, which is set in the ``local.conf`` configuration file | ||
5022 | found in the ``conf`` folder of the | ||
5023 | :term:`Build Directory`, specifies the package manager the | ||
5024 | OpenEmbedded build system uses when packaging data. | ||
5025 | |||
5026 | You can provide one or more of the following arguments for the | ||
5027 | variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk | ||
5028 | package_tar" | ||
5029 | |||
5030 | .. note:: | ||
5031 | |||
5032 | While it is a legal option, the ``package_tar`` | ||
5033 | class has limited functionality due to no support for package | ||
5034 | dependencies by that backend. Therefore, it is recommended that | ||
5035 | you do not use it. | ||
5036 | |||
5037 | The build system uses only the first argument in the list as the | ||
5038 | package manager when creating your image or SDK. However, packages | ||
5039 | will be created using any additional packaging classes you specify. | ||
5040 | For example, if you use the following in your ``local.conf`` file: | ||
5041 | :: | ||
5042 | |||
5043 | PACKAGE_CLASSES ?= "package_ipk" | ||
5044 | |||
5045 | The OpenEmbedded build system uses | ||
5046 | the IPK package manager to create your image or SDK. | ||
5047 | |||
5048 | For information on packaging and build performance effects as a | ||
5049 | result of the package manager in use, see the | ||
5050 | ":ref:`package.bbclass <ref-classes-package>`" section. | ||
5051 | |||
5052 | :term:`PACKAGE_DEBUG_SPLIT_STYLE` | ||
5053 | Determines how to split up the binary and debug information when | ||
5054 | creating ``*-dbg`` packages to be used with the GNU Project Debugger | ||
5055 | (GDB). | ||
5056 | |||
5057 | With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control | ||
5058 | where debug information, which can include or exclude source files, | ||
5059 | is stored: | ||
5060 | |||
5061 | - ".debug": Debug symbol files are placed next to the binary in a | ||
5062 | ``.debug`` directory on the target. For example, if a binary is | ||
5063 | installed into ``/bin``, the corresponding debug symbol files are | ||
5064 | installed in ``/bin/.debug``. Source files are placed in | ||
5065 | ``/usr/src/debug``. | ||
5066 | |||
5067 | - "debug-file-directory": Debug symbol files are placed under | ||
5068 | ``/usr/lib/debug`` on the target, and separated by the path from | ||
5069 | where the binary is installed. For example, if a binary is | ||
5070 | installed in ``/bin``, the corresponding debug symbols are | ||
5071 | installed in ``/usr/lib/debug/bin``. Source files are placed in | ||
5072 | ``/usr/src/debug``. | ||
5073 | |||
5074 | - "debug-without-src": The same behavior as ".debug" previously | ||
5075 | described with the exception that no source files are installed. | ||
5076 | |||
5077 | - "debug-with-srcpkg": The same behavior as ".debug" previously | ||
5078 | described with the exception that all source files are placed in a | ||
5079 | separate ``*-src`` pkg. This is the default behavior. | ||
5080 | |||
5081 | You can find out more about debugging using GDB by reading the | ||
5082 | ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section | ||
5083 | in the Yocto Project Development Tasks Manual. | ||
5084 | |||
5085 | :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` | ||
5086 | Prevents specific packages from being installed when you are | ||
5087 | installing complementary packages. | ||
5088 | |||
5089 | You might find that you want to prevent installing certain packages | ||
5090 | when you are installing complementary packages. For example, if you | ||
5091 | are using :term:`IMAGE_FEATURES` to install | ||
5092 | ``dev-pkgs``, you might not want to install all packages from a | ||
5093 | particular multilib. If you find yourself in this situation, you can | ||
5094 | use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular | ||
5095 | expressions to match the packages you want to exclude. | ||
5096 | |||
5097 | :term:`PACKAGE_EXCLUDE` | ||
5098 | Lists packages that should not be installed into an image. For | ||
5099 | example: | ||
5100 | :: | ||
5101 | |||
5102 | PACKAGE_EXCLUDE = "package_name package_name package_name ..." | ||
5103 | |||
5104 | You can set this variable globally in your ``local.conf`` file or you | ||
5105 | can attach it to a specific image recipe by using the recipe name | ||
5106 | override: | ||
5107 | :: | ||
5108 | |||
5109 | PACKAGE_EXCLUDE_pn-target_image = "package_name" | ||
5110 | |||
5111 | If you choose to not install a package using this variable and some | ||
5112 | other package is dependent on it (i.e. listed in a recipe's | ||
5113 | :term:`RDEPENDS` variable), the OpenEmbedded build | ||
5114 | system generates a fatal installation error. Because the build system | ||
5115 | halts the process with a fatal error, you can use the variable with | ||
5116 | an iterative development process to remove specific components from a | ||
5117 | system. | ||
5118 | |||
5119 | Support for this variable exists only when using the IPK and RPM | ||
5120 | packaging backend. Support does not exist for DEB. | ||
5121 | |||
5122 | See the :term:`NO_RECOMMENDATIONS` and the | ||
5123 | :term:`BAD_RECOMMENDATIONS` variables for | ||
5124 | related information. | ||
5125 | |||
5126 | :term:`PACKAGE_EXTRA_ARCHS` | ||
5127 | Specifies the list of architectures compatible with the device CPU. | ||
5128 | This variable is useful when you build for several different devices | ||
5129 | that use miscellaneous processors such as XScale and ARM926-EJS. | ||
5130 | |||
5131 | :term:`PACKAGE_FEED_ARCHS` | ||
5132 | Optionally specifies the package architectures used as part of the | ||
5133 | package feed URIs during the build. When used, the | ||
5134 | ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed | ||
5135 | URI, which is constructed using the | ||
5136 | :term:`PACKAGE_FEED_URIS` and | ||
5137 | :term:`PACKAGE_FEED_BASE_PATHS` | ||
5138 | variables. | ||
5139 | |||
5140 | .. note:: | ||
5141 | |||
5142 | You can use the ``PACKAGE_FEED_ARCHS`` | ||
5143 | variable to whitelist specific package architectures. If you do | ||
5144 | not need to whitelist specific architectures, which is a common | ||
5145 | case, you can omit this variable. Omitting the variable results in | ||
5146 | all available architectures for the current machine being included | ||
5147 | into remote package feeds. | ||
5148 | |||
5149 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5150 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5151 | defined in your ``local.conf`` file: | ||
5152 | :: | ||
5153 | |||
5154 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5155 | https://example.com/packagerepos/updates" | ||
5156 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5157 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5158 | |||
5159 | Given these settings, the resulting package feeds are as follows: | ||
5160 | |||
5161 | .. code-block:: none | ||
5162 | |||
5163 | https://example.com/packagerepos/release/rpm/all | ||
5164 | https://example.com/packagerepos/release/rpm/core2-64 | ||
5165 | https://example.com/packagerepos/release/rpm-dev/all | ||
5166 | https://example.com/packagerepos/release/rpm-dev/core2-64 | ||
5167 | https://example.com/packagerepos/updates/rpm/all | ||
5168 | https://example.com/packagerepos/updates/rpm/core2-64 | ||
5169 | https://example.com/packagerepos/updates/rpm-dev/all | ||
5170 | https://example.com/packagerepos/updates/rpm-dev/core2-64 | ||
5171 | |||
5172 | :term:`PACKAGE_FEED_BASE_PATHS` | ||
5173 | Specifies the base path used when constructing package feed URIs. The | ||
5174 | ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a | ||
5175 | package feed URI used by the OpenEmbedded build system. The base path | ||
5176 | lies between the :term:`PACKAGE_FEED_URIS` | ||
5177 | and :term:`PACKAGE_FEED_ARCHS` variables. | ||
5178 | |||
5179 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5180 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5181 | defined in your ``local.conf`` file: | ||
5182 | :: | ||
5183 | |||
5184 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5185 | https://example.com/packagerepos/updates" | ||
5186 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5187 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5188 | |||
5189 | Given these settings, the resulting package feeds are as follows: | ||
5190 | |||
5191 | .. code-block:: none | ||
5192 | |||
5193 | https://example.com/packagerepos/release/rpm/all | ||
5194 | https://example.com/packagerepos/release/rpm/core2-64 | ||
5195 | https://example.com/packagerepos/release/rpm-dev/all | ||
5196 | https://example.com/packagerepos/release/rpm-dev/core2-64 | ||
5197 | https://example.com/packagerepos/updates/rpm/all | ||
5198 | https://example.com/packagerepos/updates/rpm/core2-64 | ||
5199 | https://example.com/packagerepos/updates/rpm-dev/all | ||
5200 | https://example.com/packagerepos/updates/rpm-dev/core2-64 | ||
5201 | |||
5202 | :term:`PACKAGE_FEED_URIS` | ||
5203 | Specifies the front portion of the package feed URI used by the | ||
5204 | OpenEmbedded build system. Each final package feed URI is comprised | ||
5205 | of ``PACKAGE_FEED_URIS``, | ||
5206 | :term:`PACKAGE_FEED_BASE_PATHS`, and | ||
5207 | :term:`PACKAGE_FEED_ARCHS` variables. | ||
5208 | |||
5209 | Consider the following example where the ``PACKAGE_FEED_URIS``, | ||
5210 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | ||
5211 | defined in your ``local.conf`` file: | ||
5212 | :: | ||
5213 | |||
5214 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | ||
5215 | https://example.com/packagerepos/updates" | ||
5216 | PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev" | ||
5217 | PACKAGE_FEED_ARCHS = "all core2-64" | ||
5218 | |||
5219 | Given these settings, the resulting package feeds are as follows: | ||
5220 | |||
5221 | .. code-block:: none | ||
5222 | |||
5223 | https://example.com/packagerepos/release/rpm/all | ||
5224 | https://example.com/packagerepos/release/rpm/core2-64 | ||
5225 | https://example.com/packagerepos/release/rpm-dev/all | ||
5226 | https://example.com/packagerepos/release/rpm-dev/core2-64 | ||
5227 | https://example.com/packagerepos/updates/rpm/all | ||
5228 | https://example.com/packagerepos/updates/rpm/core2-64 | ||
5229 | https://example.com/packagerepos/updates/rpm-dev/all | ||
5230 | https://example.com/packagerepos/updates/rpm-dev/core2-64 | ||
5231 | |||
5232 | :term:`PACKAGE_INSTALL` | ||
5233 | The final list of packages passed to the package manager for | ||
5234 | installation into the image. | ||
5235 | |||
5236 | Because the package manager controls actual installation of all | ||
5237 | packages, the list of packages passed using ``PACKAGE_INSTALL`` is | ||
5238 | not the final list of packages that are actually installed. This | ||
5239 | variable is internal to the image construction code. Consequently, in | ||
5240 | general, you should use the | ||
5241 | :term:`IMAGE_INSTALL` variable to specify | ||
5242 | packages for installation. The exception to this is when working with | ||
5243 | the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` | ||
5244 | image. When working with an initial RAM filesystem (initramfs) image, | ||
5245 | use the ``PACKAGE_INSTALL`` variable. For information on creating an | ||
5246 | initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | ||
5247 | in the Yocto Project Development Tasks Manual. | ||
5248 | |||
5249 | :term:`PACKAGE_INSTALL_ATTEMPTONLY` | ||
5250 | Specifies a list of packages the OpenEmbedded build system attempts | ||
5251 | to install when creating an image. If a listed package fails to | ||
5252 | install, the build system does not generate an error. This variable | ||
5253 | is generally not user-defined. | ||
5254 | |||
5255 | :term:`PACKAGE_PREPROCESS_FUNCS` | ||
5256 | Specifies a list of functions run to pre-process the | ||
5257 | :term:`PKGD` directory prior to splitting the files out | ||
5258 | to individual packages. | ||
5259 | |||
5260 | :term:`PACKAGE_WRITE_DEPS` | ||
5261 | Specifies a list of dependencies for post-installation and | ||
5262 | pre-installation scripts on native/cross tools. If your | ||
5263 | post-installation or pre-installation script can execute at rootfs | ||
5264 | creation time rather than on the target but depends on a native tool | ||
5265 | in order to execute, you need to list the tools in | ||
5266 | ``PACKAGE_WRITE_DEPS``. | ||
5267 | |||
5268 | For information on running post-installation scripts, see the | ||
5269 | ":ref:`dev-manual/common-tasks:post-installation scripts`" | ||
5270 | section in the Yocto Project Development Tasks Manual. | ||
5271 | |||
5272 | :term:`PACKAGECONFIG` | ||
5273 | This variable provides a means of enabling or disabling features of a | ||
5274 | recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in | ||
5275 | recipes when you specify features and then arguments that define | ||
5276 | feature behaviors. Here is the basic block structure (broken over | ||
5277 | multiple lines for readability): | ||
5278 | :: | ||
5279 | |||
5280 | PACKAGECONFIG ??= "f1 f2 f3 ..." | ||
5281 | PACKAGECONFIG[f1] = "\ | ||
5282 | --with-f1, \ | ||
5283 | --without-f1, \ | ||
5284 | build-deps-for-f1, \ | ||
5285 | runtime-deps-for-f1, \ | ||
5286 | runtime-recommends-for-f1, \ | ||
5287 | packageconfig-conflicts-for-f1" | ||
5288 | PACKAGECONFIG[f2] = "\ | ||
5289 | ... and so on and so on ... | ||
5290 | |||
5291 | The ``PACKAGECONFIG`` variable itself specifies a space-separated | ||
5292 | list of the features to enable. Following the features, you can | ||
5293 | determine the behavior of each feature by providing up to six | ||
5294 | order-dependent arguments, which are separated by commas. You can | ||
5295 | omit any argument you like but must retain the separating commas. The | ||
5296 | order is important and specifies the following: | ||
5297 | |||
5298 | 1. Extra arguments that should be added to the configure script | ||
5299 | argument list (:term:`EXTRA_OECONF` or | ||
5300 | :term:`PACKAGECONFIG_CONFARGS`) if | ||
5301 | the feature is enabled. | ||
5302 | |||
5303 | 2. Extra arguments that should be added to ``EXTRA_OECONF`` or | ||
5304 | ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. | ||
5305 | |||
5306 | 3. Additional build dependencies (:term:`DEPENDS`) | ||
5307 | that should be added if the feature is enabled. | ||
5308 | |||
5309 | 4. Additional runtime dependencies (:term:`RDEPENDS`) | ||
5310 | that should be added if the feature is enabled. | ||
5311 | |||
5312 | 5. Additional runtime recommendations | ||
5313 | (:term:`RRECOMMENDS`) that should be added if | ||
5314 | the feature is enabled. | ||
5315 | |||
5316 | 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` | ||
5317 | settings for this feature. | ||
5318 | |||
5319 | Consider the following ``PACKAGECONFIG`` block taken from the | ||
5320 | ``librsvg`` recipe. In this example the feature is ``gtk``, which has | ||
5321 | three arguments that determine the feature's behavior. | ||
5322 | :: | ||
5323 | |||
5324 | PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" | ||
5325 | |||
5326 | The | ||
5327 | ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is | ||
5328 | enabled. In this case, ``--with-gtk3`` is added to the configure | ||
5329 | script argument list and ``gtk+3`` is added to ``DEPENDS``. On the | ||
5330 | other hand, if the feature is disabled say through a ``.bbappend`` | ||
5331 | file in another layer, then the second argument ``--without-gtk3`` is | ||
5332 | added to the configure script instead. | ||
5333 | |||
5334 | The basic ``PACKAGECONFIG`` structure previously described holds true | ||
5335 | regardless of whether you are creating a block or changing a block. | ||
5336 | When creating a block, use the structure inside your recipe. | ||
5337 | |||
5338 | If you want to change an existing ``PACKAGECONFIG`` block, you can do | ||
5339 | so one of two ways: | ||
5340 | |||
5341 | - *Append file:* Create an append file named | ||
5342 | recipename\ ``.bbappend`` in your layer and override the value of | ||
5343 | ``PACKAGECONFIG``. You can either completely override the | ||
5344 | variable: | ||
5345 | :: | ||
5346 | |||
5347 | PACKAGECONFIG = "f4 f5" | ||
5348 | |||
5349 | Or, you can just append the variable: | ||
5350 | :: | ||
5351 | |||
5352 | PACKAGECONFIG_append = " f4" | ||
5353 | |||
5354 | - *Configuration file:* This method is identical to changing the | ||
5355 | block through an append file except you edit your ``local.conf`` | ||
5356 | or ``mydistro.conf`` file. As with append files previously | ||
5357 | described, you can either completely override the variable: | ||
5358 | :: | ||
5359 | |||
5360 | PACKAGECONFIG_pn-recipename = "f4 f5" | ||
5361 | |||
5362 | Or, you can just amend the variable: | ||
5363 | :: | ||
5364 | |||
5365 | PACKAGECONFIG_append_pn-recipename = " f4" | ||
5366 | |||
5367 | :term:`PACKAGECONFIG_CONFARGS` | ||
5368 | A space-separated list of configuration options generated from the | ||
5369 | :term:`PACKAGECONFIG` setting. | ||
5370 | |||
5371 | Classes such as :ref:`autotools <ref-classes-autotools>` and | ||
5372 | :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to | ||
5373 | pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, | ||
5374 | respectively. If you are using ``PACKAGECONFIG`` but not a class that | ||
5375 | handles the ``do_configure`` task, then you need to use | ||
5376 | ``PACKAGECONFIG_CONFARGS`` appropriately. | ||
5377 | |||
5378 | :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` | ||
5379 | For recipes inheriting the | ||
5380 | :ref:`packagegroup <ref-classes-packagegroup>` class, setting | ||
5381 | ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the | ||
5382 | normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) | ||
5383 | should not be automatically created by the ``packagegroup`` recipe, | ||
5384 | which is the default behavior. | ||
5385 | |||
5386 | :term:`PACKAGES` | ||
5387 | The list of packages the recipe creates. The default value is the | ||
5388 | following: | ||
5389 | :: | ||
5390 | |||
5391 | ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} | ||
5392 | |||
5393 | During packaging, the :ref:`ref-tasks-package` task | ||
5394 | goes through ``PACKAGES`` and uses the :term:`FILES` | ||
5395 | variable corresponding to each package to assign files to the | ||
5396 | package. If a file matches the ``FILES`` variable for more than one | ||
5397 | package in ``PACKAGES``, it will be assigned to the earliest | ||
5398 | (leftmost) package. | ||
5399 | |||
5400 | Packages in the variable's list that are empty (i.e. where none of | ||
5401 | the patterns in ``FILES_``\ pkg match any files installed by the | ||
5402 | :ref:`ref-tasks-install` task) are not generated, | ||
5403 | unless generation is forced through the | ||
5404 | :term:`ALLOW_EMPTY` variable. | ||
5405 | |||
5406 | :term:`PACKAGES_DYNAMIC` | ||
5407 | A promise that your recipe satisfies runtime dependencies for | ||
5408 | optional modules that are found in other recipes. | ||
5409 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | ||
5410 | only states that they should be satisfied. For example, if a hard, | ||
5411 | runtime dependency (:term:`RDEPENDS`) of another | ||
5412 | package is satisfied at build time through the ``PACKAGES_DYNAMIC`` | ||
5413 | variable, but a package with the module name is never actually | ||
5414 | produced, then the other package will be broken. Thus, if you attempt | ||
5415 | to include that package in an image, you will get a dependency | ||
5416 | failure from the packaging system during the | ||
5417 | :ref:`ref-tasks-rootfs` task. | ||
5418 | |||
5419 | Typically, if there is a chance that such a situation can occur and | ||
5420 | the package that is not created is valid without the dependency being | ||
5421 | satisfied, then you should use :term:`RRECOMMENDS` | ||
5422 | (a soft runtime dependency) instead of ``RDEPENDS``. | ||
5423 | |||
5424 | For an example of how to use the ``PACKAGES_DYNAMIC`` variable when | ||
5425 | you are splitting packages, see the | ||
5426 | ":ref:`dev-manual/common-tasks:handling optional module packaging`" | ||
5427 | section in the Yocto Project Development Tasks Manual. | ||
5428 | |||
5429 | :term:`PACKAGESPLITFUNCS` | ||
5430 | Specifies a list of functions run to perform additional splitting of | ||
5431 | files into individual packages. Recipes can either prepend to this | ||
5432 | variable or prepend to the ``populate_packages`` function in order to | ||
5433 | perform additional package splitting. In either case, the function | ||
5434 | should set :term:`PACKAGES`, | ||
5435 | :term:`FILES`, :term:`RDEPENDS` and | ||
5436 | other packaging variables appropriately in order to perform the | ||
5437 | desired splitting. | ||
5438 | |||
5439 | :term:`PARALLEL_MAKE` | ||
5440 | Extra options passed to the ``make`` command during the | ||
5441 | :ref:`ref-tasks-compile` task in order to specify | ||
5442 | parallel compilation on the local build host. This variable is | ||
5443 | usually in the form "-j x", where x represents the maximum number of | ||
5444 | parallel threads ``make`` can run. | ||
5445 | |||
5446 | .. note:: | ||
5447 | |||
5448 | In order for ``PARALLEL_MAKE`` to be effective, ``make`` must be | ||
5449 | called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure | ||
5450 | this is to use the ``oe_runmake`` function. | ||
5451 | |||
5452 | By default, the OpenEmbedded build system automatically sets this | ||
5453 | variable to be equal to the number of cores the build system uses. | ||
5454 | |||
5455 | .. note:: | ||
5456 | |||
5457 | If the software being built experiences dependency issues during | ||
5458 | the ``do_compile`` task that result in race conditions, you can clear | ||
5459 | the ``PARALLEL_MAKE`` variable within the recipe as a workaround. For | ||
5460 | information on addressing race conditions, see the | ||
5461 | ":ref:`dev-manual/common-tasks:debugging parallel make races`" | ||
5462 | section in the Yocto Project Development Tasks Manual. | ||
5463 | |||
5464 | For single socket systems (i.e. one CPU), you should not have to | ||
5465 | override this variable to gain optimal parallelism during builds. | ||
5466 | However, if you have very large systems that employ multiple physical | ||
5467 | CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is | ||
5468 | not set higher than "-j 20". | ||
5469 | |||
5470 | For more information on speeding up builds, see the | ||
5471 | ":ref:`dev-manual/common-tasks:speeding up a build`" | ||
5472 | section in the Yocto Project Development Tasks Manual. | ||
5473 | |||
5474 | :term:`PARALLEL_MAKEINST` | ||
5475 | Extra options passed to the ``make install`` command during the | ||
5476 | :ref:`ref-tasks-install` task in order to specify | ||
5477 | parallel installation. This variable defaults to the value of | ||
5478 | :term:`PARALLEL_MAKE`. | ||
5479 | |||
5480 | .. note:: | ||
5481 | |||
5482 | In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must | ||
5483 | be called with | ||
5484 | ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy | ||
5485 | way to ensure this is to use the ``oe_runmake`` function. | ||
5486 | |||
5487 | If the software being built experiences dependency issues during | ||
5488 | the ``do_install`` task that result in race conditions, you can | ||
5489 | clear the ``PARALLEL_MAKEINST`` variable within the recipe as a | ||
5490 | workaround. For information on addressing race conditions, see the | ||
5491 | ":ref:`dev-manual/common-tasks:debugging parallel make races`" | ||
5492 | section in the Yocto Project Development Tasks Manual. | ||
5493 | |||
5494 | :term:`PATCHRESOLVE` | ||
5495 | Determines the action to take when a patch fails. You can set this | ||
5496 | variable to one of two values: "noop" and "user". | ||
5497 | |||
5498 | The default value of "noop" causes the build to simply fail when the | ||
5499 | OpenEmbedded build system cannot successfully apply a patch. Setting | ||
5500 | the value to "user" causes the build system to launch a shell and | ||
5501 | places you in the right location so that you can manually resolve the | ||
5502 | conflicts. | ||
5503 | |||
5504 | Set this variable in your ``local.conf`` file. | ||
5505 | |||
5506 | :term:`PATCHTOOL` | ||
5507 | Specifies the utility used to apply patches for a recipe during the | ||
5508 | :ref:`ref-tasks-patch` task. You can specify one of | ||
5509 | three utilities: "patch", "quilt", or "git". The default utility used | ||
5510 | is "quilt" except for the quilt-native recipe itself. Because the | ||
5511 | quilt tool is not available at the time quilt-native is being | ||
5512 | patched, it uses "patch". | ||
5513 | |||
5514 | If you wish to use an alternative patching tool, set the variable in | ||
5515 | the recipe using one of the following: | ||
5516 | :: | ||
5517 | |||
5518 | PATCHTOOL = "patch" | ||
5519 | PATCHTOOL = "quilt" | ||
5520 | PATCHTOOL = "git" | ||
5521 | |||
5522 | :term:`PE` | ||
5523 | The epoch of the recipe. By default, this variable is unset. The | ||
5524 | variable is used to make upgrades possible when the versioning scheme | ||
5525 | changes in some backwards incompatible way. | ||
5526 | |||
5527 | ``PE`` is the default value of the :term:`PKGE` variable. | ||
5528 | |||
5529 | :term:`PF` | ||
5530 | Specifies the recipe or package name and includes all version and | ||
5531 | revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and | ||
5532 | ``bash-4.2-r1/``). This variable is comprised of the following: | ||
5533 | ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} | ||
5534 | |||
5535 | :term:`PIXBUF_PACKAGES` | ||
5536 | When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` | ||
5537 | class, this variable identifies packages that contain the pixbuf | ||
5538 | loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` | ||
5539 | class assumes that the loaders are in the recipe's main package (i.e. | ||
5540 | ``${``\ :term:`PN`\ ``}``). Use this variable if the | ||
5541 | loaders you need are in a package other than that main package. | ||
5542 | |||
5543 | :term:`PKG` | ||
5544 | The name of the resulting package created by the OpenEmbedded build | ||
5545 | system. | ||
5546 | |||
5547 | .. note:: | ||
5548 | |||
5549 | When using the ``PKG`` variable, you must use a package name override. | ||
5550 | |||
5551 | For example, when the :ref:`debian <ref-classes-debian>` class | ||
5552 | renames the output package, it does so by setting | ||
5553 | ``PKG_packagename``. | ||
5554 | |||
5555 | :term:`PKG_CONFIG_PATH` | ||
5556 | The path to ``pkg-config`` files for the current build context. | ||
5557 | ``pkg-config`` reads this variable from the environment. | ||
5558 | |||
5559 | :term:`PKGD` | ||
5560 | Points to the destination directory for files to be packaged before | ||
5561 | they are split into individual packages. This directory defaults to | ||
5562 | the following: | ||
5563 | :: | ||
5564 | |||
5565 | ${WORKDIR}/package | ||
5566 | |||
5567 | Do not change this default. | ||
5568 | |||
5569 | :term:`PKGDATA_DIR` | ||
5570 | Points to a shared, global-state directory that holds data generated | ||
5571 | during the packaging process. During the packaging process, the | ||
5572 | :ref:`ref-tasks-packagedata` task packages data | ||
5573 | for each recipe and installs it into this temporary, shared area. | ||
5574 | This directory defaults to the following, which you should not | ||
5575 | change: | ||
5576 | :: | ||
5577 | |||
5578 | ${STAGING_DIR_HOST}/pkgdata | ||
5579 | |||
5580 | For examples of how this data is used, see the | ||
5581 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | ||
5582 | section in the Yocto Project Overview and Concepts Manual and the | ||
5583 | ":ref:`dev-manual/common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" | ||
5584 | section in the Yocto Project Development Tasks Manual. For more | ||
5585 | information on the shared, global-state directory, see | ||
5586 | :term:`STAGING_DIR_HOST`. | ||
5587 | |||
5588 | :term:`PKGDEST` | ||
5589 | Points to the parent directory for files to be packaged after they | ||
5590 | have been split into individual packages. This directory defaults to | ||
5591 | the following: | ||
5592 | :: | ||
5593 | |||
5594 | ${WORKDIR}/packages-split | ||
5595 | |||
5596 | Under this directory, the build system creates directories for each | ||
5597 | package specified in :term:`PACKAGES`. Do not change | ||
5598 | this default. | ||
5599 | |||
5600 | :term:`PKGDESTWORK` | ||
5601 | Points to a temporary work area where the | ||
5602 | :ref:`ref-tasks-package` task saves package metadata. | ||
5603 | The ``PKGDESTWORK`` location defaults to the following: | ||
5604 | :: | ||
5605 | |||
5606 | ${WORKDIR}/pkgdata | ||
5607 | |||
5608 | Do not change this default. | ||
5609 | |||
5610 | The :ref:`ref-tasks-packagedata` task copies the | ||
5611 | package metadata from ``PKGDESTWORK`` to | ||
5612 | :term:`PKGDATA_DIR` to make it available globally. | ||
5613 | |||
5614 | :term:`PKGE` | ||
5615 | The epoch of the package(s) built by the recipe. By default, ``PKGE`` | ||
5616 | is set to :term:`PE`. | ||
5617 | |||
5618 | :term:`PKGR` | ||
5619 | The revision of the package(s) built by the recipe. By default, | ||
5620 | ``PKGR`` is set to :term:`PR`. | ||
5621 | |||
5622 | :term:`PKGV` | ||
5623 | The version of the package(s) built by the recipe. By default, | ||
5624 | ``PKGV`` is set to :term:`PV`. | ||
5625 | |||
5626 | :term:`PN` | ||
5627 | This variable can have two separate functions depending on the | ||
5628 | context: a recipe name or a resulting package name. | ||
5629 | |||
5630 | ``PN`` refers to a recipe name in the context of a file used by the | ||
5631 | OpenEmbedded build system as input to create a package. The name is | ||
5632 | normally extracted from the recipe file name. For example, if the | ||
5633 | recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` | ||
5634 | will be "expat". | ||
5635 | |||
5636 | The variable refers to a package name in the context of a file | ||
5637 | created or produced by the OpenEmbedded build system. | ||
5638 | |||
5639 | If applicable, the ``PN`` variable also contains any special suffix | ||
5640 | or prefix. For example, using ``bash`` to build packages for the | ||
5641 | native machine, ``PN`` is ``bash-native``. Using ``bash`` to build | ||
5642 | packages for the target and for Multilib, ``PN`` would be ``bash`` | ||
5643 | and ``lib64-bash``, respectively. | ||
5644 | |||
5645 | :term:`PNBLACKLIST` | ||
5646 | Lists recipes you do not want the OpenEmbedded build system to build. | ||
5647 | This variable works in conjunction with the | ||
5648 | :ref:`blacklist <ref-classes-blacklist>` class, which is inherited | ||
5649 | globally. | ||
5650 | |||
5651 | To prevent a recipe from being built, use the ``PNBLACKLIST`` | ||
5652 | variable in your ``local.conf`` file. Here is an example that | ||
5653 | prevents ``myrecipe`` from being built: | ||
5654 | :: | ||
5655 | |||
5656 | PNBLACKLIST[myrecipe] = "Not supported by our organization." | ||
5657 | |||
5658 | :term:`POPULATE_SDK_POST_HOST_COMMAND` | ||
5659 | Specifies a list of functions to call once the OpenEmbedded build | ||
5660 | system has created the host part of the SDK. You can specify | ||
5661 | functions separated by semicolons: | ||
5662 | :: | ||
5663 | |||
5664 | POPULATE_SDK_POST_HOST_COMMAND += "function; ... " | ||
5665 | |||
5666 | If you need to pass the SDK path to a command within a function, you | ||
5667 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
5668 | the OpenEmbedded build system when creating SDK output. See the | ||
5669 | :term:`SDK_DIR` variable for more information. | ||
5670 | |||
5671 | :term:`POPULATE_SDK_POST_TARGET_COMMAND` | ||
5672 | Specifies a list of functions to call once the OpenEmbedded build | ||
5673 | system has created the target part of the SDK. You can specify | ||
5674 | functions separated by semicolons: | ||
5675 | :: | ||
5676 | |||
5677 | POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " | ||
5678 | |||
5679 | If you need to pass the SDK path to a command within a function, you | ||
5680 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
5681 | the OpenEmbedded build system when creating SDK output. See the | ||
5682 | :term:`SDK_DIR` variable for more information. | ||
5683 | |||
5684 | :term:`PR` | ||
5685 | The revision of the recipe. The default value for this variable is | ||
5686 | "r0". Subsequent revisions of the recipe conventionally have the | ||
5687 | values "r1", "r2", and so forth. When :term:`PV` increases, | ||
5688 | ``PR`` is conventionally reset to "r0". | ||
5689 | |||
5690 | .. note:: | ||
5691 | |||
5692 | The OpenEmbedded build system does not need the aid of ``PR`` | ||
5693 | to know when to rebuild a recipe. The build system uses the task | ||
5694 | :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the | ||
5695 | :ref:`stamp <structure-build-tmp-stamps>` and | ||
5696 | :ref:`overview-manual/concepts:shared state cache` | ||
5697 | mechanisms. | ||
5698 | |||
5699 | The ``PR`` variable primarily becomes significant when a package | ||
5700 | manager dynamically installs packages on an already built image. In | ||
5701 | this case, ``PR``, which is the default value of | ||
5702 | :term:`PKGR`, helps the package manager distinguish which | ||
5703 | package is the most recent one in cases where many packages have the | ||
5704 | same ``PV`` (i.e. ``PKGV``). A component having many packages with | ||
5705 | the same ``PV`` usually means that the packages all install the same | ||
5706 | upstream version, but with later (``PR``) version packages including | ||
5707 | packaging fixes. | ||
5708 | |||
5709 | .. note:: | ||
5710 | |||
5711 | ``PR`` does not need to be increased for changes that do not change the | ||
5712 | package contents or metadata. | ||
5713 | |||
5714 | Because manually managing ``PR`` can be cumbersome and error-prone, | ||
5715 | an automated solution exists. See the | ||
5716 | ":ref:`dev-manual/common-tasks:working with a pr service`" section | ||
5717 | in the Yocto Project Development Tasks Manual for more information. | ||
5718 | |||
5719 | :term:`PREFERRED_PROVIDER` | ||
5720 | If multiple recipes provide the same item, this variable determines | ||
5721 | which recipe is preferred and thus provides the item (i.e. the | ||
5722 | preferred provider). You should always suffix this variable with the | ||
5723 | name of the provided item. And, you should define the variable using | ||
5724 | the preferred recipe's name (:term:`PN`). Here is a common | ||
5725 | example: | ||
5726 | :: | ||
5727 | |||
5728 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | ||
5729 | |||
5730 | In the previous example, multiple recipes are providing "virtual/kernel". | ||
5731 | The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of | ||
5732 | the recipe you prefer to provide "virtual/kernel". | ||
5733 | |||
5734 | Following are more examples: | ||
5735 | :: | ||
5736 | |||
5737 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | ||
5738 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" | ||
5739 | |||
5740 | For more | ||
5741 | information, see the ":ref:`dev-manual/common-tasks:using virtual providers`" | ||
5742 | section in the Yocto Project Development Tasks Manual. | ||
5743 | |||
5744 | .. note:: | ||
5745 | |||
5746 | If you use a ``virtual/\*`` item with ``PREFERRED_PROVIDER``, then any | ||
5747 | recipe that :term:`PROVIDES` that item but is not selected (defined) | ||
5748 | by ``PREFERRED_PROVIDER`` is prevented from building, which is usually | ||
5749 | desirable since this mechanism is designed to select between mutually | ||
5750 | exclusive alternative providers. | ||
5751 | |||
5752 | :term:`PREFERRED_VERSION` | ||
5753 | If multiple versions of recipes exist, this variable determines which | ||
5754 | version is given preference. You must always suffix the variable with | ||
5755 | the :term:`PN` you want to select, and you should set the | ||
5756 | :term:`PV` accordingly for precedence. | ||
5757 | |||
5758 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | ||
5759 | through the "``%``" character. You can use the character to match any | ||
5760 | number of characters, which can be useful when specifying versions | ||
5761 | that contain long revision numbers that potentially change. Here are | ||
5762 | two examples: | ||
5763 | :: | ||
5764 | |||
5765 | PREFERRED_VERSION_python = "3.4.0" | ||
5766 | PREFERRED_VERSION_linux-yocto = "5.0%" | ||
5767 | |||
5768 | .. note:: | ||
5769 | |||
5770 | The use of the "%" character is limited in that it only works at the end of the | ||
5771 | string. You cannot use the wildcard character in any other | ||
5772 | location of the string. | ||
5773 | |||
5774 | The specified version is matched against :term:`PV`, which | ||
5775 | does not necessarily match the version part of the recipe's filename. | ||
5776 | For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` | ||
5777 | where ``foo_git.bb`` contains the following assignment: | ||
5778 | :: | ||
5779 | |||
5780 | PV = "1.1+git${SRCPV}" | ||
5781 | |||
5782 | In this case, the correct way to select | ||
5783 | ``foo_git.bb`` is by using an assignment such as the following: | ||
5784 | :: | ||
5785 | |||
5786 | PREFERRED_VERSION_foo = "1.1+git%" | ||
5787 | |||
5788 | Compare that previous example | ||
5789 | against the following incorrect example, which does not work: | ||
5790 | :: | ||
5791 | |||
5792 | PREFERRED_VERSION_foo = "git" | ||
5793 | |||
5794 | Sometimes the ``PREFERRED_VERSION`` variable can be set by | ||
5795 | configuration files in a way that is hard to change. You can use | ||
5796 | :term:`OVERRIDES` to set a machine-specific | ||
5797 | override. Here is an example: | ||
5798 | :: | ||
5799 | |||
5800 | PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" | ||
5801 | |||
5802 | Although not recommended, worst case, you can also use the | ||
5803 | "forcevariable" override, which is the strongest override possible. | ||
5804 | Here is an example: | ||
5805 | :: | ||
5806 | |||
5807 | PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" | ||
5808 | |||
5809 | .. note:: | ||
5810 | |||
5811 | The ``\_forcevariable`` override is not handled specially. This override | ||
5812 | only works because the default value of ``OVERRIDES`` includes "forcevariable". | ||
5813 | |||
5814 | :term:`PREMIRRORS` | ||
5815 | Specifies additional paths from which the OpenEmbedded build system | ||
5816 | gets source code. When the build system searches for source code, it | ||
5817 | first tries the local download directory. If that location fails, the | ||
5818 | build system tries locations defined by ``PREMIRRORS``, the upstream | ||
5819 | source, and then locations specified by | ||
5820 | :term:`MIRRORS` in that order. | ||
5821 | |||
5822 | Assuming your distribution (:term:`DISTRO`) is "poky", | ||
5823 | the default value for ``PREMIRRORS`` is defined in the | ||
5824 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
5825 | |||
5826 | Typically, you could add a specific server for the build system to | ||
5827 | attempt before any others by adding something like the following to | ||
5828 | the ``local.conf`` configuration file in the | ||
5829 | :term:`Build Directory`: | ||
5830 | :: | ||
5831 | |||
5832 | PREMIRRORS_prepend = "\ | ||
5833 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
5834 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
5835 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | ||
5836 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | ||
5837 | |||
5838 | These changes cause the | ||
5839 | build system to intercept Git, FTP, HTTP, and HTTPS requests and | ||
5840 | direct them to the ``http://`` sources mirror. You can use | ||
5841 | ``file://`` URLs to point to local directories or network shares as | ||
5842 | well. | ||
5843 | |||
5844 | :term:`PRIORITY` | ||
5845 | Indicates the importance of a package. | ||
5846 | |||
5847 | ``PRIORITY`` is considered to be part of the distribution policy | ||
5848 | because the importance of any given recipe depends on the purpose for | ||
5849 | which the distribution is being produced. Thus, ``PRIORITY`` is not | ||
5850 | normally set within recipes. | ||
5851 | |||
5852 | You can set ``PRIORITY`` to "required", "standard", "extra", and | ||
5853 | "optional", which is the default. | ||
5854 | |||
5855 | :term:`PRIVATE_LIBS` | ||
5856 | Specifies libraries installed within a recipe that should be ignored | ||
5857 | by the OpenEmbedded build system's shared library resolver. This | ||
5858 | variable is typically used when software being built by a recipe has | ||
5859 | its own private versions of a library normally provided by another | ||
5860 | recipe. In this case, you would not want the package containing the | ||
5861 | private libraries to be set as a dependency on other unrelated | ||
5862 | packages that should instead depend on the package providing the | ||
5863 | standard version of the library. | ||
5864 | |||
5865 | Libraries specified in this variable should be specified by their | ||
5866 | file name. For example, from the Firefox recipe in meta-browser: | ||
5867 | :: | ||
5868 | |||
5869 | PRIVATE_LIBS = "libmozjs.so \ | ||
5870 | libxpcom.so \ | ||
5871 | libnspr4.so \ | ||
5872 | libxul.so \ | ||
5873 | libmozalloc.so \ | ||
5874 | libplc4.so \ | ||
5875 | libplds4.so" | ||
5876 | |||
5877 | For more information, see the | ||
5878 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | ||
5879 | section in the Yocto Project Overview and Concepts Manual. | ||
5880 | |||
5881 | :term:`PROVIDES` | ||
5882 | A list of aliases by which a particular recipe can be known. By | ||
5883 | default, a recipe's own ``PN`` is implicitly already in its | ||
5884 | ``PROVIDES`` list and therefore does not need to mention that it | ||
5885 | provides itself. If a recipe uses ``PROVIDES``, the additional | ||
5886 | aliases are synonyms for the recipe and can be useful for satisfying | ||
5887 | dependencies of other recipes during the build as specified by | ||
5888 | ``DEPENDS``. | ||
5889 | |||
5890 | Consider the following example ``PROVIDES`` statement from the recipe | ||
5891 | file ``eudev_3.2.9.bb``: | ||
5892 | :: | ||
5893 | |||
5894 | PROVIDES = "udev" | ||
5895 | |||
5896 | The ``PROVIDES`` statement | ||
5897 | results in the "eudev" recipe also being available as simply "udev". | ||
5898 | |||
5899 | .. note:: | ||
5900 | |||
5901 | Given that a recipe's own recipe name is already implicitly in its | ||
5902 | own PROVIDES list, it is unnecessary to add aliases with the "+=" operator; | ||
5903 | using a simple assignment will be sufficient. In other words, | ||
5904 | while you could write: | ||
5905 | :: | ||
5906 | |||
5907 | PROVIDES += "udev" | ||
5908 | |||
5909 | |||
5910 | in the above, the "+=" is overkill and unnecessary. | ||
5911 | |||
5912 | In addition to providing recipes under alternate names, the | ||
5913 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | ||
5914 | virtual target is a name that corresponds to some particular | ||
5915 | functionality (e.g. a Linux kernel). Recipes that provide the | ||
5916 | functionality in question list the virtual target in ``PROVIDES``. | ||
5917 | Recipes that depend on the functionality in question can include the | ||
5918 | virtual target in ``DEPENDS`` to leave the choice of provider open. | ||
5919 | |||
5920 | Conventionally, virtual targets have names on the form | ||
5921 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part | ||
5922 | of the name and has no syntactical significance. | ||
5923 | |||
5924 | The :term:`PREFERRED_PROVIDER` variable is | ||
5925 | used to select which particular recipe provides a virtual target. | ||
5926 | |||
5927 | .. note:: | ||
5928 | |||
5929 | A corresponding mechanism for virtual runtime dependencies | ||
5930 | (packages) exists. However, the mechanism does not depend on any | ||
5931 | special functionality beyond ordinary variable assignments. For | ||
5932 | example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of | ||
5933 | the component that manages the ``/dev`` directory. | ||
5934 | |||
5935 | Setting the "preferred provider" for runtime dependencies is as | ||
5936 | simple as using the following assignment in a configuration file: | ||
5937 | :: | ||
5938 | |||
5939 | VIRTUAL-RUNTIME_dev_manager = "udev" | ||
5940 | |||
5941 | |||
5942 | :term:`PRSERV_HOST` | ||
5943 | The network based :term:`PR` service host and port. | ||
5944 | |||
5945 | The ``conf/local.conf.sample.extended`` configuration file in the | ||
5946 | :term:`Source Directory` shows how the | ||
5947 | ``PRSERV_HOST`` variable is set: | ||
5948 | :: | ||
5949 | |||
5950 | PRSERV_HOST = "localhost:0" | ||
5951 | |||
5952 | You must | ||
5953 | set the variable if you want to automatically start a local :ref:`PR | ||
5954 | service <dev-manual/common-tasks:working with a pr service>`. You can | ||
5955 | set ``PRSERV_HOST`` to other values to use a remote PR service. | ||
5956 | |||
5957 | |||
5958 | :term:`PSEUDO_IGNORE_PATHS` | ||
5959 | A comma-separated (without spaces) list of path prefixes that should be ignored | ||
5960 | by pseudo when monitoring and recording file operations, in order to avoid | ||
5961 | problems with files being written to outside of the pseudo context and | ||
5962 | reduce pseudo's overhead. A path is ignored if it matches any prefix in the list | ||
5963 | and can include partial directory (or file) names. | ||
5964 | |||
5965 | |||
5966 | :term:`PTEST_ENABLED` | ||
5967 | Specifies whether or not :ref:`Package | ||
5968 | Test <dev-manual/common-tasks:testing packages with ptest>` (ptest) | ||
5969 | functionality is enabled when building a recipe. You should not set | ||
5970 | this variable directly. Enabling and disabling building Package Tests | ||
5971 | at build time should be done by adding "ptest" to (or removing it | ||
5972 | from) :term:`DISTRO_FEATURES`. | ||
5973 | |||
5974 | :term:`PV` | ||
5975 | The version of the recipe. The version is normally extracted from the | ||
5976 | recipe filename. For example, if the recipe is named | ||
5977 | ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". | ||
5978 | ``PV`` is generally not overridden within a recipe unless it is | ||
5979 | building an unstable (i.e. development) version from a source code | ||
5980 | repository (e.g. Git or Subversion). | ||
5981 | |||
5982 | ``PV`` is the default value of the :term:`PKGV` variable. | ||
5983 | |||
5984 | :term:`PYTHON_ABI` | ||
5985 | When used by recipes that inherit the | ||
5986 | :ref:`distutils3 <ref-classes-distutils3>`, | ||
5987 | :ref:`setuptools3 <ref-classes-setuptools3>`, | ||
5988 | :ref:`distutils <ref-classes-distutils>`, or | ||
5989 | :ref:`setuptools <ref-classes-setuptools>` classes, denotes the | ||
5990 | Application Binary Interface (ABI) currently in use for Python. By | ||
5991 | default, the ABI is "m". You do not have to set this variable as the | ||
5992 | OpenEmbedded build system sets it for you. | ||
5993 | |||
5994 | The OpenEmbedded build system uses the ABI to construct directory | ||
5995 | names used when installing the Python headers and libraries in | ||
5996 | sysroot (e.g. ``.../python3.3m/...``). | ||
5997 | |||
5998 | Recipes that inherit the ``distutils`` class during cross-builds also | ||
5999 | use this variable to locate the headers and libraries of the | ||
6000 | appropriate Python that the extension is targeting. | ||
6001 | |||
6002 | :term:`PYTHON_PN` | ||
6003 | When used by recipes that inherit the | ||
6004 | `distutils3 <ref-classes-distutils3>`, | ||
6005 | :ref:`setuptools3 <ref-classes-setuptools3>`, | ||
6006 | :ref:`distutils <ref-classes-distutils>`, or | ||
6007 | :ref:`setuptools <ref-classes-setuptools>` classes, specifies the | ||
6008 | major Python version being built. For Python 3.x, ``PYTHON_PN`` would | ||
6009 | be "python3". You do not have to set this variable as the | ||
6010 | OpenEmbedded build system automatically sets it for you. | ||
6011 | |||
6012 | The variable allows recipes to use common infrastructure such as the | ||
6013 | following: | ||
6014 | :: | ||
6015 | |||
6016 | DEPENDS += "${PYTHON_PN}-native" | ||
6017 | |||
6018 | In the previous example, | ||
6019 | the version of the dependency is ``PYTHON_PN``. | ||
6020 | |||
6021 | :term:`RANLIB` | ||
6022 | The minimal command and arguments to run ``ranlib``. | ||
6023 | |||
6024 | :term:`RCONFLICTS` | ||
6025 | The list of packages that conflict with packages. Note that packages | ||
6026 | will not be installed if conflicting packages are not first removed. | ||
6027 | |||
6028 | Like all package-controlling variables, you must always use them in | ||
6029 | conjunction with a package name override. Here is an example: | ||
6030 | :: | ||
6031 | |||
6032 | RCONFLICTS_${PN} = "another_conflicting_package_name" | ||
6033 | |||
6034 | BitBake, which the OpenEmbedded build system uses, supports | ||
6035 | specifying versioned dependencies. Although the syntax varies | ||
6036 | depending on the packaging format, BitBake hides these differences | ||
6037 | from you. Here is the general syntax to specify versions with the | ||
6038 | ``RCONFLICTS`` variable: | ||
6039 | :: | ||
6040 | |||
6041 | RCONFLICTS_${PN} = "package (operator version)" | ||
6042 | |||
6043 | For ``operator``, you can specify the following: | ||
6044 | |||
6045 | - = | ||
6046 | - < | ||
6047 | - > | ||
6048 | - <= | ||
6049 | - >= | ||
6050 | |||
6051 | For example, the following sets up a dependency on version 1.2 or | ||
6052 | greater of the package ``foo``: | ||
6053 | :: | ||
6054 | |||
6055 | RCONFLICTS_${PN} = "foo (>= 1.2)" | ||
6056 | |||
6057 | :term:`RDEPENDS` | ||
6058 | Lists runtime dependencies of a package. These dependencies are other | ||
6059 | packages that must be installed in order for the package to function | ||
6060 | correctly. As an example, the following assignment declares that the | ||
6061 | package ``foo`` needs the packages ``bar`` and ``baz`` to be | ||
6062 | installed: | ||
6063 | :: | ||
6064 | |||
6065 | RDEPENDS_foo = "bar baz" | ||
6066 | |||
6067 | The most common types of package | ||
6068 | runtime dependencies are automatically detected and added. Therefore, | ||
6069 | most recipes do not need to set ``RDEPENDS``. For more information, | ||
6070 | see the | ||
6071 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | ||
6072 | section in the Yocto Project Overview and Concepts Manual. | ||
6073 | |||
6074 | The practical effect of the above ``RDEPENDS`` assignment is that | ||
6075 | ``bar`` and ``baz`` will be declared as dependencies inside the | ||
6076 | package ``foo`` when it is written out by one of the | ||
6077 | :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks. | ||
6078 | Exactly how this is done depends on which package format is used, | ||
6079 | which is determined by | ||
6080 | :term:`PACKAGE_CLASSES`. When the | ||
6081 | corresponding package manager installs the package, it will know to | ||
6082 | also install the packages on which it depends. | ||
6083 | |||
6084 | To ensure that the packages ``bar`` and ``baz`` get built, the | ||
6085 | previous ``RDEPENDS`` assignment also causes a task dependency to be | ||
6086 | added. This dependency is from the recipe's | ||
6087 | :ref:`ref-tasks-build` (not to be confused with | ||
6088 | :ref:`ref-tasks-compile`) task to the | ||
6089 | ``do_package_write_*`` task of the recipes that build ``bar`` and | ||
6090 | ``baz``. | ||
6091 | |||
6092 | The names of the packages you list within ``RDEPENDS`` must be the | ||
6093 | names of other packages - they cannot be recipe names. Although | ||
6094 | package names and recipe names usually match, the important point | ||
6095 | here is that you are providing package names within the ``RDEPENDS`` | ||
6096 | variable. For an example of the default list of packages created from | ||
6097 | a recipe, see the :term:`PACKAGES` variable. | ||
6098 | |||
6099 | Because the ``RDEPENDS`` variable applies to packages being built, | ||
6100 | you should always use the variable in a form with an attached package | ||
6101 | name (remember that a single recipe can build multiple packages). For | ||
6102 | example, suppose you are building a development package that depends | ||
6103 | on the ``perl`` package. In this case, you would use the following | ||
6104 | ``RDEPENDS`` statement: | ||
6105 | :: | ||
6106 | |||
6107 | RDEPENDS_${PN}-dev += "perl" | ||
6108 | |||
6109 | In the example, | ||
6110 | the development package depends on the ``perl`` package. Thus, the | ||
6111 | ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of | ||
6112 | the variable. | ||
6113 | |||
6114 | .. note:: | ||
6115 | |||
6116 | ``RDEPENDS_${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` | ||
6117 | by default. This default is set in the BitBake configuration file | ||
6118 | (``meta/conf/bitbake.conf``). Be careful not to accidentally remove | ||
6119 | ``${PN}`` when modifying ``RDEPENDS_${PN}-dev``. Use the "+=" operator | ||
6120 | rather than the "=" operator. | ||
6121 | |||
6122 | The package names you use with ``RDEPENDS`` must appear as they would | ||
6123 | in the ``PACKAGES`` variable. The :term:`PKG` variable | ||
6124 | allows a different name to be used for the final package (e.g. the | ||
6125 | :ref:`debian <ref-classes-debian>` class uses this to rename | ||
6126 | packages), but this final package name cannot be used with | ||
6127 | ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be | ||
6128 | independent of the package format used. | ||
6129 | |||
6130 | BitBake, which the OpenEmbedded build system uses, supports | ||
6131 | specifying versioned dependencies. Although the syntax varies | ||
6132 | depending on the packaging format, BitBake hides these differences | ||
6133 | from you. Here is the general syntax to specify versions with the | ||
6134 | ``RDEPENDS`` variable: | ||
6135 | :: | ||
6136 | |||
6137 | RDEPENDS_${PN} = "package (operator version)" | ||
6138 | |||
6139 | For ``operator``, you can specify the following: | ||
6140 | |||
6141 | - = | ||
6142 | - < | ||
6143 | - > | ||
6144 | - <= | ||
6145 | - >= | ||
6146 | |||
6147 | For version, provide the version number. | ||
6148 | |||
6149 | .. note:: | ||
6150 | |||
6151 | You can use ``EXTENDPKGV`` to provide a full package version | ||
6152 | specification. | ||
6153 | |||
6154 | For example, the following sets up a dependency on version 1.2 or | ||
6155 | greater of the package ``foo``: | ||
6156 | :: | ||
6157 | |||
6158 | RDEPENDS_${PN} = "foo (>= 1.2)" | ||
6159 | |||
6160 | For information on build-time dependencies, see the | ||
6161 | :term:`DEPENDS` variable. You can also see the | ||
6162 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | ||
6163 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | ||
6164 | BitBake User Manual for additional information on tasks and | ||
6165 | dependencies. | ||
6166 | |||
6167 | :term:`REQUIRED_DISTRO_FEATURES` | ||
6168 | When inheriting the | ||
6169 | :ref:`features_check <ref-classes-features_check>` | ||
6170 | class, this variable identifies distribution features that must exist | ||
6171 | in the current configuration in order for the OpenEmbedded build | ||
6172 | system to build the recipe. In other words, if the | ||
6173 | ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not | ||
6174 | appear in ``DISTRO_FEATURES`` within the current configuration, then | ||
6175 | the recipe will be skipped, and if the build system attempts to build | ||
6176 | the recipe then an error will be triggered. | ||
6177 | |||
6178 | :term:`RM_WORK_EXCLUDE` | ||
6179 | With ``rm_work`` enabled, this variable specifies a list of recipes | ||
6180 | whose work directories should not be removed. See the | ||
6181 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more | ||
6182 | details. | ||
6183 | |||
6184 | :term:`ROOT_HOME` | ||
6185 | Defines the root home directory. By default, this directory is set as | ||
6186 | follows in the BitBake configuration file: | ||
6187 | :: | ||
6188 | |||
6189 | ROOT_HOME ??= "/home/root" | ||
6190 | |||
6191 | .. note:: | ||
6192 | |||
6193 | This default value is likely used because some embedded solutions | ||
6194 | prefer to have a read-only root filesystem and prefer to keep | ||
6195 | writeable data in one place. | ||
6196 | |||
6197 | You can override the default by setting the variable in any layer or | ||
6198 | in the ``local.conf`` file. Because the default is set using a "weak" | ||
6199 | assignment (i.e. "??="), you can use either of the following forms to | ||
6200 | define your override: | ||
6201 | :: | ||
6202 | |||
6203 | ROOT_HOME = "/root" | ||
6204 | ROOT_HOME ?= "/root" | ||
6205 | |||
6206 | These | ||
6207 | override examples use ``/root``, which is probably the most commonly | ||
6208 | used override. | ||
6209 | |||
6210 | :term:`ROOTFS` | ||
6211 | Indicates a filesystem image to include as the root filesystem. | ||
6212 | |||
6213 | The ``ROOTFS`` variable is an optional variable used with the | ||
6214 | :ref:`image-live <ref-classes-image-live>` class. | ||
6215 | |||
6216 | :term:`ROOTFS_POSTINSTALL_COMMAND` | ||
6217 | Specifies a list of functions to call after the OpenEmbedded build | ||
6218 | system has installed packages. You can specify functions separated by | ||
6219 | semicolons: | ||
6220 | :: | ||
6221 | |||
6222 | ROOTFS_POSTINSTALL_COMMAND += "function; ... " | ||
6223 | |||
6224 | If you need to pass the root filesystem path to a command within a | ||
6225 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6226 | directory that becomes the root filesystem image. See the | ||
6227 | :term:`IMAGE_ROOTFS` variable for more | ||
6228 | information. | ||
6229 | |||
6230 | :term:`ROOTFS_POSTPROCESS_COMMAND` | ||
6231 | Specifies a list of functions to call once the OpenEmbedded build | ||
6232 | system has created the root filesystem. You can specify functions | ||
6233 | separated by semicolons: | ||
6234 | :: | ||
6235 | |||
6236 | ROOTFS_POSTPROCESS_COMMAND += "function; ... " | ||
6237 | |||
6238 | If you need to pass the root filesystem path to a command within a | ||
6239 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6240 | directory that becomes the root filesystem image. See the | ||
6241 | :term:`IMAGE_ROOTFS` variable for more | ||
6242 | information. | ||
6243 | |||
6244 | :term:`ROOTFS_POSTUNINSTALL_COMMAND` | ||
6245 | Specifies a list of functions to call after the OpenEmbedded build | ||
6246 | system has removed unnecessary packages. When runtime package | ||
6247 | management is disabled in the image, several packages are removed | ||
6248 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. | ||
6249 | You can specify functions separated by semicolons: | ||
6250 | :: | ||
6251 | |||
6252 | ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " | ||
6253 | |||
6254 | If you need to pass the root filesystem path to a command within a | ||
6255 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6256 | directory that becomes the root filesystem image. See the | ||
6257 | :term:`IMAGE_ROOTFS` variable for more | ||
6258 | information. | ||
6259 | |||
6260 | :term:`ROOTFS_PREPROCESS_COMMAND` | ||
6261 | Specifies a list of functions to call before the OpenEmbedded build | ||
6262 | system has created the root filesystem. You can specify functions | ||
6263 | separated by semicolons: | ||
6264 | :: | ||
6265 | |||
6266 | ROOTFS_PREPROCESS_COMMAND += "function; ... " | ||
6267 | |||
6268 | If you need to pass the root filesystem path to a command within a | ||
6269 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | ||
6270 | directory that becomes the root filesystem image. See the | ||
6271 | :term:`IMAGE_ROOTFS` variable for more | ||
6272 | information. | ||
6273 | |||
6274 | :term:`RPROVIDES` | ||
6275 | A list of package name aliases that a package also provides. These | ||
6276 | aliases are useful for satisfying runtime dependencies of other | ||
6277 | packages both during the build and on the target (as specified by | ||
6278 | ``RDEPENDS``). | ||
6279 | |||
6280 | .. note:: | ||
6281 | |||
6282 | A package's own name is implicitly already in its ``RPROVIDES`` list. | ||
6283 | |||
6284 | As with all package-controlling variables, you must always use the | ||
6285 | variable in conjunction with a package name override. Here is an | ||
6286 | example: | ||
6287 | :: | ||
6288 | |||
6289 | RPROVIDES_${PN} = "widget-abi-2" | ||
6290 | |||
6291 | :term:`RRECOMMENDS` | ||
6292 | A list of packages that extends the usability of a package being | ||
6293 | built. The package being built does not depend on this list of | ||
6294 | packages in order to successfully build, but rather uses them for | ||
6295 | extended usability. To specify runtime dependencies for packages, see | ||
6296 | the ``RDEPENDS`` variable. | ||
6297 | |||
6298 | The package manager will automatically install the ``RRECOMMENDS`` | ||
6299 | list of packages when installing the built package. However, you can | ||
6300 | prevent listed packages from being installed by using the | ||
6301 | :term:`BAD_RECOMMENDATIONS`, | ||
6302 | :term:`NO_RECOMMENDATIONS`, and | ||
6303 | :term:`PACKAGE_EXCLUDE` variables. | ||
6304 | |||
6305 | Packages specified in ``RRECOMMENDS`` need not actually be produced. | ||
6306 | However, a recipe must exist that provides each package, either | ||
6307 | through the :term:`PACKAGES` or | ||
6308 | :term:`PACKAGES_DYNAMIC` variables or the | ||
6309 | :term:`RPROVIDES` variable, or an error will occur | ||
6310 | during the build. If such a recipe does exist and the package is not | ||
6311 | produced, the build continues without error. | ||
6312 | |||
6313 | Because the ``RRECOMMENDS`` variable applies to packages being built, | ||
6314 | you should always attach an override to the variable to specify the | ||
6315 | particular package whose usability is being extended. For example, | ||
6316 | suppose you are building a development package that is extended to | ||
6317 | support wireless functionality. In this case, you would use the | ||
6318 | following: | ||
6319 | :: | ||
6320 | |||
6321 | RRECOMMENDS_${PN}-dev += "wireless_package_name" | ||
6322 | |||
6323 | In the | ||
6324 | example, the package name (``${PN}-dev``) must appear as it would in | ||
6325 | the ``PACKAGES`` namespace before any renaming of the output package | ||
6326 | by classes such as ``debian.bbclass``. | ||
6327 | |||
6328 | BitBake, which the OpenEmbedded build system uses, supports | ||
6329 | specifying versioned recommends. Although the syntax varies depending | ||
6330 | on the packaging format, BitBake hides these differences from you. | ||
6331 | Here is the general syntax to specify versions with the | ||
6332 | ``RRECOMMENDS`` variable: | ||
6333 | :: | ||
6334 | |||
6335 | RRECOMMENDS_${PN} = "package (operator version)" | ||
6336 | |||
6337 | For ``operator``, you can specify the following: | ||
6338 | |||
6339 | - = | ||
6340 | - < | ||
6341 | - > | ||
6342 | - <= | ||
6343 | - >= | ||
6344 | |||
6345 | For example, the following sets up a recommend on version 1.2 or | ||
6346 | greater of the package ``foo``: | ||
6347 | :: | ||
6348 | |||
6349 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | ||
6350 | |||
6351 | :term:`RREPLACES` | ||
6352 | A list of packages replaced by a package. The package manager uses | ||
6353 | this variable to determine which package should be installed to | ||
6354 | replace other package(s) during an upgrade. In order to also have the | ||
6355 | other package(s) removed at the same time, you must add the name of | ||
6356 | the other package to the ``RCONFLICTS`` variable. | ||
6357 | |||
6358 | As with all package-controlling variables, you must use this variable | ||
6359 | in conjunction with a package name override. Here is an example: | ||
6360 | :: | ||
6361 | |||
6362 | RREPLACES_${PN} = "other_package_being_replaced" | ||
6363 | |||
6364 | BitBake, which the OpenEmbedded build system uses, supports | ||
6365 | specifying versioned replacements. Although the syntax varies | ||
6366 | depending on the packaging format, BitBake hides these differences | ||
6367 | from you. Here is the general syntax to specify versions with the | ||
6368 | ``RREPLACES`` variable: | ||
6369 | :: | ||
6370 | |||
6371 | RREPLACES_${PN} = "package (operator version)" | ||
6372 | |||
6373 | For ``operator``, you can specify the following: | ||
6374 | |||
6375 | - = | ||
6376 | - < | ||
6377 | - > | ||
6378 | - <= | ||
6379 | - >= | ||
6380 | |||
6381 | For example, the following sets up a replacement using version 1.2 | ||
6382 | or greater of the package ``foo``: | ||
6383 | :: | ||
6384 | |||
6385 | RREPLACES_${PN} = "foo (>= 1.2)" | ||
6386 | |||
6387 | :term:`RSUGGESTS` | ||
6388 | A list of additional packages that you can suggest for installation | ||
6389 | by the package manager at the time a package is installed. Not all | ||
6390 | package managers support this functionality. | ||
6391 | |||
6392 | As with all package-controlling variables, you must always use this | ||
6393 | variable in conjunction with a package name override. Here is an | ||
6394 | example: | ||
6395 | :: | ||
6396 | |||
6397 | RSUGGESTS_${PN} = "useful_package another_package" | ||
6398 | |||
6399 | :term:`S` | ||
6400 | The location in the :term:`Build Directory` where | ||
6401 | unpacked recipe source code resides. By default, this directory is | ||
6402 | ``${``\ :term:`WORKDIR`\ ``}/${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``, | ||
6403 | where ``${BPN}`` is the base recipe name and ``${PV}`` is the recipe | ||
6404 | version. If the source tarball extracts the code to a directory named | ||
6405 | anything other than ``${BPN}-${PV}``, or if the source code is | ||
6406 | fetched from an SCM such as Git or Subversion, then you must set | ||
6407 | ``S`` in the recipe so that the OpenEmbedded build system knows where | ||
6408 | to find the unpacked source. | ||
6409 | |||
6410 | As an example, assume a :term:`Source Directory` | ||
6411 | top-level folder named ``poky`` and a default Build Directory at | ||
6412 | ``poky/build``. In this case, the work directory the build system | ||
6413 | uses to keep the unpacked recipe for ``db`` is the following: | ||
6414 | :: | ||
6415 | |||
6416 | poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 | ||
6417 | |||
6418 | The unpacked source code resides in the ``db-5.1.19`` folder. | ||
6419 | |||
6420 | This next example assumes a Git repository. By default, Git | ||
6421 | repositories are cloned to ``${WORKDIR}/git`` during | ||
6422 | :ref:`ref-tasks-fetch`. Since this path is different | ||
6423 | from the default value of ``S``, you must set it specifically so the | ||
6424 | source can be located: | ||
6425 | :: | ||
6426 | |||
6427 | SRC_URI = "git://path/to/repo.git" | ||
6428 | S = "${WORKDIR}/git" | ||
6429 | |||
6430 | :term:`SANITY_REQUIRED_UTILITIES` | ||
6431 | Specifies a list of command-line utilities that should be checked for | ||
6432 | during the initial sanity checking process when running BitBake. If | ||
6433 | any of the utilities are not installed on the build host, then | ||
6434 | BitBake immediately exits with an error. | ||
6435 | |||
6436 | :term:`SANITY_TESTED_DISTROS` | ||
6437 | A list of the host distribution identifiers that the build system has | ||
6438 | been tested against. Identifiers consist of the host distributor ID | ||
6439 | followed by the release, as reported by the ``lsb_release`` tool or | ||
6440 | as read from ``/etc/lsb-release``. Separate the list items with | ||
6441 | explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is | ||
6442 | not empty and the current value of | ||
6443 | :term:`NATIVELSBSTRING` does not appear in the | ||
6444 | list, then the build system reports a warning that indicates the | ||
6445 | current host distribution has not been tested as a build host. | ||
6446 | |||
6447 | :term:`SDK_ARCH` | ||
6448 | The target architecture for the SDK. Typically, you do not directly | ||
6449 | set this variable. Instead, use :term:`SDKMACHINE`. | ||
6450 | |||
6451 | :term:`SDK_DEPLOY` | ||
6452 | The directory set up and used by the | ||
6453 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which | ||
6454 | the SDK is deployed. The ``populate_sdk_base`` class defines | ||
6455 | ``SDK_DEPLOY`` as follows: | ||
6456 | :: | ||
6457 | |||
6458 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" | ||
6459 | |||
6460 | :term:`SDK_DIR` | ||
6461 | The parent directory used by the OpenEmbedded build system when | ||
6462 | creating SDK output. The | ||
6463 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines | ||
6464 | the variable as follows: | ||
6465 | :: | ||
6466 | |||
6467 | SDK_DIR = "${WORKDIR}/sdk" | ||
6468 | |||
6469 | .. note:: | ||
6470 | |||
6471 | The ``SDK_DIR`` directory is a temporary directory as it is part of | ||
6472 | ``WORKDIR``. The final output directory is :term:`SDK_DEPLOY`. | ||
6473 | |||
6474 | :term:`SDK_EXT_TYPE` | ||
6475 | Controls whether or not shared state artifacts are copied into the | ||
6476 | extensible SDK. The default value of "full" copies all of the | ||
6477 | required shared state artifacts into the extensible SDK. The value | ||
6478 | "minimal" leaves these artifacts out of the SDK. | ||
6479 | |||
6480 | .. note:: | ||
6481 | |||
6482 | If you set the variable to "minimal", you need to ensure | ||
6483 | :term:`SSTATE_MIRRORS` is set in the SDK's configuration to enable the | ||
6484 | artifacts to be fetched as needed. | ||
6485 | |||
6486 | :term:`SDK_HOST_MANIFEST` | ||
6487 | The manifest file for the host part of the SDK. This file lists all | ||
6488 | the installed packages that make up the host part of the SDK. The | ||
6489 | file contains package information on a line-per-package basis as | ||
6490 | follows: | ||
6491 | :: | ||
6492 | |||
6493 | packagename packagearch version | ||
6494 | |||
6495 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | ||
6496 | defines the manifest file as follows: | ||
6497 | :: | ||
6498 | |||
6499 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" | ||
6500 | |||
6501 | The location is derived using the :term:`SDK_DEPLOY` and | ||
6502 | :term:`TOOLCHAIN_OUTPUTNAME` variables. | ||
6503 | |||
6504 | :term:`SDK_INCLUDE_PKGDATA` | ||
6505 | When set to "1", specifies to include the packagedata for all recipes | ||
6506 | in the "world" target in the extensible SDK. Including this data | ||
6507 | allows the ``devtool search`` command to find these recipes in search | ||
6508 | results, as well as allows the ``devtool add`` command to map | ||
6509 | dependencies more effectively. | ||
6510 | |||
6511 | .. note:: | ||
6512 | |||
6513 | Enabling the ``SDK_INCLUDE_PKGDATA`` | ||
6514 | variable significantly increases build time because all of world | ||
6515 | needs to be built. Enabling the variable also slightly increases | ||
6516 | the size of the extensible SDK. | ||
6517 | |||
6518 | :term:`SDK_INCLUDE_TOOLCHAIN` | ||
6519 | When set to "1", specifies to include the toolchain in the extensible | ||
6520 | SDK. Including the toolchain is useful particularly when | ||
6521 | :term:`SDK_EXT_TYPE` is set to "minimal" to keep | ||
6522 | the SDK reasonably small but you still want to provide a usable | ||
6523 | toolchain. For example, suppose you want to use the toolchain from an | ||
6524 | IDE or from other tools and you do not want to perform additional | ||
6525 | steps to install the toolchain. | ||
6526 | |||
6527 | The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if | ||
6528 | ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if | ||
6529 | ``SDK_EXT_TYPE`` is set to "full". | ||
6530 | |||
6531 | :term:`SDK_INHERIT_BLACKLIST` | ||
6532 | A list of classes to remove from the :term:`INHERIT` | ||
6533 | value globally within the extensible SDK configuration. The | ||
6534 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the | ||
6535 | default value: | ||
6536 | :: | ||
6537 | |||
6538 | SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" | ||
6539 | |||
6540 | Some classes are not generally applicable within the extensible SDK | ||
6541 | context. You can use this variable to disable those classes. | ||
6542 | |||
6543 | For additional information on how to customize the extensible SDK's | ||
6544 | configuration, see the | ||
6545 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6546 | section in the Yocto Project Application Development and the | ||
6547 | Extensible Software Development Kit (eSDK) manual. | ||
6548 | |||
6549 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6550 | A list of variables not allowed through from the OpenEmbedded build | ||
6551 | system configuration into the extensible SDK configuration. Usually, | ||
6552 | these are variables that are specific to the machine on which the | ||
6553 | build system is running and thus would be potentially problematic | ||
6554 | within the extensible SDK. | ||
6555 | |||
6556 | By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the | ||
6557 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and | ||
6558 | excludes the following variables: | ||
6559 | |||
6560 | - :term:`CONF_VERSION` | ||
6561 | - :term:`BB_NUMBER_THREADS` | ||
6562 | - :term:`bitbake:BB_NUMBER_PARSE_THREADS` | ||
6563 | - :term:`PARALLEL_MAKE` | ||
6564 | - :term:`PRSERV_HOST` | ||
6565 | - :term:`SSTATE_MIRRORS` :term:`DL_DIR` | ||
6566 | - :term:`SSTATE_DIR` :term:`TMPDIR` | ||
6567 | - :term:`BB_SERVER_TIMEOUT` | ||
6568 | |||
6569 | For additional information on how to customize the extensible SDK's | ||
6570 | configuration, see the | ||
6571 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6572 | section in the Yocto Project Application Development and the | ||
6573 | Extensible Software Development Kit (eSDK) manual. | ||
6574 | |||
6575 | :term:`SDK_LOCAL_CONF_WHITELIST` | ||
6576 | A list of variables allowed through from the OpenEmbedded build | ||
6577 | system configuration into the extensible SDK configuration. By | ||
6578 | default, the list of variables is empty and is set in the | ||
6579 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. | ||
6580 | |||
6581 | This list overrides the variables specified using the | ||
6582 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6583 | variable as well as any variables identified by automatic | ||
6584 | blacklisting due to the "/" character being found at the start of the | ||
6585 | value, which is usually indicative of being a path and thus might not | ||
6586 | be valid on the system where the SDK is installed. | ||
6587 | |||
6588 | For additional information on how to customize the extensible SDK's | ||
6589 | configuration, see the | ||
6590 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6591 | section in the Yocto Project Application Development and the | ||
6592 | Extensible Software Development Kit (eSDK) manual. | ||
6593 | |||
6594 | :term:`SDK_NAME` | ||
6595 | The base name for SDK output files. The name is derived from the | ||
6596 | :term:`DISTRO`, :term:`TCLIBC`, | ||
6597 | :term:`SDK_ARCH`, | ||
6598 | :term:`IMAGE_BASENAME`, and | ||
6599 | :term:`TUNE_PKGARCH` variables: | ||
6600 | :: | ||
6601 | |||
6602 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" | ||
6603 | |||
6604 | :term:`SDK_OS` | ||
6605 | Specifies the operating system for which the SDK will be built. The | ||
6606 | default value is the value of :term:`BUILD_OS`. | ||
6607 | |||
6608 | :term:`SDK_OUTPUT` | ||
6609 | The location used by the OpenEmbedded build system when creating SDK | ||
6610 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | ||
6611 | class defines the variable as follows: | ||
6612 | :: | ||
6613 | |||
6614 | SDK_DIR = "${WORKDIR}/sdk" | ||
6615 | SDK_OUTPUT = "${SDK_DIR}/image" | ||
6616 | SDK_DEPLOY = "${DEPLOY_DIR}/sdk" | ||
6617 | |||
6618 | .. note:: | ||
6619 | |||
6620 | The ``SDK_OUTPUT`` directory is a temporary directory as it is part of | ||
6621 | :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is | ||
6622 | :term:`SDK_DEPLOY`. | ||
6623 | |||
6624 | :term:`SDK_PACKAGE_ARCHS` | ||
6625 | Specifies a list of architectures compatible with the SDK machine. | ||
6626 | This variable is set automatically and should not normally be | ||
6627 | hand-edited. Entries are separated using spaces and listed in order | ||
6628 | of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any | ||
6629 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". | ||
6630 | |||
6631 | :term:`SDK_POSTPROCESS_COMMAND` | ||
6632 | Specifies a list of functions to call once the OpenEmbedded build | ||
6633 | system creates the SDK. You can specify functions separated by | ||
6634 | semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " | ||
6635 | |||
6636 | If you need to pass an SDK path to a command within a function, you | ||
6637 | can use ``${SDK_DIR}``, which points to the parent directory used by | ||
6638 | the OpenEmbedded build system when creating SDK output. See the | ||
6639 | :term:`SDK_DIR` variable for more information. | ||
6640 | |||
6641 | :term:`SDK_PREFIX` | ||
6642 | The toolchain binary prefix used for ``nativesdk`` recipes. The | ||
6643 | OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the | ||
6644 | :term:`TARGET_PREFIX` when building | ||
6645 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". | ||
6646 | |||
6647 | :term:`SDK_RECRDEP_TASKS` | ||
6648 | A list of shared state tasks added to the extensible SDK. By default, | ||
6649 | the following tasks are added: | ||
6650 | |||
6651 | - do_populate_lic | ||
6652 | - do_package_qa | ||
6653 | - do_populate_sysroot | ||
6654 | - do_deploy | ||
6655 | |||
6656 | Despite the default value of "" for the | ||
6657 | ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added | ||
6658 | to the SDK. To specify tasks beyond these four, you need to use the | ||
6659 | ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional | ||
6660 | tasks that are needed in order to build | ||
6661 | :term:`SDK_TARGETS`). | ||
6662 | |||
6663 | :term:`SDK_SYS` | ||
6664 | Specifies the system, including the architecture and the operating | ||
6665 | system, for which the SDK will be built. | ||
6666 | |||
6667 | The OpenEmbedded build system automatically sets this variable based | ||
6668 | on :term:`SDK_ARCH`, | ||
6669 | :term:`SDK_VENDOR`, and | ||
6670 | :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` | ||
6671 | variable yourself. | ||
6672 | |||
6673 | :term:`SDK_TARGET_MANIFEST` | ||
6674 | The manifest file for the target part of the SDK. This file lists all | ||
6675 | the installed packages that make up the target part of the SDK. The | ||
6676 | file contains package information on a line-per-package basis as | ||
6677 | follows: | ||
6678 | :: | ||
6679 | |||
6680 | packagename packagearch version | ||
6681 | |||
6682 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | ||
6683 | defines the manifest file as follows: | ||
6684 | :: | ||
6685 | |||
6686 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" | ||
6687 | |||
6688 | The location is derived using the :term:`SDK_DEPLOY` and | ||
6689 | :term:`TOOLCHAIN_OUTPUTNAME` variables. | ||
6690 | |||
6691 | :term:`SDK_TARGETS` | ||
6692 | A list of targets to install from shared state as part of the | ||
6693 | standard or extensible SDK installation. The default value is "${PN}" | ||
6694 | (i.e. the image from which the SDK is built). | ||
6695 | |||
6696 | The ``SDK_TARGETS`` variable is an internal variable and typically | ||
6697 | would not be changed. | ||
6698 | |||
6699 | :term:`SDK_TITLE` | ||
6700 | The title to be printed when running the SDK installer. By default, | ||
6701 | this title is based on the :term:`DISTRO_NAME` or | ||
6702 | :term:`DISTRO` variable and is set in the | ||
6703 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | ||
6704 | follows: | ||
6705 | :: | ||
6706 | |||
6707 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" | ||
6708 | |||
6709 | For the default distribution "poky", | ||
6710 | ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". | ||
6711 | |||
6712 | For information on how to change this default title, see the | ||
6713 | ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" | ||
6714 | section in the Yocto Project Application Development and the | ||
6715 | Extensible Software Development Kit (eSDK) manual. | ||
6716 | |||
6717 | :term:`SDK_UPDATE_URL` | ||
6718 | An optional URL for an update server for the extensible SDK. If set, | ||
6719 | the value is used as the default update server when running | ||
6720 | ``devtool sdk-update`` within the extensible SDK. | ||
6721 | |||
6722 | :term:`SDK_VENDOR` | ||
6723 | Specifies the name of the SDK vendor. | ||
6724 | |||
6725 | :term:`SDK_VERSION` | ||
6726 | Specifies the version of the SDK. The distribution configuration file | ||
6727 | (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the | ||
6728 | ``SDK_VERSION`` as follows: | ||
6729 | :: | ||
6730 | |||
6731 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" | ||
6732 | |||
6733 | For additional information, see the | ||
6734 | :term:`DISTRO_VERSION` and | ||
6735 | :term:`DATE` variables. | ||
6736 | |||
6737 | :term:`SDKEXTPATH` | ||
6738 | The default installation directory for the Extensible SDK. By | ||
6739 | default, this directory is based on the :term:`DISTRO` | ||
6740 | variable and is set in the | ||
6741 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | ||
6742 | follows: | ||
6743 | :: | ||
6744 | |||
6745 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" | ||
6746 | |||
6747 | For the | ||
6748 | default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". | ||
6749 | |||
6750 | For information on how to change this default directory, see the | ||
6751 | ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" | ||
6752 | section in the Yocto Project Application Development and the | ||
6753 | Extensible Software Development Kit (eSDK) manual. | ||
6754 | |||
6755 | :term:`SDKIMAGE_FEATURES` | ||
6756 | Equivalent to ``IMAGE_FEATURES``. However, this variable applies to | ||
6757 | the SDK generated from an image using the following command: | ||
6758 | :: | ||
6759 | |||
6760 | $ bitbake -c populate_sdk imagename | ||
6761 | |||
6762 | :term:`SDKMACHINE` | ||
6763 | The machine for which the SDK is built. In other words, the SDK is | ||
6764 | built such that it runs on the target you specify with the | ||
6765 | ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` | ||
6766 | file under ``conf/machine-sdk/``. | ||
6767 | |||
6768 | You can use "i686" and "x86_64" as possible values for this variable. | ||
6769 | The variable defaults to "i686" and is set in the local.conf file in | ||
6770 | the Build Directory. | ||
6771 | :: | ||
6772 | |||
6773 | SDKMACHINE ?= "i686" | ||
6774 | |||
6775 | .. note:: | ||
6776 | |||
6777 | You cannot set the ``SDKMACHINE`` | ||
6778 | variable in your distribution configuration file. If you do, the | ||
6779 | configuration will not take affect. | ||
6780 | |||
6781 | :term:`SDKPATH` | ||
6782 | Defines the path offered to the user for installation of the SDK that | ||
6783 | is generated by the OpenEmbedded build system. The path appears as | ||
6784 | the default location for installing the SDK when you run the SDK's | ||
6785 | installation script. You can override the offered path when you run | ||
6786 | the script. | ||
6787 | |||
6788 | :term:`SDKTARGETSYSROOT` | ||
6789 | The full path to the sysroot used for cross-compilation within an SDK | ||
6790 | as it will be when installed into the default | ||
6791 | :term:`SDKPATH`. | ||
6792 | |||
6793 | :term:`SECTION` | ||
6794 | The section in which packages should be categorized. Package | ||
6795 | management utilities can make use of this variable. | ||
6796 | |||
6797 | :term:`SELECTED_OPTIMIZATION` | ||
6798 | Specifies the optimization flags passed to the C compiler when | ||
6799 | building for the target. The flags are passed through the default | ||
6800 | value of the :term:`TARGET_CFLAGS` variable. | ||
6801 | |||
6802 | The ``SELECTED_OPTIMIZATION`` variable takes the value of | ||
6803 | ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the | ||
6804 | case, the value of ``DEBUG_OPTIMIZATION`` is used. | ||
6805 | |||
6806 | :term:`SERIAL_CONSOLE` | ||
6807 | Defines a serial console (TTY) to enable using | ||
6808 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6809 | value that specifies the baud rate followed by the TTY device name | ||
6810 | separated by a space. You cannot specify more than one TTY device: | ||
6811 | :: | ||
6812 | |||
6813 | SERIAL_CONSOLE = "115200 ttyS0" | ||
6814 | |||
6815 | .. note:: | ||
6816 | |||
6817 | The ``SERIAL_CONSOLE`` variable is deprecated. Please use the | ||
6818 | :term:`SERIAL_CONSOLES` variable. | ||
6819 | |||
6820 | :term:`SERIAL_CONSOLES` | ||
6821 | Defines a serial console (TTY) to enable using | ||
6822 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6823 | value that specifies the baud rate followed by the TTY device name | ||
6824 | separated by a semicolon. Use spaces to separate multiple devices: | ||
6825 | :: | ||
6826 | |||
6827 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" | ||
6828 | |||
6829 | :term:`SERIAL_CONSOLES_CHECK` | ||
6830 | Specifies serial consoles, which must be listed in | ||
6831 | :term:`SERIAL_CONSOLES`, to check against | ||
6832 | ``/proc/console`` before enabling them using getty. This variable | ||
6833 | allows aliasing in the format: <device>:<alias>. If a device was | ||
6834 | listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in | ||
6835 | ``/proc/console``, you would do the following: :: | ||
6836 | |||
6837 | SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" | ||
6838 | |||
6839 | This variable is currently only supported with SysVinit (i.e. not | ||
6840 | with systemd). | ||
6841 | |||
6842 | :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` | ||
6843 | A list of recipe dependencies that should not be used to determine | ||
6844 | signatures of tasks from one recipe when they depend on tasks from | ||
6845 | another recipe. For example: :: | ||
6846 | |||
6847 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" | ||
6848 | |||
6849 | In the previous example, ``intone`` depends on ``mplayer2``. | ||
6850 | |||
6851 | You can use the special token ``"*"`` on the left-hand side of the | ||
6852 | dependency to match all recipes except the one on the right-hand | ||
6853 | side. Here is an example: :: | ||
6854 | |||
6855 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" | ||
6856 | |||
6857 | In the previous example, all recipes except ``quilt-native`` ignore | ||
6858 | task signatures from the ``quilt-native`` recipe when determining | ||
6859 | their task signatures. | ||
6860 | |||
6861 | Use of this variable is one mechanism to remove dependencies that | ||
6862 | affect task signatures and thus force rebuilds when a recipe changes. | ||
6863 | |||
6864 | .. note:: | ||
6865 | |||
6866 | If you add an inappropriate dependency for a recipe relationship, | ||
6867 | the software might break during runtime if the interface of the | ||
6868 | second recipe was changed after the first recipe had been built. | ||
6869 | |||
6870 | :term:`SIGGEN_EXCLUDERECIPES_ABISAFE` | ||
6871 | A list of recipes that are completely stable and will never change. | ||
6872 | The ABI for the recipes in the list are presented by output from the | ||
6873 | tasks run to build the recipe. Use of this variable is one way to | ||
6874 | remove dependencies from one recipe on another that affect task | ||
6875 | signatures and thus force rebuilds when the recipe changes. | ||
6876 | |||
6877 | .. note:: | ||
6878 | |||
6879 | If you add an inappropriate variable to this list, the software | ||
6880 | might break at runtime if the interface of the recipe was changed | ||
6881 | after the other had been built. | ||
6882 | |||
6883 | :term:`SITEINFO_BITS` | ||
6884 | Specifies the number of bits for the target system CPU. The value | ||
6885 | should be either "32" or "64". | ||
6886 | |||
6887 | :term:`SITEINFO_ENDIANNESS` | ||
6888 | Specifies the endian byte order of the target system. The value | ||
6889 | should be either "le" for little-endian or "be" for big-endian. | ||
6890 | |||
6891 | :term:`SKIP_FILEDEPS` | ||
6892 | Enables removal of all files from the "Provides" section of an RPM | ||
6893 | package. Removal of these files is required for packages containing | ||
6894 | prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. | ||
6895 | |||
6896 | To enable file removal, set the variable to "1" in your | ||
6897 | ``conf/local.conf`` configuration file in your: | ||
6898 | :term:`Build Directory`. | ||
6899 | :: | ||
6900 | |||
6901 | SKIP_FILEDEPS = "1" | ||
6902 | |||
6903 | :term:`SOC_FAMILY` | ||
6904 | Groups together machines based upon the same family of SOC (System On | ||
6905 | Chip). You typically set this variable in a common ``.inc`` file that | ||
6906 | you include in the configuration files of all the machines. | ||
6907 | |||
6908 | .. note:: | ||
6909 | |||
6910 | You must include ``conf/machine/include/soc-family.inc`` for this | ||
6911 | variable to appear in :term:`MACHINEOVERRIDES`. | ||
6912 | |||
6913 | :term:`SOLIBS` | ||
6914 | Defines the suffix for shared libraries used on the target platform. | ||
6915 | By default, this suffix is ".so.*" for all Linux-based systems and is | ||
6916 | defined in the ``meta/conf/bitbake.conf`` configuration file. | ||
6917 | |||
6918 | You will see this variable referenced in the default values of | ||
6919 | ``FILES_${PN}``. | ||
6920 | |||
6921 | :term:`SOLIBSDEV` | ||
6922 | Defines the suffix for the development symbolic link (symlink) for | ||
6923 | shared libraries on the target platform. By default, this suffix is | ||
6924 | ".so" for Linux-based systems and is defined in the | ||
6925 | ``meta/conf/bitbake.conf`` configuration file. | ||
6926 | |||
6927 | You will see this variable referenced in the default values of | ||
6928 | ``FILES_${PN}-dev``. | ||
6929 | |||
6930 | :term:`SOURCE_MIRROR_FETCH` | ||
6931 | When you are fetching files to create a mirror of sources (i.e. | ||
6932 | creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in | ||
6933 | your ``local.conf`` configuration file ensures the source for all | ||
6934 | recipes are fetched regardless of whether or not a recipe is | ||
6935 | compatible with the configuration. A recipe is considered | ||
6936 | incompatible with the currently configured machine when either or | ||
6937 | both the :term:`COMPATIBLE_MACHINE` | ||
6938 | variable and :term:`COMPATIBLE_HOST` variables | ||
6939 | specify compatibility with a machine other than that of the current | ||
6940 | machine or host. | ||
6941 | |||
6942 | .. note:: | ||
6943 | |||
6944 | Do not set the ``SOURCE_MIRROR_FETCH`` | ||
6945 | variable unless you are creating a source mirror. In other words, | ||
6946 | do not set the variable during a normal build. | ||
6947 | |||
6948 | :term:`SOURCE_MIRROR_URL` | ||
6949 | Defines your own :term:`PREMIRRORS` from which to | ||
6950 | first fetch source before attempting to fetch from the upstream | ||
6951 | specified in :term:`SRC_URI`. | ||
6952 | |||
6953 | To use this variable, you must globally inherit the | ||
6954 | :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide | ||
6955 | the URL to your mirrors. Here is the general syntax: | ||
6956 | :: | ||
6957 | |||
6958 | INHERIT += "own-mirrors" | ||
6959 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" | ||
6960 | |||
6961 | .. note:: | ||
6962 | |||
6963 | You can specify only a single URL in ``SOURCE_MIRROR_URL``. | ||
6964 | |||
6965 | :term:`SPDXLICENSEMAP` | ||
6966 | Maps commonly used license names to their SPDX counterparts found in | ||
6967 | ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` | ||
6968 | mappings, see the ``meta/conf/licenses.conf`` file. | ||
6969 | |||
6970 | For additional information, see the :term:`LICENSE` | ||
6971 | variable. | ||
6972 | |||
6973 | :term:`SPECIAL_PKGSUFFIX` | ||
6974 | A list of prefixes for :term:`PN` used by the OpenEmbedded | ||
6975 | build system to create variants of recipes or packages. The list | ||
6976 | specifies the prefixes to strip off during certain circumstances such | ||
6977 | as the generation of the :term:`BPN` variable. | ||
6978 | |||
6979 | :term:`SPL_BINARY` | ||
6980 | The file type for the Secondary Program Loader (SPL). Some devices | ||
6981 | use an SPL from which to boot (e.g. the BeagleBone development | ||
6982 | board). For such cases, you can declare the file type of the SPL | ||
6983 | binary in the ``u-boot.inc`` include file, which is used in the | ||
6984 | U-Boot recipe. | ||
6985 | |||
6986 | The SPL file type is set to "null" by default in the ``u-boot.inc`` | ||
6987 | file as follows: | ||
6988 | :: | ||
6989 | |||
6990 | # Some versions of u-boot build an SPL (Second Program Loader) image that | ||
6991 | # should be packaged along with the u-boot binary as well as placed in the | ||
6992 | # deploy directory. For those versions they can set the following variables | ||
6993 | # to allow packaging the SPL. | ||
6994 | SPL_BINARY ?= "" | ||
6995 | SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}" | ||
6996 | SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" | ||
6997 | SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" | ||
6998 | |||
6999 | The ``SPL_BINARY`` variable helps form | ||
7000 | various ``SPL_*`` variables used by the OpenEmbedded build system. | ||
7001 | |||
7002 | See the BeagleBone machine configuration example in the | ||
7003 | ":ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" | ||
7004 | section in the Yocto Project Board Support Package Developer's Guide | ||
7005 | for additional information. | ||
7006 | |||
7007 | :term:`SRC_URI` | ||
7008 | The list of source files - local or remote. This variable tells the | ||
7009 | OpenEmbedded build system which bits to pull in for the build and how | ||
7010 | to pull them in. For example, if the recipe or append file only needs | ||
7011 | to fetch a tarball from the Internet, the recipe or append file uses | ||
7012 | a single ``SRC_URI`` entry. On the other hand, if the recipe or | ||
7013 | append file needs to fetch a tarball, apply two patches, and include | ||
7014 | a custom file, the recipe or append file would include four instances | ||
7015 | of the variable. | ||
7016 | |||
7017 | The following list explains the available URI protocols. URI | ||
7018 | protocols are highly dependent on particular BitBake Fetcher | ||
7019 | submodules. Depending on the fetcher BitBake uses, various URL | ||
7020 | parameters are employed. For specifics on the supported Fetchers, see | ||
7021 | the ":ref:`Fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`" section in the | ||
7022 | BitBake User Manual. | ||
7023 | |||
7024 | - ``file://`` - Fetches files, which are usually files shipped | ||
7025 | with the :term:`Metadata`, from the local machine (e.g. | ||
7026 | :ref:`patch <overview-manual/concepts:patching>` files). | ||
7027 | The path is relative to the :term:`FILESPATH` | ||
7028 | variable. Thus, the build system searches, in order, from the | ||
7029 | following directories, which are assumed to be a subdirectories of | ||
7030 | the directory in which the recipe file (``.bb``) or append file | ||
7031 | (``.bbappend``) resides: | ||
7032 | |||
7033 | - ``${BPN}`` - The base recipe name without any special suffix | ||
7034 | or version numbers. | ||
7035 | |||
7036 | - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and | ||
7037 | version but without any special package name suffix. | ||
7038 | |||
7039 | - *files -* Files within a directory, which is named ``files`` | ||
7040 | and is also alongside the recipe or append file. | ||
7041 | |||
7042 | .. note:: | ||
7043 | |||
7044 | If you want the build system to pick up files specified through | ||
7045 | a | ||
7046 | SRC_URI | ||
7047 | statement from your append file, you need to be sure to extend | ||
7048 | the | ||
7049 | FILESPATH | ||
7050 | variable by also using the | ||
7051 | FILESEXTRAPATHS | ||
7052 | variable from within your append file. | ||
7053 | |||
7054 | - ``bzr://`` - Fetches files from a Bazaar revision control | ||
7055 | repository. | ||
7056 | |||
7057 | - ``git://`` - Fetches files from a Git revision control | ||
7058 | repository. | ||
7059 | |||
7060 | - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) | ||
7061 | revision control repository. | ||
7062 | |||
7063 | - ``repo://`` - Fetches files from a repo (Git) repository. | ||
7064 | |||
7065 | - ``ccrc://`` - Fetches files from a ClearCase repository. | ||
7066 | |||
7067 | - ``http://`` - Fetches files from the Internet using ``http``. | ||
7068 | |||
7069 | - ``https://`` - Fetches files from the Internet using ``https``. | ||
7070 | |||
7071 | - ``ftp://`` - Fetches files from the Internet using ``ftp``. | ||
7072 | |||
7073 | - ``cvs://`` - Fetches files from a CVS revision control | ||
7074 | repository. | ||
7075 | |||
7076 | - ``hg://`` - Fetches files from a Mercurial (``hg``) revision | ||
7077 | control repository. | ||
7078 | |||
7079 | - ``p4://`` - Fetches files from a Perforce (``p4``) revision | ||
7080 | control repository. | ||
7081 | |||
7082 | - ``ssh://`` - Fetches files from a secure shell. | ||
7083 | |||
7084 | - ``svn://`` - Fetches files from a Subversion (``svn``) revision | ||
7085 | control repository. | ||
7086 | |||
7087 | - ``npm://`` - Fetches JavaScript modules from a registry. | ||
7088 | |||
7089 | Standard and recipe-specific options for ``SRC_URI`` exist. Here are | ||
7090 | standard options: | ||
7091 | |||
7092 | - ``apply`` - Whether to apply the patch or not. The default | ||
7093 | action is to apply the patch. | ||
7094 | |||
7095 | - ``striplevel`` - Which striplevel to use when applying the | ||
7096 | patch. The default level is 1. | ||
7097 | |||
7098 | - ``patchdir`` - Specifies the directory in which the patch should | ||
7099 | be applied. The default is ``${``\ :term:`S`\ ``}``. | ||
7100 | |||
7101 | Here are options specific to recipes building code from a revision | ||
7102 | control system: | ||
7103 | |||
7104 | - ``mindate`` - Apply the patch only if | ||
7105 | :term:`SRCDATE` is equal to or greater than | ||
7106 | ``mindate``. | ||
7107 | |||
7108 | - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later | ||
7109 | than ``maxdate``. | ||
7110 | |||
7111 | - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or | ||
7112 | greater than ``minrev``. | ||
7113 | |||
7114 | - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later | ||
7115 | than ``maxrev``. | ||
7116 | |||
7117 | - ``rev`` - Apply the patch only if ``SRCREV`` is equal to | ||
7118 | ``rev``. | ||
7119 | |||
7120 | - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to | ||
7121 | ``rev``. | ||
7122 | |||
7123 | Here are some additional options worth mentioning: | ||
7124 | |||
7125 | - ``unpack`` - Controls whether or not to unpack the file if it is | ||
7126 | an archive. The default action is to unpack the file. | ||
7127 | |||
7128 | - ``destsuffix`` - Places the file (or extracts its contents) into | ||
7129 | the specified subdirectory of :term:`WORKDIR` when | ||
7130 | the Git fetcher is used. | ||
7131 | |||
7132 | - ``subdir`` - Places the file (or extracts its contents) into the | ||
7133 | specified subdirectory of ``WORKDIR`` when the local (``file://``) | ||
7134 | fetcher is used. | ||
7135 | |||
7136 | - ``localdir`` - Places the file (or extracts its contents) into | ||
7137 | the specified subdirectory of ``WORKDIR`` when the CVS fetcher is | ||
7138 | used. | ||
7139 | |||
7140 | - ``subpath`` - Limits the checkout to a specific subpath of the | ||
7141 | tree when using the Git fetcher is used. | ||
7142 | |||
7143 | - ``name`` - Specifies a name to be used for association with | ||
7144 | ``SRC_URI`` checksums or :term:`SRCREV` when you have more than one | ||
7145 | file or git repository specified in ``SRC_URI``. For example: | ||
7146 | :: | ||
7147 | |||
7148 | SRC_URI = "git://example.com/foo.git;name=first \ | ||
7149 | git://example.com/bar.git;name=second \ | ||
7150 | http://example.com/file.tar.gz;name=third" | ||
7151 | |||
7152 | SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" | ||
7153 | SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" | ||
7154 | SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" | ||
7155 | |||
7156 | |||
7157 | - ``downloadfilename`` - Specifies the filename used when storing | ||
7158 | the downloaded file. | ||
7159 | |||
7160 | :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` | ||
7161 | By default, the OpenEmbedded build system automatically detects | ||
7162 | whether ``SRC_URI`` contains files that are machine-specific. If so, | ||
7163 | the build system automatically changes ``PACKAGE_ARCH``. Setting this | ||
7164 | variable to "0" disables this behavior. | ||
7165 | |||
7166 | :term:`SRCDATE` | ||
7167 | The date of the source code used to build the package. This variable | ||
7168 | applies only if the source was fetched from a Source Code Manager | ||
7169 | (SCM). | ||
7170 | |||
7171 | :term:`SRCPV` | ||
7172 | Returns the version string of the current package. This string is | ||
7173 | used to help define the value of :term:`PV`. | ||
7174 | |||
7175 | The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` | ||
7176 | configuration file in the :term:`Source Directory` as | ||
7177 | follows: | ||
7178 | :: | ||
7179 | |||
7180 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" | ||
7181 | |||
7182 | Recipes that need to define ``PV`` do so with the help of the | ||
7183 | ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) | ||
7184 | located in ``meta/recipes-connectivity`` in the Source Directory | ||
7185 | defines ``PV`` as follows: | ||
7186 | :: | ||
7187 | |||
7188 | PV = "0.12-git${SRCPV}" | ||
7189 | |||
7190 | :term:`SRCREV` | ||
7191 | The revision of the source code used to build the package. This | ||
7192 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note | ||
7193 | that if you want to build a fixed revision and you want to avoid | ||
7194 | performing a query on the remote repository every time BitBake parses | ||
7195 | your recipe, you should specify a ``SRCREV`` that is a full revision | ||
7196 | identifier and not just a tag. | ||
7197 | |||
7198 | .. note:: | ||
7199 | |||
7200 | For information on limitations when inheriting the latest revision | ||
7201 | of software using ``SRCREV``, see the :term:`AUTOREV` variable | ||
7202 | description and the | ||
7203 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | ||
7204 | section, which is in the Yocto Project Development Tasks Manual. | ||
7205 | |||
7206 | :term:`SSTATE_DIR` | ||
7207 | The directory for the shared state cache. | ||
7208 | |||
7209 | :term:`SSTATE_MIRROR_ALLOW_NETWORK` | ||
7210 | If set to "1", allows fetches from mirrors that are specified in | ||
7211 | :term:`SSTATE_MIRRORS` to work even when | ||
7212 | fetching from the network is disabled by setting ``BB_NO_NETWORK`` to | ||
7213 | "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if | ||
7214 | you have set ``SSTATE_MIRRORS`` to point to an internal server for | ||
7215 | your shared state cache, but you want to disable any other fetching | ||
7216 | from the network. | ||
7217 | |||
7218 | :term:`SSTATE_MIRRORS` | ||
7219 | Configures the OpenEmbedded build system to search other mirror | ||
7220 | locations for prebuilt cache data objects before building out the | ||
7221 | data. This variable works like fetcher :term:`MIRRORS` | ||
7222 | and :term:`PREMIRRORS` and points to the cache | ||
7223 | locations to check for the shared state (sstate) objects. | ||
7224 | |||
7225 | You can specify a filesystem directory or a remote URL such as HTTP | ||
7226 | or FTP. The locations you specify need to contain the shared state | ||
7227 | cache (sstate-cache) results from previous builds. The sstate-cache | ||
7228 | you point to can also be from builds on other machines. | ||
7229 | |||
7230 | When pointing to sstate build artifacts on another machine that uses | ||
7231 | a different GCC version for native builds, you must configure | ||
7232 | ``SSTATE_MIRRORS`` with a regular expression that maps local search | ||
7233 | paths to server paths. The paths need to take into account | ||
7234 | :term:`NATIVELSBSTRING` set by the | ||
7235 | :ref:`uninative <ref-classes-uninative>` class. For example, the | ||
7236 | following maps the local search path ``universal-4.9`` to the | ||
7237 | server-provided path server_url_sstate_path: | ||
7238 | :: | ||
7239 | |||
7240 | SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" | ||
7241 | |||
7242 | If a mirror uses the same structure as | ||
7243 | :term:`SSTATE_DIR`, you need to add "PATH" at the | ||
7244 | end as shown in the examples below. The build system substitutes the | ||
7245 | correct path within the directory structure. | ||
7246 | :: | ||
7247 | |||
7248 | SSTATE_MIRRORS ?= "\ | ||
7249 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | ||
7250 | file://.* file:///some-local-dir/sstate/PATH" | ||
7251 | |||
7252 | :term:`SSTATE_SCAN_FILES` | ||
7253 | Controls the list of files the OpenEmbedded build system scans for | ||
7254 | hardcoded installation paths. The variable uses a space-separated | ||
7255 | list of filenames (not paths) with standard wildcard characters | ||
7256 | allowed. | ||
7257 | |||
7258 | During a build, the OpenEmbedded build system creates a shared state | ||
7259 | (sstate) object during the first stage of preparing the sysroots. | ||
7260 | That object is scanned for hardcoded paths for original installation | ||
7261 | locations. The list of files that are scanned for paths is controlled | ||
7262 | by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files | ||
7263 | they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather | ||
7264 | than the variable being comprehensively set. The | ||
7265 | :ref:`sstate <ref-classes-sstate>` class specifies the default list | ||
7266 | of files. | ||
7267 | |||
7268 | For details on the process, see the | ||
7269 | :ref:`staging <ref-classes-staging>` class. | ||
7270 | |||
7271 | :term:`STAGING_BASE_LIBDIR_NATIVE` | ||
7272 | Specifies the path to the ``/lib`` subdirectory of the sysroot | ||
7273 | directory for the build host. | ||
7274 | |||
7275 | :term:`STAGING_BASELIBDIR` | ||
7276 | Specifies the path to the ``/lib`` subdirectory of the sysroot | ||
7277 | directory for the target for which the current recipe is being built | ||
7278 | (:term:`STAGING_DIR_HOST`). | ||
7279 | |||
7280 | :term:`STAGING_BINDIR` | ||
7281 | Specifies the path to the ``/usr/bin`` subdirectory of the sysroot | ||
7282 | directory for the target for which the current recipe is being built | ||
7283 | (:term:`STAGING_DIR_HOST`). | ||
7284 | |||
7285 | :term:`STAGING_BINDIR_CROSS` | ||
7286 | Specifies the path to the directory containing binary configuration | ||
7287 | scripts. These scripts provide configuration information for other | ||
7288 | software that wants to make use of libraries or include files | ||
7289 | provided by the software associated with the script. | ||
7290 | |||
7291 | .. note:: | ||
7292 | |||
7293 | This style of build configuration has been largely replaced by | ||
7294 | ``pkg-config``. Consequently, if ``pkg-config`` is supported by the | ||
7295 | library to which you are linking, it is recommended you use | ||
7296 | ``pkg-config`` instead of a provided configuration script. | ||
7297 | |||
7298 | :term:`STAGING_BINDIR_NATIVE` | ||
7299 | Specifies the path to the ``/usr/bin`` subdirectory of the sysroot | ||
7300 | directory for the build host. | ||
7301 | |||
7302 | :term:`STAGING_DATADIR` | ||
7303 | Specifies the path to the ``/usr/share`` subdirectory of the sysroot | ||
7304 | directory for the target for which the current recipe is being built | ||
7305 | (:term:`STAGING_DIR_HOST`). | ||
7306 | |||
7307 | :term:`STAGING_DATADIR_NATIVE` | ||
7308 | Specifies the path to the ``/usr/share`` subdirectory of the sysroot | ||
7309 | directory for the build host. | ||
7310 | |||
7311 | :term:`STAGING_DIR` | ||
7312 | Helps construct the ``recipe-sysroots`` directory, which is used | ||
7313 | during packaging. | ||
7314 | |||
7315 | For information on how staging for recipe-specific sysroots occurs, | ||
7316 | see the :ref:`ref-tasks-populate_sysroot` | ||
7317 | task, the ":ref:`sdk-manual/extensible:sharing files between recipes`" | ||
7318 | section in the Yocto Project Development Tasks Manual, the | ||
7319 | ":ref:`overview-manual/concepts:configuration, compilation, and staging`" | ||
7320 | section in the Yocto Project Overview and Concepts Manual, and the | ||
7321 | :term:`SYSROOT_DIRS` variable. | ||
7322 | |||
7323 | .. note:: | ||
7324 | |||
7325 | Recipes should never write files directly under the ``STAGING_DIR`` | ||
7326 | directory because the OpenEmbedded build system manages the | ||
7327 | directory automatically. Instead, files should be installed to | ||
7328 | ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` | ||
7329 | task and then the OpenEmbedded build system will stage a subset of | ||
7330 | those files into the sysroot. | ||
7331 | |||
7332 | :term:`STAGING_DIR_HOST` | ||
7333 | Specifies the path to the sysroot directory for the system on which | ||
7334 | the component is built to run (the system that hosts the component). | ||
7335 | For most recipes, this sysroot is the one in which that recipe's | ||
7336 | :ref:`ref-tasks-populate_sysroot` task copies | ||
7337 | files. Exceptions include ``-native`` recipes, where the | ||
7338 | ``do_populate_sysroot`` task instead uses | ||
7339 | :term:`STAGING_DIR_NATIVE`. Depending on | ||
7340 | the type of recipe and the build target, ``STAGING_DIR_HOST`` can | ||
7341 | have the following values: | ||
7342 | |||
7343 | - For recipes building for the target machine, the value is | ||
7344 | "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". | ||
7345 | |||
7346 | - For native recipes building for the build host, the value is empty | ||
7347 | given the assumption that when building for the build host, the | ||
7348 | build host's own directories should be used. | ||
7349 | |||
7350 | .. note:: | ||
7351 | |||
7352 | ``-native`` recipes are not installed into host paths like such | ||
7353 | as ``/usr``. Rather, these recipes are installed into | ||
7354 | ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, | ||
7355 | standard build environment variables such as | ||
7356 | :term:`CPPFLAGS` and | ||
7357 | :term:`CFLAGS` are set up so that both host paths | ||
7358 | and ``STAGING_DIR_NATIVE`` are searched for libraries and | ||
7359 | headers using, for example, GCC's ``-isystem`` option. | ||
7360 | |||
7361 | Thus, the emphasis is that the ``STAGING_DIR*`` variables | ||
7362 | should be viewed as input variables by tasks such as | ||
7363 | :ref:`ref-tasks-configure`, | ||
7364 | :ref:`ref-tasks-compile`, and | ||
7365 | :ref:`ref-tasks-install`. Having the real system | ||
7366 | root correspond to ``STAGING_DIR_HOST`` makes conceptual sense | ||
7367 | for ``-native`` recipes, as they make use of host headers and | ||
7368 | libraries. | ||
7369 | |||
7370 | :term:`STAGING_DIR_NATIVE` | ||
7371 | Specifies the path to the sysroot directory used when building | ||
7372 | components that run on the build host itself. | ||
7373 | |||
7374 | :term:`STAGING_DIR_TARGET` | ||
7375 | Specifies the path to the sysroot used for the system for which the | ||
7376 | component generates code. For components that do not generate code, | ||
7377 | which is the majority, ``STAGING_DIR_TARGET`` is set to match | ||
7378 | :term:`STAGING_DIR_HOST`. | ||
7379 | |||
7380 | Some recipes build binaries that can run on the target system but | ||
7381 | those binaries in turn generate code for another different system | ||
7382 | (e.g. cross-canadian recipes). Using terminology from GNU, the | ||
7383 | primary system is referred to as the "HOST" and the secondary, or | ||
7384 | different, system is referred to as the "TARGET". Thus, the binaries | ||
7385 | run on the "HOST" system and generate binaries for the "TARGET" | ||
7386 | system. The ``STAGING_DIR_HOST`` variable points to the sysroot used | ||
7387 | for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the | ||
7388 | sysroot used for the "TARGET" system. | ||
7389 | |||
7390 | :term:`STAGING_ETCDIR_NATIVE` | ||
7391 | Specifies the path to the ``/etc`` subdirectory of the sysroot | ||
7392 | directory for the build host. | ||
7393 | |||
7394 | :term:`STAGING_EXECPREFIXDIR` | ||
7395 | Specifies the path to the ``/usr`` subdirectory of the sysroot | ||
7396 | directory for the target for which the current recipe is being built | ||
7397 | (:term:`STAGING_DIR_HOST`). | ||
7398 | |||
7399 | :term:`STAGING_INCDIR` | ||
7400 | Specifies the path to the ``/usr/include`` subdirectory of the | ||
7401 | sysroot directory for the target for which the current recipe being | ||
7402 | built (:term:`STAGING_DIR_HOST`). | ||
7403 | |||
7404 | :term:`STAGING_INCDIR_NATIVE` | ||
7405 | Specifies the path to the ``/usr/include`` subdirectory of the | ||
7406 | sysroot directory for the build host. | ||
7407 | |||
7408 | :term:`STAGING_KERNEL_BUILDDIR` | ||
7409 | Points to the directory containing the kernel build artifacts. | ||
7410 | Recipes building software that needs to access kernel build artifacts | ||
7411 | (e.g. ``systemtap-uprobes``) can look in the directory specified with | ||
7412 | the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts | ||
7413 | after the kernel has been built. | ||
7414 | |||
7415 | :term:`STAGING_KERNEL_DIR` | ||
7416 | The directory with kernel headers that are required to build | ||
7417 | out-of-tree modules. | ||
7418 | |||
7419 | :term:`STAGING_LIBDIR` | ||
7420 | Specifies the path to the ``/usr/lib`` subdirectory of the sysroot | ||
7421 | directory for the target for which the current recipe is being built | ||
7422 | (:term:`STAGING_DIR_HOST`). | ||
7423 | |||
7424 | :term:`STAGING_LIBDIR_NATIVE` | ||
7425 | Specifies the path to the ``/usr/lib`` subdirectory of the sysroot | ||
7426 | directory for the build host. | ||
7427 | |||
7428 | :term:`STAMP` | ||
7429 | Specifies the base path used to create recipe stamp files. The path | ||
7430 | to an actual stamp file is constructed by evaluating this string and | ||
7431 | then appending additional information. Currently, the default | ||
7432 | assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` | ||
7433 | file is: | ||
7434 | :: | ||
7435 | |||
7436 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" | ||
7437 | |||
7438 | For information on how BitBake uses stamp files to determine if a | ||
7439 | task should be rerun, see the | ||
7440 | ":ref:`overview-manual/concepts:stamp files and the rerunning of tasks`" | ||
7441 | section in the Yocto Project Overview and Concepts Manual. | ||
7442 | |||
7443 | See :term:`STAMPS_DIR`, | ||
7444 | :term:`MULTIMACH_TARGET_SYS`, | ||
7445 | :term:`PN`, :term:`EXTENDPE`, | ||
7446 | :term:`PV`, and :term:`PR` for related variable | ||
7447 | information. | ||
7448 | |||
7449 | :term:`STAMPS_DIR` | ||
7450 | Specifies the base directory in which the OpenEmbedded build system | ||
7451 | places stamps. The default directory is ``${TMPDIR}/stamps``. | ||
7452 | |||
7453 | :term:`STRIP` | ||
7454 | The minimal command and arguments to run ``strip``, which is used to | ||
7455 | strip symbols. | ||
7456 | |||
7457 | :term:`SUMMARY` | ||
7458 | The short (72 characters or less) summary of the binary package for | ||
7459 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, | ||
7460 | ``SUMMARY`` is used to define the | ||
7461 | :term:`DESCRIPTION` variable if ``DESCRIPTION`` is | ||
7462 | not set in the recipe. | ||
7463 | |||
7464 | :term:`SVNDIR` | ||
7465 | The directory in which files checked out of a Subversion system are | ||
7466 | stored. | ||
7467 | |||
7468 | :term:`SYSLINUX_DEFAULT_CONSOLE` | ||
7469 | Specifies the kernel boot default console. If you want to use a | ||
7470 | console other than the default, set this variable in your recipe as | ||
7471 | follows where "X" is the console number you want to use: | ||
7472 | :: | ||
7473 | |||
7474 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" | ||
7475 | |||
7476 | The :ref:`syslinux <ref-classes-syslinux>` class initially sets | ||
7477 | this variable to null but then checks for a value later. | ||
7478 | |||
7479 | :term:`SYSLINUX_OPTS` | ||
7480 | Lists additional options to add to the syslinux file. You need to set | ||
7481 | this variable in your recipe. If you want to list multiple options, | ||
7482 | separate the options with a semicolon character (``;``). | ||
7483 | |||
7484 | The :ref:`syslinux <ref-classes-syslinux>` class uses this variable | ||
7485 | to create a set of options. | ||
7486 | |||
7487 | :term:`SYSLINUX_SERIAL` | ||
7488 | Specifies the alternate serial port or turns it off. To turn off | ||
7489 | serial, set this variable to an empty string in your recipe. The | ||
7490 | variable's default value is set in the | ||
7491 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | ||
7492 | :: | ||
7493 | |||
7494 | SYSLINUX_SERIAL ?= "0 115200" | ||
7495 | |||
7496 | The class checks for and uses the variable as needed. | ||
7497 | |||
7498 | :term:`SYSLINUX_SERIAL_TTY` | ||
7499 | Specifies the alternate console=tty... kernel boot argument. The | ||
7500 | variable's default value is set in the | ||
7501 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | ||
7502 | :: | ||
7503 | |||
7504 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" | ||
7505 | |||
7506 | The class checks for and uses the variable as needed. | ||
7507 | |||
7508 | :term:`SYSLINUX_SPLASH` | ||
7509 | An ``.LSS`` file used as the background for the VGA boot menu when | ||
7510 | you use the boot menu. You need to set this variable in your recipe. | ||
7511 | |||
7512 | The :ref:`syslinux <ref-classes-syslinux>` class checks for this | ||
7513 | variable and if found, the OpenEmbedded build system installs the | ||
7514 | splash screen. | ||
7515 | |||
7516 | :term:`SYSROOT_DESTDIR` | ||
7517 | Points to the temporary directory under the work directory (default | ||
7518 | "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") | ||
7519 | where the files populated into the sysroot are assembled during the | ||
7520 | :ref:`ref-tasks-populate_sysroot` task. | ||
7521 | |||
7522 | :term:`SYSROOT_DIRS` | ||
7523 | Directories that are staged into the sysroot by the | ||
7524 | :ref:`ref-tasks-populate_sysroot` task. By | ||
7525 | default, the following directories are staged: | ||
7526 | :: | ||
7527 | |||
7528 | SYSROOT_DIRS = " \ | ||
7529 | ${includedir} \ | ||
7530 | ${libdir} \ | ||
7531 | ${base_libdir} \ | ||
7532 | ${nonarch_base_libdir} \ | ||
7533 | ${datadir} \ | ||
7534 | " | ||
7535 | |||
7536 | :term:`SYSROOT_DIRS_BLACKLIST` | ||
7537 | Directories that are not staged into the sysroot by the | ||
7538 | :ref:`ref-tasks-populate_sysroot` task. You | ||
7539 | can use this variable to exclude certain subdirectories of | ||
7540 | directories listed in :term:`SYSROOT_DIRS` from | ||
7541 | staging. By default, the following directories are not staged: | ||
7542 | :: | ||
7543 | |||
7544 | SYSROOT_DIRS_BLACKLIST = " \ | ||
7545 | ${mandir} \ | ||
7546 | ${docdir} \ | ||
7547 | ${infodir} \ | ||
7548 | ${datadir}/locale \ | ||
7549 | ${datadir}/applications \ | ||
7550 | ${datadir}/fonts \ | ||
7551 | ${datadir}/pixmaps \ | ||
7552 | " | ||
7553 | |||
7554 | :term:`SYSROOT_DIRS_NATIVE` | ||
7555 | Extra directories staged into the sysroot by the | ||
7556 | :ref:`ref-tasks-populate_sysroot` task for | ||
7557 | ``-native`` recipes, in addition to those specified in | ||
7558 | :term:`SYSROOT_DIRS`. By default, the following | ||
7559 | extra directories are staged: | ||
7560 | :: | ||
7561 | |||
7562 | SYSROOT_DIRS_NATIVE = " \ | ||
7563 | ${bindir} \ | ||
7564 | ${sbindir} \ | ||
7565 | ${base_bindir} \ | ||
7566 | ${base_sbindir} \ | ||
7567 | ${libexecdir} \ | ||
7568 | ${sysconfdir} \ | ||
7569 | ${localstatedir} \ | ||
7570 | " | ||
7571 | |||
7572 | .. note:: | ||
7573 | |||
7574 | Programs built by ``-native`` recipes run directly from the sysroot | ||
7575 | (:term:`STAGING_DIR_NATIVE`), which is why additional directories | ||
7576 | containing program executables and supporting files need to be staged. | ||
7577 | |||
7578 | :term:`SYSROOT_PREPROCESS_FUNCS` | ||
7579 | A list of functions to execute after files are staged into the | ||
7580 | sysroot. These functions are usually used to apply additional | ||
7581 | processing on the staged files, or to stage additional files. | ||
7582 | |||
7583 | :term:`SYSTEMD_AUTO_ENABLE` | ||
7584 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7585 | this variable specifies whether the specified service in | ||
7586 | :term:`SYSTEMD_SERVICE` should start | ||
7587 | automatically or not. By default, the service is enabled to | ||
7588 | automatically start at boot time. The default setting is in the | ||
7589 | :ref:`systemd <ref-classes-systemd>` class as follows: | ||
7590 | :: | ||
7591 | |||
7592 | SYSTEMD_AUTO_ENABLE ??= "enable" | ||
7593 | |||
7594 | You can disable the service by setting the variable to "disable". | ||
7595 | |||
7596 | :term:`SYSTEMD_BOOT_CFG` | ||
7597 | When :term:`EFI_PROVIDER` is set to | ||
7598 | "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the | ||
7599 | configuration file that should be used. By default, the | ||
7600 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7601 | ``SYSTEMD_BOOT_CFG`` as follows: | ||
7602 | :: | ||
7603 | |||
7604 | SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" | ||
7605 | |||
7606 | For information on Systemd-boot, see the `Systemd-boot | ||
7607 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7608 | |||
7609 | :term:`SYSTEMD_BOOT_ENTRIES` | ||
7610 | When :term:`EFI_PROVIDER` is set to | ||
7611 | "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a | ||
7612 | list of entry files (``*.conf``) to install that contain one boot | ||
7613 | entry per file. By default, the | ||
7614 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7615 | ``SYSTEMD_BOOT_ENTRIES`` as follows: | ||
7616 | :: | ||
7617 | |||
7618 | SYSTEMD_BOOT_ENTRIES ?= "" | ||
7619 | |||
7620 | For information on Systemd-boot, see the `Systemd-boot | ||
7621 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7622 | |||
7623 | :term:`SYSTEMD_BOOT_TIMEOUT` | ||
7624 | When :term:`EFI_PROVIDER` is set to | ||
7625 | "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the | ||
7626 | boot menu timeout in seconds. By default, the | ||
7627 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | ||
7628 | ``SYSTEMD_BOOT_TIMEOUT`` as follows: | ||
7629 | :: | ||
7630 | |||
7631 | SYSTEMD_BOOT_TIMEOUT ?= "10" | ||
7632 | |||
7633 | For information on Systemd-boot, see the `Systemd-boot | ||
7634 | documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | ||
7635 | |||
7636 | :term:`SYSTEMD_PACKAGES` | ||
7637 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7638 | this variable locates the systemd unit files when they are not found | ||
7639 | in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` | ||
7640 | variable is set such that the systemd unit files are assumed to | ||
7641 | reside in the recipes main package: | ||
7642 | :: | ||
7643 | |||
7644 | SYSTEMD_PACKAGES ?= "${PN}" | ||
7645 | |||
7646 | If these unit files are not in this recipe's main package, you need | ||
7647 | to use ``SYSTEMD_PACKAGES`` to list the package or packages in which | ||
7648 | the build system can find the systemd unit files. | ||
7649 | |||
7650 | :term:`SYSTEMD_SERVICE` | ||
7651 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | ||
7652 | this variable specifies the systemd service name for a package. | ||
7653 | |||
7654 | When you specify this file in your recipe, use a package name | ||
7655 | override to indicate the package to which the value applies. Here is | ||
7656 | an example from the connman recipe: | ||
7657 | :: | ||
7658 | |||
7659 | SYSTEMD_SERVICE_${PN} = "connman.service" | ||
7660 | |||
7661 | :term:`SYSVINIT_ENABLED_GETTYS` | ||
7662 | When using | ||
7663 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | ||
7664 | specifies a space-separated list of the virtual terminals that should | ||
7665 | run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ | ||
7666 | (allowing login), assuming :term:`USE_VT` is not set to | ||
7667 | "0". | ||
7668 | |||
7669 | The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only | ||
7670 | run a getty on the first virtual terminal). | ||
7671 | |||
7672 | :term:`T` | ||
7673 | This variable points to a directory were BitBake places temporary | ||
7674 | files, which consist mostly of task logs and scripts, when building a | ||
7675 | particular recipe. The variable is typically set as follows: | ||
7676 | :: | ||
7677 | |||
7678 | T = "${WORKDIR}/temp" | ||
7679 | |||
7680 | The :term:`WORKDIR` is the directory into which | ||
7681 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` | ||
7682 | file sets this variable. | ||
7683 | |||
7684 | The ``T`` variable is not to be confused with the | ||
7685 | :term:`TMPDIR` variable, which points to the root of | ||
7686 | the directory tree where BitBake places the output of an entire | ||
7687 | build. | ||
7688 | |||
7689 | :term:`TARGET_ARCH` | ||
7690 | The target machine's architecture. The OpenEmbedded build system | ||
7691 | supports many architectures. Here is an example list of architectures | ||
7692 | supported. This list is by no means complete as the architecture is | ||
7693 | configurable: | ||
7694 | |||
7695 | - arm | ||
7696 | - i586 | ||
7697 | - x86_64 | ||
7698 | - powerpc | ||
7699 | - powerpc64 | ||
7700 | - mips | ||
7701 | - mipsel | ||
7702 | |||
7703 | For additional information on machine architectures, see the | ||
7704 | :term:`TUNE_ARCH` variable. | ||
7705 | |||
7706 | :term:`TARGET_AS_ARCH` | ||
7707 | Specifies architecture-specific assembler flags for the target | ||
7708 | system. ``TARGET_AS_ARCH`` is initialized from | ||
7709 | :term:`TUNE_ASARGS` by default in the BitBake | ||
7710 | configuration file (``meta/conf/bitbake.conf``): | ||
7711 | :: | ||
7712 | |||
7713 | TARGET_AS_ARCH = "${TUNE_ASARGS}" | ||
7714 | |||
7715 | :term:`TARGET_CC_ARCH` | ||
7716 | Specifies architecture-specific C compiler flags for the target | ||
7717 | system. ``TARGET_CC_ARCH`` is initialized from | ||
7718 | :term:`TUNE_CCARGS` by default. | ||
7719 | |||
7720 | .. note:: | ||
7721 | |||
7722 | It is a common workaround to append :term:`LDFLAGS` to | ||
7723 | ``TARGET_CC_ARCH`` in recipes that build software for the target that | ||
7724 | would not otherwise respect the exported ``LDFLAGS`` variable. | ||
7725 | |||
7726 | :term:`TARGET_CC_KERNEL_ARCH` | ||
7727 | This is a specific kernel compiler flag for a CPU or Application | ||
7728 | Binary Interface (ABI) tune. The flag is used rarely and only for | ||
7729 | cases where a userspace :term:`TUNE_CCARGS` is not | ||
7730 | compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` | ||
7731 | variable allows the kernel (and associated modules) to use a | ||
7732 | different configuration. See the | ||
7733 | ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the | ||
7734 | :term:`Source Directory` for an example. | ||
7735 | |||
7736 | :term:`TARGET_CFLAGS` | ||
7737 | Specifies the flags to pass to the C compiler when building for the | ||
7738 | target. When building in the target context, | ||
7739 | :term:`CFLAGS` is set to the value of this variable by | ||
7740 | default. | ||
7741 | |||
7742 | Additionally, the SDK's environment setup script sets the ``CFLAGS`` | ||
7743 | variable in the environment to the ``TARGET_CFLAGS`` value so that | ||
7744 | executables built using the SDK also have the flags applied. | ||
7745 | |||
7746 | :term:`TARGET_CPPFLAGS` | ||
7747 | Specifies the flags to pass to the C pre-processor (i.e. to both the | ||
7748 | C and the C++ compilers) when building for the target. When building | ||
7749 | in the target context, :term:`CPPFLAGS` is set to the | ||
7750 | value of this variable by default. | ||
7751 | |||
7752 | Additionally, the SDK's environment setup script sets the | ||
7753 | ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` | ||
7754 | value so that executables built using the SDK also have the flags | ||
7755 | applied. | ||
7756 | |||
7757 | :term:`TARGET_CXXFLAGS` | ||
7758 | Specifies the flags to pass to the C++ compiler when building for the | ||
7759 | target. When building in the target context, | ||
7760 | :term:`CXXFLAGS` is set to the value of this variable | ||
7761 | by default. | ||
7762 | |||
7763 | Additionally, the SDK's environment setup script sets the | ||
7764 | ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` | ||
7765 | value so that executables built using the SDK also have the flags | ||
7766 | applied. | ||
7767 | |||
7768 | :term:`TARGET_FPU` | ||
7769 | Specifies the method for handling FPU code. For FPU-less targets, | ||
7770 | which include most ARM CPUs, the variable must be set to "soft". If | ||
7771 | not, the kernel emulation gets used, which results in a performance | ||
7772 | penalty. | ||
7773 | |||
7774 | :term:`TARGET_LD_ARCH` | ||
7775 | Specifies architecture-specific linker flags for the target system. | ||
7776 | ``TARGET_LD_ARCH`` is initialized from | ||
7777 | :term:`TUNE_LDARGS` by default in the BitBake | ||
7778 | configuration file (``meta/conf/bitbake.conf``): | ||
7779 | :: | ||
7780 | |||
7781 | TARGET_LD_ARCH = "${TUNE_LDARGS}" | ||
7782 | |||
7783 | :term:`TARGET_LDFLAGS` | ||
7784 | Specifies the flags to pass to the linker when building for the | ||
7785 | target. When building in the target context, | ||
7786 | :term:`LDFLAGS` is set to the value of this variable | ||
7787 | by default. | ||
7788 | |||
7789 | Additionally, the SDK's environment setup script sets the | ||
7790 | :term:`LDFLAGS` variable in the environment to the | ||
7791 | ``TARGET_LDFLAGS`` value so that executables built using the SDK also | ||
7792 | have the flags applied. | ||
7793 | |||
7794 | :term:`TARGET_OS` | ||
7795 | Specifies the target's operating system. The variable can be set to | ||
7796 | "linux" for glibc-based systems (GNU C Library) and to "linux-musl" | ||
7797 | for musl libc. For ARM/EABI targets, "linux-gnueabi" and | ||
7798 | "linux-musleabi" possible values exist. | ||
7799 | |||
7800 | :term:`TARGET_PREFIX` | ||
7801 | Specifies the prefix used for the toolchain binary target tools. | ||
7802 | |||
7803 | Depending on the type of recipe and the build target, | ||
7804 | ``TARGET_PREFIX`` is set as follows: | ||
7805 | |||
7806 | - For recipes building for the target machine, the value is | ||
7807 | "${:term:`TARGET_SYS`}-". | ||
7808 | |||
7809 | - For native recipes, the build system sets the variable to the | ||
7810 | value of ``BUILD_PREFIX``. | ||
7811 | |||
7812 | - For native SDK recipes (``nativesdk``), the build system sets the | ||
7813 | variable to the value of ``SDK_PREFIX``. | ||
7814 | |||
7815 | :term:`TARGET_SYS` | ||
7816 | Specifies the system, including the architecture and the operating | ||
7817 | system, for which the build is occurring in the context of the | ||
7818 | current recipe. | ||
7819 | |||
7820 | The OpenEmbedded build system automatically sets this variable based | ||
7821 | on :term:`TARGET_ARCH`, | ||
7822 | :term:`TARGET_VENDOR`, and | ||
7823 | :term:`TARGET_OS` variables. | ||
7824 | |||
7825 | .. note:: | ||
7826 | |||
7827 | You do not need to set the ``TARGET_SYS`` variable yourself. | ||
7828 | |||
7829 | Consider these two examples: | ||
7830 | |||
7831 | - Given a native recipe on a 32-bit, x86 machine running Linux, the | ||
7832 | value is "i686-linux". | ||
7833 | |||
7834 | - Given a recipe being built for a little-endian, MIPS target | ||
7835 | running Linux, the value might be "mipsel-linux". | ||
7836 | |||
7837 | :term:`TARGET_VENDOR` | ||
7838 | Specifies the name of the target vendor. | ||
7839 | |||
7840 | :term:`TCLIBC` | ||
7841 | Specifies the GNU standard C library (``libc``) variant to use during | ||
7842 | the build process. This variable replaces ``POKYLIBC``, which is no | ||
7843 | longer supported. | ||
7844 | |||
7845 | You can select "glibc", "musl", "newlib", or "baremetal" | ||
7846 | |||
7847 | :term:`TCLIBCAPPEND` | ||
7848 | Specifies a suffix to be appended onto the | ||
7849 | :term:`TMPDIR` value. The suffix identifies the | ||
7850 | ``libc`` variant for building. When you are building for multiple | ||
7851 | variants with the same :term:`Build Directory`, this | ||
7852 | mechanism ensures that output for different ``libc`` variants is kept | ||
7853 | separate to avoid potential conflicts. | ||
7854 | |||
7855 | In the ``defaultsetup.conf`` file, the default value of | ||
7856 | ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, | ||
7857 | which normally only support one ``libc`` variant, set | ||
7858 | ``TCLIBCAPPEND`` to "" in their distro configuration file resulting | ||
7859 | in no suffix being applied. | ||
7860 | |||
7861 | :term:`TCMODE` | ||
7862 | Specifies the toolchain selector. ``TCMODE`` controls the | ||
7863 | characteristics of the generated packages and images by telling the | ||
7864 | OpenEmbedded build system which toolchain profile to use. By default, | ||
7865 | the OpenEmbedded build system builds its own internal toolchain. The | ||
7866 | variable's default value is "default", which uses that internal | ||
7867 | toolchain. | ||
7868 | |||
7869 | .. note:: | ||
7870 | |||
7871 | If ``TCMODE`` is set to a value other than "default", then it is your | ||
7872 | responsibility to ensure that the toolchain is compatible with the | ||
7873 | default toolchain. Using older or newer versions of these | ||
7874 | components might cause build problems. See the Release Notes for | ||
7875 | the Yocto Project release for the specific components with which | ||
7876 | the toolchain must be compatible. To access the Release Notes, go | ||
7877 | to the :yocto_home:`Downloads </software-overview/downloads>` | ||
7878 | page on the Yocto Project website and click on the "RELEASE | ||
7879 | INFORMATION" link for the appropriate release. | ||
7880 | |||
7881 | The ``TCMODE`` variable is similar to :term:`TCLIBC`, | ||
7882 | which controls the variant of the GNU standard C library (``libc``) | ||
7883 | used during the build process: ``glibc`` or ``musl``. | ||
7884 | |||
7885 | With additional layers, it is possible to use a pre-compiled external | ||
7886 | toolchain. One example is the Sourcery G++ Toolchain. The support for | ||
7887 | this toolchain resides in the separate Mentor Graphics | ||
7888 | ``meta-sourcery`` layer at | ||
7889 | http://github.com/MentorEmbedded/meta-sourcery/. | ||
7890 | |||
7891 | The layer's ``README`` file contains information on how to use the | ||
7892 | Sourcery G++ Toolchain as an external toolchain. In summary, you must | ||
7893 | be sure to add the layer to your ``bblayers.conf`` file in front of | ||
7894 | the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable | ||
7895 | in your ``local.conf`` file to the location in which you installed | ||
7896 | the toolchain. | ||
7897 | |||
7898 | The fundamentals used for this example apply to any external | ||
7899 | toolchain. You can use ``meta-sourcery`` as a template for adding | ||
7900 | support for other external toolchains. | ||
7901 | |||
7902 | :term:`TEST_EXPORT_DIR` | ||
7903 | The location the OpenEmbedded build system uses to export tests when | ||
7904 | the :term:`TEST_EXPORT_ONLY` variable is set | ||
7905 | to "1". | ||
7906 | |||
7907 | The ``TEST_EXPORT_DIR`` variable defaults to | ||
7908 | ``"${TMPDIR}/testimage/${PN}"``. | ||
7909 | |||
7910 | :term:`TEST_EXPORT_ONLY` | ||
7911 | Specifies to export the tests only. Set this variable to "1" if you | ||
7912 | do not want to run the tests but you want them to be exported in a | ||
7913 | manner that you to run them outside of the build system. | ||
7914 | |||
7915 | :term:`TEST_LOG_DIR` | ||
7916 | Holds the SSH log and the boot log for QEMU machines. The | ||
7917 | ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. | ||
7918 | |||
7919 | .. note:: | ||
7920 | |||
7921 | Actual test results reside in the task log (``log.do_testimage``), | ||
7922 | which is in the ``${WORKDIR}/temp/`` directory. | ||
7923 | |||
7924 | :term:`TEST_POWERCONTROL_CMD` | ||
7925 | For automated hardware testing, specifies the command to use to | ||
7926 | control the power of the target machine under test. Typically, this | ||
7927 | command would point to a script that performs the appropriate action | ||
7928 | (e.g. interacting with a web-enabled power strip). The specified | ||
7929 | command should expect to receive as the last argument "off", "on" or | ||
7930 | "cycle" specifying to power off, on, or cycle (power off and then | ||
7931 | power on) the device, respectively. | ||
7932 | |||
7933 | :term:`TEST_POWERCONTROL_EXTRA_ARGS` | ||
7934 | For automated hardware testing, specifies additional arguments to | ||
7935 | pass through to the command specified in | ||
7936 | :term:`TEST_POWERCONTROL_CMD`. Setting | ||
7937 | ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you | ||
7938 | wish, for example, to separate the machine-specific and | ||
7939 | non-machine-specific parts of the arguments. | ||
7940 | |||
7941 | :term:`TEST_QEMUBOOT_TIMEOUT` | ||
7942 | The time in seconds allowed for an image to boot before automated | ||
7943 | runtime tests begin to run against an image. The default timeout | ||
7944 | period to allow the boot process to reach the login prompt is 500 | ||
7945 | seconds. You can specify a different value in the ``local.conf`` | ||
7946 | file. | ||
7947 | |||
7948 | For more information on testing images, see the | ||
7949 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | ||
7950 | section in the Yocto Project Development Tasks Manual. | ||
7951 | |||
7952 | :term:`TEST_SERIALCONTROL_CMD` | ||
7953 | For automated hardware testing, specifies the command to use to | ||
7954 | connect to the serial console of the target machine under test. This | ||
7955 | command simply needs to connect to the serial console and forward | ||
7956 | that connection to standard input and output as any normal terminal | ||
7957 | program does. | ||
7958 | |||
7959 | For example, to use the Picocom terminal program on serial device | ||
7960 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: | ||
7961 | :: | ||
7962 | |||
7963 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | ||
7964 | |||
7965 | :term:`TEST_SERIALCONTROL_EXTRA_ARGS` | ||
7966 | For automated hardware testing, specifies additional arguments to | ||
7967 | pass through to the command specified in | ||
7968 | :term:`TEST_SERIALCONTROL_CMD`. Setting | ||
7969 | ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you | ||
7970 | wish, for example, to separate the machine-specific and | ||
7971 | non-machine-specific parts of the command. | ||
7972 | |||
7973 | :term:`TEST_SERVER_IP` | ||
7974 | The IP address of the build machine (host machine). This IP address | ||
7975 | is usually automatically detected. However, if detection fails, this | ||
7976 | variable needs to be set to the IP address of the build machine (i.e. | ||
7977 | where the build is taking place). | ||
7978 | |||
7979 | .. note:: | ||
7980 | |||
7981 | The ``TEST_SERVER_IP`` variable is only used for a small number of | ||
7982 | tests such as the "dnf" test suite, which needs to download packages | ||
7983 | from ``WORKDIR/oe-rootfs-repo``. | ||
7984 | |||
7985 | :term:`TEST_SUITES` | ||
7986 | An ordered list of tests (modules) to run against an image when | ||
7987 | performing automated runtime testing. | ||
7988 | |||
7989 | The OpenEmbedded build system provides a core set of tests that can | ||
7990 | be used against images. | ||
7991 | |||
7992 | .. note:: | ||
7993 | |||
7994 | Currently, there is only support for running these tests under | ||
7995 | QEMU. | ||
7996 | |||
7997 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add | ||
7998 | your own tests to the list of tests by appending ``TEST_SUITES`` as | ||
7999 | follows: | ||
8000 | :: | ||
8001 | |||
8002 | TEST_SUITES_append = " mytest" | ||
8003 | |||
8004 | Alternatively, you can | ||
8005 | provide the "auto" option to have all applicable tests run against | ||
8006 | the image. | ||
8007 | :: | ||
8008 | |||
8009 | TEST_SUITES_append = " auto" | ||
8010 | |||
8011 | Using this option causes the | ||
8012 | build system to automatically run tests that are applicable to the | ||
8013 | image. Tests that are not applicable are skipped. | ||
8014 | |||
8015 | The order in which tests are run is important. Tests that depend on | ||
8016 | another test must appear later in the list than the test on which | ||
8017 | they depend. For example, if you append the list of tests with two | ||
8018 | tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on | ||
8019 | ``test_A``, then you must order the tests as follows: | ||
8020 | :: | ||
8021 | |||
8022 | TEST_SUITES = "test_A test_B" | ||
8023 | |||
8024 | For more information on testing images, see the | ||
8025 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | ||
8026 | section in the Yocto Project Development Tasks Manual. | ||
8027 | |||
8028 | :term:`TEST_TARGET` | ||
8029 | Specifies the target controller to use when running tests against a | ||
8030 | test image. The default controller to use is "qemu": | ||
8031 | :: | ||
8032 | |||
8033 | TEST_TARGET = "qemu" | ||
8034 | |||
8035 | A target controller is a class that defines how an image gets | ||
8036 | deployed on a target and how a target is started. A layer can extend | ||
8037 | the controllers by adding a module in the layer's | ||
8038 | ``/lib/oeqa/controllers`` directory and by inheriting the | ||
8039 | ``BaseTarget`` class, which is an abstract class that cannot be used | ||
8040 | as a value of ``TEST_TARGET``. | ||
8041 | |||
8042 | You can provide the following arguments with ``TEST_TARGET``: | ||
8043 | |||
8044 | - *"qemu":* Boots a QEMU image and runs the tests. See the | ||
8045 | ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section | ||
8046 | in the Yocto Project Development Tasks Manual for more | ||
8047 | information. | ||
8048 | |||
8049 | - *"simpleremote":* Runs the tests on target hardware that is | ||
8050 | already up and running. The hardware can be on the network or it | ||
8051 | can be a device running an image on QEMU. You must also set | ||
8052 | :term:`TEST_TARGET_IP` when you use | ||
8053 | "simpleremote". | ||
8054 | |||
8055 | .. note:: | ||
8056 | |||
8057 | This argument is defined in | ||
8058 | ``meta/lib/oeqa/controllers/simpleremote.py``. | ||
8059 | |||
8060 | For information on running tests on hardware, see the | ||
8061 | ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`" | ||
8062 | section in the Yocto Project Development Tasks Manual. | ||
8063 | |||
8064 | :term:`TEST_TARGET_IP` | ||
8065 | The IP address of your hardware under test. The ``TEST_TARGET_IP`` | ||
8066 | variable has no effect when :term:`TEST_TARGET` is | ||
8067 | set to "qemu". | ||
8068 | |||
8069 | When you specify the IP address, you can also include a port. Here is | ||
8070 | an example: | ||
8071 | :: | ||
8072 | |||
8073 | TEST_TARGET_IP = "192.168.1.4:2201" | ||
8074 | |||
8075 | Specifying a port is | ||
8076 | useful when SSH is started on a non-standard port or in cases when | ||
8077 | your hardware under test is behind a firewall or network that is not | ||
8078 | directly accessible from your host and you need to do port address | ||
8079 | translation. | ||
8080 | |||
8081 | :term:`TESTIMAGE_AUTO` | ||
8082 | Automatically runs the series of automated tests for images when an | ||
8083 | image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes | ||
8084 | any image that successfully builds to automatically boot under QEMU. | ||
8085 | Using the variable also adds in dependencies so that any SDK for | ||
8086 | which testing is requested is automatically built first. | ||
8087 | |||
8088 | These tests are written in Python making use of the ``unittest`` | ||
8089 | module, and the majority of them run commands on the target system | ||
8090 | over ``ssh``. You can set this variable to "1" in your ``local.conf`` | ||
8091 | file in the :term:`Build Directory` to have the | ||
8092 | OpenEmbedded build system automatically run these tests after an | ||
8093 | image successfully builds: | ||
8094 | |||
8095 | TESTIMAGE_AUTO = "1" | ||
8096 | |||
8097 | For more information | ||
8098 | on enabling, running, and writing these tests, see the | ||
8099 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | ||
8100 | section in the Yocto Project Development Tasks Manual and the | ||
8101 | ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. | ||
8102 | |||
8103 | :term:`THISDIR` | ||
8104 | The directory in which the file BitBake is currently parsing is | ||
8105 | located. Do not manually set this variable. | ||
8106 | |||
8107 | :term:`TIME` | ||
8108 | The time the build was started. Times appear using the hour, minute, | ||
8109 | and second (HMS) format (e.g. "140159" for one minute and fifty-nine | ||
8110 | seconds past 1400 hours). | ||
8111 | |||
8112 | :term:`TMPDIR` | ||
8113 | This variable is the base directory the OpenEmbedded build system | ||
8114 | uses for all build output and intermediate files (other than the | ||
8115 | shared state cache). By default, the ``TMPDIR`` variable points to | ||
8116 | ``tmp`` within the :term:`Build Directory`. | ||
8117 | |||
8118 | If you want to establish this directory in a location other than the | ||
8119 | default, you can uncomment and edit the following statement in the | ||
8120 | ``conf/local.conf`` file in the :term:`Source Directory`: | ||
8121 | :: | ||
8122 | |||
8123 | #TMPDIR = "${TOPDIR}/tmp" | ||
8124 | |||
8125 | An example use for this scenario is to set ``TMPDIR`` to a local disk, | ||
8126 | which does not use NFS, while having the Build Directory use NFS. | ||
8127 | |||
8128 | The filesystem used by ``TMPDIR`` must have standard filesystem | ||
8129 | semantics (i.e. mixed-case files are unique, POSIX file locking, and | ||
8130 | persistent inodes). Due to various issues with NFS and bugs in some | ||
8131 | implementations, NFS does not meet this minimum requirement. | ||
8132 | Consequently, ``TMPDIR`` cannot be on NFS. | ||
8133 | |||
8134 | :term:`TOOLCHAIN_HOST_TASK` | ||
8135 | This variable lists packages the OpenEmbedded build system uses when | ||
8136 | building an SDK, which contains a cross-development environment. The | ||
8137 | packages specified by this variable are part of the toolchain set | ||
8138 | that runs on the :term:`SDKMACHINE`, and each | ||
8139 | package should usually have the prefix ``nativesdk-``. For example, | ||
8140 | consider the following command when building an SDK: | ||
8141 | :: | ||
8142 | |||
8143 | $ bitbake -c populate_sdk imagename | ||
8144 | |||
8145 | In this case, a default list of packages is | ||
8146 | set in this variable, but you can add additional packages to the | ||
8147 | list. See the | ||
8148 | ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section | ||
8149 | in the Yocto Project Application Development and the Extensible | ||
8150 | Software Development Kit (eSDK) manual for more information. | ||
8151 | |||
8152 | For background information on cross-development toolchains in the | ||
8153 | Yocto Project development environment, see the | ||
8154 | ":ref:`sdk-manual/intro:the cross-development toolchain`" | ||
8155 | section in the Yocto Project Overview and Concepts Manual. For | ||
8156 | information on setting up a cross-development environment, see the | ||
8157 | :doc:`/sdk-manual/index` manual. | ||
8158 | |||
8159 | :term:`TOOLCHAIN_OUTPUTNAME` | ||
8160 | This variable defines the name used for the toolchain output. The | ||
8161 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets | ||
8162 | the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: | ||
8163 | :: | ||
8164 | |||
8165 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" | ||
8166 | |||
8167 | See | ||
8168 | the :term:`SDK_NAME` and | ||
8169 | :term:`SDK_VERSION` variables for additional | ||
8170 | information. | ||
8171 | |||
8172 | :term:`TOOLCHAIN_TARGET_TASK` | ||
8173 | This variable lists packages the OpenEmbedded build system uses when | ||
8174 | it creates the target part of an SDK (i.e. the part built for the | ||
8175 | target hardware), which includes libraries and headers. Use this | ||
8176 | variable to add individual packages to the part of the SDK that runs | ||
8177 | on the target. See the | ||
8178 | ":ref:`sdk-manual/appendix-customizing-standard:adding individual packages to the standard sdk`" section | ||
8179 | in the Yocto Project Application Development and the Extensible | ||
8180 | Software Development Kit (eSDK) manual for more information. | ||
8181 | |||
8182 | For background information on cross-development toolchains in the | ||
8183 | Yocto Project development environment, see the | ||
8184 | ":ref:`sdk-manual/intro:the cross-development toolchain`" | ||
8185 | section in the Yocto Project Overview and Concepts Manual. For | ||
8186 | information on setting up a cross-development environment, see the | ||
8187 | :doc:`/sdk-manual/index` manual. | ||
8188 | |||
8189 | :term:`TOPDIR` | ||
8190 | The top-level :term:`Build Directory`. BitBake | ||
8191 | automatically sets this variable when you initialize your build | ||
8192 | environment using :ref:`structure-core-script`. | ||
8193 | |||
8194 | :term:`TRANSLATED_TARGET_ARCH` | ||
8195 | A sanitized version of :term:`TARGET_ARCH`. This | ||
8196 | variable is used where the architecture is needed in a value where | ||
8197 | underscores are not allowed, for example within package filenames. In | ||
8198 | this case, dash characters replace any underscore characters used in | ||
8199 | ``TARGET_ARCH``. | ||
8200 | |||
8201 | Do not edit this variable. | ||
8202 | |||
8203 | :term:`TUNE_ARCH` | ||
8204 | The GNU canonical architecture for a specific architecture (i.e. | ||
8205 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses | ||
8206 | this value to setup configuration. | ||
8207 | |||
8208 | ``TUNE_ARCH`` definitions are specific to a given architecture. The | ||
8209 | definitions can be a single static definition, or can be dynamically | ||
8210 | adjusted. You can see details for a given CPU family by looking at | ||
8211 | the architecture's ``README`` file. For example, the | ||
8212 | ``meta/conf/machine/include/mips/README`` file in the | ||
8213 | :term:`Source Directory` provides information for | ||
8214 | ``TUNE_ARCH`` specific to the ``mips`` architecture. | ||
8215 | |||
8216 | ``TUNE_ARCH`` is tied closely to | ||
8217 | :term:`TARGET_ARCH`, which defines the target | ||
8218 | machine's architecture. The BitBake configuration file | ||
8219 | (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: | ||
8220 | :: | ||
8221 | |||
8222 | TARGET_ARCH = "${TUNE_ARCH}" | ||
8223 | |||
8224 | The following list, which is by no means complete since architectures | ||
8225 | are configurable, shows supported machine architectures: | ||
8226 | |||
8227 | - arm | ||
8228 | - i586 | ||
8229 | - x86_64 | ||
8230 | - powerpc | ||
8231 | - powerpc64 | ||
8232 | - mips | ||
8233 | - mipsel | ||
8234 | |||
8235 | :term:`TUNE_ASARGS` | ||
8236 | Specifies architecture-specific assembler flags for the target | ||
8237 | system. The set of flags is based on the selected tune features. | ||
8238 | ``TUNE_ASARGS`` is set using the tune include files, which are | ||
8239 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8240 | through :term:`TUNE_FEATURES`. For example, the | ||
8241 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | ||
8242 | for the x86 architecture as follows: | ||
8243 | :: | ||
8244 | |||
8245 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" | ||
8246 | |||
8247 | .. note:: | ||
8248 | |||
8249 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8250 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8251 | supply its own set of flags). | ||
8252 | |||
8253 | :term:`TUNE_CCARGS` | ||
8254 | Specifies architecture-specific C compiler flags for the target | ||
8255 | system. The set of flags is based on the selected tune features. | ||
8256 | ``TUNE_CCARGS`` is set using the tune include files, which are | ||
8257 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8258 | through :term:`TUNE_FEATURES`. | ||
8259 | |||
8260 | .. note:: | ||
8261 | |||
8262 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8263 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8264 | supply its own set of flags). | ||
8265 | |||
8266 | :term:`TUNE_FEATURES` | ||
8267 | Features used to "tune" a compiler for optimal use given a specific | ||
8268 | processor. The features are defined within the tune files and allow | ||
8269 | arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on | ||
8270 | the features. | ||
8271 | |||
8272 | The OpenEmbedded build system verifies the features to be sure they | ||
8273 | are not conflicting and that they are supported. | ||
8274 | |||
8275 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines | ||
8276 | ``TUNE_FEATURES`` as follows: | ||
8277 | :: | ||
8278 | |||
8279 | TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" | ||
8280 | |||
8281 | See the :term:`DEFAULTTUNE` variable for more information. | ||
8282 | |||
8283 | :term:`TUNE_LDARGS` | ||
8284 | Specifies architecture-specific linker flags for the target system. | ||
8285 | The set of flags is based on the selected tune features. | ||
8286 | ``TUNE_LDARGS`` is set using the tune include files, which are | ||
8287 | typically under ``meta/conf/machine/include/`` and are influenced | ||
8288 | through :term:`TUNE_FEATURES`. For example, the | ||
8289 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | ||
8290 | for the x86 architecture as follows: | ||
8291 | :: | ||
8292 | |||
8293 | TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" | ||
8294 | |||
8295 | .. note:: | ||
8296 | |||
8297 | Board Support Packages (BSPs) select the tune. The selected tune, | ||
8298 | in turn, affects the tune variables themselves (i.e. the tune can | ||
8299 | supply its own set of flags). | ||
8300 | |||
8301 | :term:`TUNE_PKGARCH` | ||
8302 | The package architecture understood by the packaging system to define | ||
8303 | the architecture, ABI, and tuning of output packages. The specific | ||
8304 | tune is defined using the "_tune" override as follows: | ||
8305 | :: | ||
8306 | |||
8307 | TUNE_PKGARCH_tune-tune = "tune" | ||
8308 | |||
8309 | These tune-specific package architectures are defined in the machine | ||
8310 | include files. Here is an example of the "core2-32" tuning as used in | ||
8311 | the ``meta/conf/machine/include/tune-core2.inc`` file: | ||
8312 | :: | ||
8313 | |||
8314 | TUNE_PKGARCH_tune-core2-32 = "core2-32" | ||
8315 | |||
8316 | :term:`TUNEABI` | ||
8317 | An underlying Application Binary Interface (ABI) used by a particular | ||
8318 | tuning in a given toolchain layer. Providers that use prebuilt | ||
8319 | libraries can use the ``TUNEABI``, | ||
8320 | :term:`TUNEABI_OVERRIDE`, and | ||
8321 | :term:`TUNEABI_WHITELIST` variables to check | ||
8322 | compatibility of tunings against their selection of libraries. | ||
8323 | |||
8324 | If ``TUNEABI`` is undefined, then every tuning is allowed. See the | ||
8325 | :ref:`sanity <ref-classes-sanity>` class to see how the variable is | ||
8326 | used. | ||
8327 | |||
8328 | :term:`TUNEABI_OVERRIDE` | ||
8329 | If set, the OpenEmbedded system ignores the | ||
8330 | :term:`TUNEABI_WHITELIST` variable. | ||
8331 | Providers that use prebuilt libraries can use the | ||
8332 | ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and | ||
8333 | :term:`TUNEABI` variables to check compatibility of a | ||
8334 | tuning against their selection of libraries. | ||
8335 | |||
8336 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8337 | variable is used. | ||
8338 | |||
8339 | :term:`TUNEABI_WHITELIST` | ||
8340 | A whitelist of permissible :term:`TUNEABI` values. If | ||
8341 | ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers | ||
8342 | that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, | ||
8343 | :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` | ||
8344 | variables to check compatibility of a tuning against their selection | ||
8345 | of libraries. | ||
8346 | |||
8347 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8348 | variable is used. | ||
8349 | |||
8350 | :term:`TUNECONFLICTS[feature]` | ||
8351 | Specifies CPU or Application Binary Interface (ABI) tuning features | ||
8352 | that conflict with feature. | ||
8353 | |||
8354 | Known tuning conflicts are specified in the machine include files in | ||
8355 | the :term:`Source Directory`. Here is an example from | ||
8356 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file | ||
8357 | that lists the "o32" and "n64" features as conflicting with the "n32" | ||
8358 | feature: | ||
8359 | :: | ||
8360 | |||
8361 | TUNECONFLICTS[n32] = "o32 n64" | ||
8362 | |||
8363 | :term:`TUNEVALID[feature]` | ||
8364 | Specifies a valid CPU or Application Binary Interface (ABI) tuning | ||
8365 | feature. The specified feature is stored as a flag. Valid features | ||
8366 | are specified in the machine include files (e.g. | ||
8367 | ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example | ||
8368 | from that file: | ||
8369 | :: | ||
8370 | |||
8371 | TUNEVALID[bigendian] = "Enable big-endian mode." | ||
8372 | |||
8373 | See the machine include files in the :term:`Source Directory` | ||
8374 | for these features. | ||
8375 | |||
8376 | :term:`UBOOT_CONFIG` | ||
8377 | Configures the :term:`UBOOT_MACHINE` and can | ||
8378 | also define :term:`IMAGE_FSTYPES` for individual | ||
8379 | cases. | ||
8380 | |||
8381 | Following is an example from the ``meta-fsl-arm`` layer. :: | ||
8382 | |||
8383 | UBOOT_CONFIG ??= "sd" | ||
8384 | UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" | ||
8385 | UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" | ||
8386 | UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" | ||
8387 | UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" | ||
8388 | |||
8389 | In this example, "sd" is selected as the configuration of the possible four for the | ||
8390 | ``UBOOT_MACHINE``. The "sd" configuration defines | ||
8391 | "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the | ||
8392 | "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image. | ||
8393 | |||
8394 | For more information on how the ``UBOOT_CONFIG`` is handled, see the | ||
8395 | :ref:`uboot-config <ref-classes-uboot-config>` | ||
8396 | class. | ||
8397 | |||
8398 | :term:`UBOOT_DTB_LOADADDRESS` | ||
8399 | Specifies the load address for the dtb image used by U-boot. During FIT | ||
8400 | image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in | ||
8401 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify | ||
8402 | the load address to be used in | ||
8403 | creating the dtb sections of Image Tree Source for the FIT image. | ||
8404 | |||
8405 | :term:`UBOOT_DTBO_LOADADDRESS` | ||
8406 | Specifies the load address for the dtbo image used by U-boot. During FIT | ||
8407 | image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in | ||
8408 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in | ||
8409 | creating the dtbo sections of Image Tree Source for the FIT image. | ||
8410 | |||
8411 | :term:`UBOOT_ENTRYPOINT` | ||
8412 | Specifies the entry point for the U-Boot image. During U-Boot image | ||
8413 | creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a | ||
8414 | command-line parameter to the ``uboot-mkimage`` utility. | ||
8415 | |||
8416 | :term:`UBOOT_LOADADDRESS` | ||
8417 | Specifies the load address for the U-Boot image. During U-Boot image | ||
8418 | creation, the ``UBOOT_LOADADDRESS`` variable is passed as a | ||
8419 | command-line parameter to the ``uboot-mkimage`` utility. | ||
8420 | |||
8421 | :term:`UBOOT_LOCALVERSION` | ||
8422 | Appends a string to the name of the local version of the U-Boot | ||
8423 | image. For example, assuming the version of the U-Boot image built | ||
8424 | was "2013.10", the full version string reported by U-Boot would be | ||
8425 | "2013.10-yocto" given the following statement: | ||
8426 | :: | ||
8427 | |||
8428 | UBOOT_LOCALVERSION = "-yocto" | ||
8429 | |||
8430 | :term:`UBOOT_MACHINE` | ||
8431 | Specifies the value passed on the ``make`` command line when building | ||
8432 | a U-Boot image. The value indicates the target platform | ||
8433 | configuration. You typically set this variable from the machine | ||
8434 | configuration file (i.e. ``conf/machine/machine_name.conf``). | ||
8435 | |||
8436 | Please see the "Selection of Processor Architecture and Board Type" | ||
8437 | section in the U-Boot README for valid values for this variable. | ||
8438 | |||
8439 | :term:`UBOOT_MAKE_TARGET` | ||
8440 | Specifies the target called in the ``Makefile``. The default target | ||
8441 | is "all". | ||
8442 | |||
8443 | :term:`UBOOT_MKIMAGE_DTCOPTS` | ||
8444 | Options for the device tree compiler passed to mkimage '-D' | ||
8445 | feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class. | ||
8446 | |||
8447 | :term:`UBOOT_RD_ENTRYPOINT` | ||
8448 | Specifies the entrypoint for the RAM disk image. | ||
8449 | During FIT image creation, the | ||
8450 | ``UBOOT_RD_ENTRYPOINT`` variable is used | ||
8451 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | ||
8452 | entrypoint to be used in creating the Image Tree Source for | ||
8453 | the FIT image. | ||
8454 | |||
8455 | :term:`UBOOT_RD_LOADADDRESS` | ||
8456 | Specifies the load address for the RAM disk image. | ||
8457 | During FIT image creation, the | ||
8458 | ``UBOOT_RD_LOADADDRESS`` variable is used | ||
8459 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | ||
8460 | load address to be used in creating the Image Tree Source for | ||
8461 | the FIT image. | ||
8462 | |||
8463 | :term:`UBOOT_SIGN_ENABLE` | ||
8464 | Enable signing of FIT image. The default value is "0". | ||
8465 | |||
8466 | :term:`UBOOT_SIGN_KEYDIR` | ||
8467 | Location of the directory containing the RSA key and | ||
8468 | certificate used for signing FIT image. | ||
8469 | |||
8470 | :term:`UBOOT_SIGN_KEYNAME` | ||
8471 | The name of keys used for signing U-boot FIT image stored in | ||
8472 | :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt | ||
8473 | certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have | ||
8474 | :term:`UBOOT_SIGN_KEYNAME` set to "dev". | ||
8475 | |||
8476 | :term:`UBOOT_SUFFIX` | ||
8477 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` | ||
8478 | has a ``.sb`` extension. | ||
8479 | |||
8480 | The default U-Boot extension is ``.bin`` | ||
8481 | |||
8482 | :term:`UBOOT_TARGET` | ||
8483 | Specifies the target used for building U-Boot. The target is passed | ||
8484 | directly as part of the "make" command (e.g. SPL and AIS). If you do | ||
8485 | not specifically set this variable, the OpenEmbedded build process | ||
8486 | passes and uses "all" for the target during the U-Boot building | ||
8487 | process. | ||
8488 | |||
8489 | :term:`UNKNOWN_CONFIGURE_WHITELIST` | ||
8490 | Specifies a list of options that, if reported by the configure script | ||
8491 | as being invalid, should not generate a warning during the | ||
8492 | :ref:`ref-tasks-configure` task. Normally, invalid | ||
8493 | configure options are simply not passed to the configure script (e.g. | ||
8494 | should be removed from :term:`EXTRA_OECONF` or | ||
8495 | :term:`PACKAGECONFIG_CONFARGS`). | ||
8496 | However, common options, for example, exist that are passed to all | ||
8497 | configure scripts at a class level that might not be valid for some | ||
8498 | configure scripts. It follows that no benefit exists in seeing a | ||
8499 | warning about these options. For these cases, the options are added | ||
8500 | to ``UNKNOWN_CONFIGURE_WHITELIST``. | ||
8501 | |||
8502 | The configure arguments check that uses | ||
8503 | ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the | ||
8504 | :ref:`insane <ref-classes-insane>` class and is only enabled if the | ||
8505 | recipe inherits the :ref:`autotools <ref-classes-autotools>` class. | ||
8506 | |||
8507 | :term:`UPDATERCPN` | ||
8508 | For recipes inheriting the | ||
8509 | :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` | ||
8510 | specifies the package that contains the initscript that is enabled. | ||
8511 | |||
8512 | The default value is "${PN}". Given that almost all recipes that | ||
8513 | install initscripts package them in the main package for the recipe, | ||
8514 | you rarely need to set this variable in individual recipes. | ||
8515 | |||
8516 | :term:`UPSTREAM_CHECK_GITTAGREGEX` | ||
8517 | You can perform a per-recipe check for what the latest upstream | ||
8518 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | ||
8519 | the recipe source code is provided from Git repositories, the | ||
8520 | OpenEmbedded build system determines the latest upstream version by | ||
8521 | picking the latest tag from the list of all repository tags. | ||
8522 | |||
8523 | You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a | ||
8524 | regular expression to filter only the relevant tags should the | ||
8525 | default filter not work correctly. | ||
8526 | :: | ||
8527 | |||
8528 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" | ||
8529 | |||
8530 | :term:`UPSTREAM_CHECK_REGEX` | ||
8531 | Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different | ||
8532 | regular expression instead of the default one when the package | ||
8533 | checking system is parsing the page found using | ||
8534 | :term:`UPSTREAM_CHECK_URI`. | ||
8535 | :: | ||
8536 | |||
8537 | UPSTREAM_CHECK_REGEX = "package_regex" | ||
8538 | |||
8539 | :term:`UPSTREAM_CHECK_URI` | ||
8540 | You can perform a per-recipe check for what the latest upstream | ||
8541 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | ||
8542 | the source code is provided from tarballs, the latest version is | ||
8543 | determined by fetching the directory listing where the tarball is and | ||
8544 | attempting to find a later tarball. When this approach does not work, | ||
8545 | you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that | ||
8546 | contains the link to the latest tarball. | ||
8547 | :: | ||
8548 | |||
8549 | UPSTREAM_CHECK_URI = "recipe_url" | ||
8550 | |||
8551 | :term:`USE_DEVFS` | ||
8552 | Determines if ``devtmpfs`` is used for ``/dev`` population. The | ||
8553 | default value used for ``USE_DEVFS`` is "1" when no value is | ||
8554 | specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a | ||
8555 | statically populated ``/dev`` directory. | ||
8556 | |||
8557 | See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in | ||
8558 | the Yocto Project Development Tasks Manual for information on how to | ||
8559 | use this variable. | ||
8560 | |||
8561 | :term:`USE_VT` | ||
8562 | When using | ||
8563 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | ||
8564 | determines whether or not to run a | ||
8565 | `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any | ||
8566 | virtual terminals in order to enable logging in through those | ||
8567 | terminals. | ||
8568 | |||
8569 | The default value used for ``USE_VT`` is "1" when no default value is | ||
8570 | specifically set. Typically, you would set ``USE_VT`` to "0" in the | ||
8571 | machine configuration file for machines that do not have a graphical | ||
8572 | display attached and therefore do not need virtual terminal | ||
8573 | functionality. | ||
8574 | |||
8575 | :term:`USER_CLASSES` | ||
8576 | A list of classes to globally inherit. These classes are used by the | ||
8577 | OpenEmbedded build system to enable extra features (e.g. | ||
8578 | ``buildstats``, ``image-mklibs``, and so forth). | ||
8579 | |||
8580 | The default list is set in your ``local.conf`` file: | ||
8581 | :: | ||
8582 | |||
8583 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | ||
8584 | |||
8585 | For more information, see | ||
8586 | ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. | ||
8587 | |||
8588 | :term:`USERADD_ERROR_DYNAMIC` | ||
8589 | If set to ``error``, forces the OpenEmbedded build system to produce | ||
8590 | an error if the user identification (``uid``) and group | ||
8591 | identification (``gid``) values are not defined in any of the files | ||
8592 | listed in :term:`USERADD_UID_TABLES` and | ||
8593 | :term:`USERADD_GID_TABLES`. If set to | ||
8594 | ``warn``, a warning will be issued instead. | ||
8595 | |||
8596 | The default behavior for the build system is to dynamically apply | ||
8597 | ``uid`` and ``gid`` values. Consequently, the | ||
8598 | ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan | ||
8599 | on using statically assigned ``gid`` and ``uid`` values, you should | ||
8600 | set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` | ||
8601 | file as follows: | ||
8602 | :: | ||
8603 | |||
8604 | USERADD_ERROR_DYNAMIC = "error" | ||
8605 | |||
8606 | Overriding the | ||
8607 | default behavior implies you are going to also take steps to set | ||
8608 | static ``uid`` and ``gid`` values through use of the | ||
8609 | :term:`USERADDEXTENSION`, | ||
8610 | :term:`USERADD_UID_TABLES`, and | ||
8611 | :term:`USERADD_GID_TABLES` variables. | ||
8612 | |||
8613 | .. note:: | ||
8614 | |||
8615 | There is a difference in behavior between setting | ||
8616 | ``USERADD_ERROR_DYNAMIC`` to ``error`` and setting it to ``warn``. | ||
8617 | When it is set to ``warn``, the build system will report a warning for | ||
8618 | every undefined ``uid`` and ``gid`` in any recipe. But when it is set | ||
8619 | to ``error``, it will only report errors for recipes that are actually | ||
8620 | built. | ||
8621 | This saves you from having to add static IDs for recipes that you | ||
8622 | know will never be built. | ||
8623 | |||
8624 | :term:`USERADD_GID_TABLES` | ||
8625 | Specifies a password file to use for obtaining static group | ||
8626 | identification (``gid``) values when the OpenEmbedded build system | ||
8627 | adds a group to the system during package installation. | ||
8628 | |||
8629 | When applying static group identification (``gid``) values, the | ||
8630 | OpenEmbedded build system looks in :term:`BBPATH` for a | ||
8631 | ``files/group`` file and then applies those ``uid`` values. Set the | ||
8632 | variable as follows in your ``local.conf`` file: | ||
8633 | :: | ||
8634 | |||
8635 | |||
8636 | USERADD_GID_TABLES = "files/group" | ||
8637 | |||
8638 | .. note:: | ||
8639 | |||
8640 | Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" | ||
8641 | causes the build system to use static ``gid`` values. | ||
8642 | |||
8643 | :term:`USERADD_PACKAGES` | ||
8644 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
8645 | this variable specifies the individual packages within the recipe | ||
8646 | that require users and/or groups to be added. | ||
8647 | |||
8648 | You must set this variable if the recipe inherits the class. For | ||
8649 | example, the following enables adding a user for the main package in | ||
8650 | a recipe: | ||
8651 | :: | ||
8652 | |||
8653 | USERADD_PACKAGES = "${PN}" | ||
8654 | |||
8655 | .. note:: | ||
8656 | |||
8657 | It follows that if you are going to use the ``USERADD_PACKAGES`` | ||
8658 | variable, you need to set one or more of the :term:`USERADD_PARAM`, | ||
8659 | :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. | ||
8660 | |||
8661 | :term:`USERADD_PARAM` | ||
8662 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | ||
8663 | this variable specifies for a package what parameters should pass to | ||
8664 | the ``useradd`` command if you add a user to the system when the | ||
8665 | package is installed. | ||
8666 | |||
8667 | Here is an example from the ``dbus`` recipe: | ||
8668 | :: | ||
8669 | |||
8670 | USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ | ||
8671 | --no-create-home --shell /bin/false \ | ||
8672 | --user-group messagebus" | ||
8673 | |||
8674 | For information on the | ||
8675 | standard Linux shell command ``useradd``, see | ||
8676 | http://linux.die.net/man/8/useradd. | ||
8677 | |||
8678 | :term:`USERADD_UID_TABLES` | ||
8679 | Specifies a password file to use for obtaining static user | ||
8680 | identification (``uid``) values when the OpenEmbedded build system | ||
8681 | adds a user to the system during package installation. | ||
8682 | |||
8683 | When applying static user identification (``uid``) values, the | ||
8684 | OpenEmbedded build system looks in :term:`BBPATH` for a | ||
8685 | ``files/passwd`` file and then applies those ``uid`` values. Set the | ||
8686 | variable as follows in your ``local.conf`` file: | ||
8687 | :: | ||
8688 | |||
8689 | USERADD_UID_TABLES = "files/passwd" | ||
8690 | |||
8691 | .. note:: | ||
8692 | |||
8693 | Setting the :term:`USERADDEXTENSION` variable to "useradd-staticids" | ||
8694 | causes the build system to use static ``uid`` values. | ||
8695 | |||
8696 | :term:`USERADDEXTENSION` | ||
8697 | When set to "useradd-staticids", causes the OpenEmbedded build system | ||
8698 | to base all user and group additions on a static ``passwd`` and | ||
8699 | ``group`` files found in :term:`BBPATH`. | ||
8700 | |||
8701 | To use static user identification (``uid``) and group identification | ||
8702 | (``gid``) values, set the variable as follows in your ``local.conf`` | ||
8703 | file: USERADDEXTENSION = "useradd-staticids" | ||
8704 | |||
8705 | .. note:: | ||
8706 | |||
8707 | Setting this variable to use static ``uid`` and ``gid`` | ||
8708 | values causes the OpenEmbedded build system to employ the | ||
8709 | :ref:`ref-classes-useradd` class. | ||
8710 | |||
8711 | If you use static ``uid`` and ``gid`` information, you must also | ||
8712 | specify the ``files/passwd`` and ``files/group`` files by setting the | ||
8713 | :term:`USERADD_UID_TABLES` and | ||
8714 | :term:`USERADD_GID_TABLES` variables. | ||
8715 | Additionally, you should also set the | ||
8716 | :term:`USERADD_ERROR_DYNAMIC` variable. | ||
8717 | |||
8718 | :term:`VOLATILE_LOG_DIR` | ||
8719 | Specifies the persistence of the target's ``/var/log`` directory, | ||
8720 | which is used to house postinstall target log files. | ||
8721 | |||
8722 | By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the | ||
8723 | file is not persistent. You can override this setting by setting the | ||
8724 | variable to "no" to make the log directory persistent. | ||
8725 | |||
8726 | :term:`WARN_QA` | ||
8727 | Specifies the quality assurance checks whose failures are reported as | ||
8728 | warnings by the OpenEmbedded build system. You set this variable in | ||
8729 | your distribution configuration file. For a list of the checks you | ||
8730 | can control with this variable, see the | ||
8731 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | ||
8732 | |||
8733 | :term:`WKS_FILE` | ||
8734 | Specifies the location of the Wic kickstart file that is used by the | ||
8735 | OpenEmbedded build system to create a partitioned image | ||
8736 | (image\ ``.wic``). For information on how to create a partitioned | ||
8737 | image, see the | ||
8738 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | ||
8739 | section in the Yocto Project Development Tasks Manual. For details on | ||
8740 | the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. | ||
8741 | |||
8742 | :term:`WKS_FILE_DEPENDS` | ||
8743 | When placed in the recipe that builds your image, this variable lists | ||
8744 | build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only | ||
8745 | applicable when Wic images are active (i.e. when | ||
8746 | :term:`IMAGE_FSTYPES` contains entries related | ||
8747 | to Wic). If your recipe does not create Wic images, the variable has | ||
8748 | no effect. | ||
8749 | |||
8750 | The ``WKS_FILE_DEPENDS`` variable is similar to the | ||
8751 | :term:`DEPENDS` variable. When you use the variable in | ||
8752 | your recipe that builds the Wic image, dependencies you list in the | ||
8753 | ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. | ||
8754 | |||
8755 | With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to | ||
8756 | specify a list of additional dependencies (e.g. native tools, | ||
8757 | bootloaders, and so forth), that are required to build Wic images. | ||
8758 | Following is an example: | ||
8759 | :: | ||
8760 | |||
8761 | WKS_FILE_DEPENDS = "some-native-tool" | ||
8762 | |||
8763 | In the | ||
8764 | previous example, some-native-tool would be replaced with an actual | ||
8765 | native tool on which the build would depend. | ||
8766 | |||
8767 | :term:`WORKDIR` | ||
8768 | The pathname of the work directory in which the OpenEmbedded build | ||
8769 | system builds a recipe. This directory is located within the | ||
8770 | :term:`TMPDIR` directory structure and is specific to | ||
8771 | the recipe being built and the system for which it is being built. | ||
8772 | |||
8773 | The ``WORKDIR`` directory is defined as follows: | ||
8774 | :: | ||
8775 | |||
8776 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | ||
8777 | |||
8778 | The actual directory depends on several things: | ||
8779 | |||
8780 | - :term:`TMPDIR`: The top-level build output directory | ||
8781 | - :term:`MULTIMACH_TARGET_SYS`: The target system identifier | ||
8782 | - :term:`PN`: The recipe name | ||
8783 | - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which | ||
8784 | is usually the case for most recipes, then `EXTENDPE` is blank) | ||
8785 | - :term:`PV`: The recipe version | ||
8786 | - :term:`PR`: The recipe revision | ||
8787 | |||
8788 | As an example, assume a Source Directory top-level folder name | ||
8789 | ``poky``, a default Build Directory at ``poky/build``, and a | ||
8790 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose | ||
8791 | your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work | ||
8792 | directory the build system uses to build the package would be as | ||
8793 | follows: | ||
8794 | :: | ||
8795 | |||
8796 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | ||
8797 | |||
8798 | :term:`XSERVER` | ||
8799 | Specifies the packages that should be installed to provide an X | ||
8800 | server and drivers for the current machine, assuming your image | ||
8801 | directly includes ``packagegroup-core-x11-xserver`` or, perhaps | ||
8802 | indirectly, includes "x11-base" in | ||
8803 | :term:`IMAGE_FEATURES`. | ||
8804 | |||
8805 | The default value of ``XSERVER``, if not specified in the machine | ||
8806 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". | ||
8807 | |||