diff options
Diffstat (limited to 'documentation/ref-manual/variables.rst')
-rw-r--r-- | documentation/ref-manual/variables.rst | 6307 |
1 files changed, 3773 insertions, 2534 deletions
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 2cb37b6a2b..3f37f42f21 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst | |||
@@ -17,6 +17,7 @@ system and gives an overview of their function and contents. | |||
17 | :term:`W <WARN_QA>` :term:`X <XSERVER>` | 17 | :term:`W <WARN_QA>` :term:`X <XSERVER>` |
18 | 18 | ||
19 | .. glossary:: | 19 | .. glossary:: |
20 | :sorted: | ||
20 | 21 | ||
21 | :term:`ABIEXTENSION` | 22 | :term:`ABIEXTENSION` |
22 | Extension to the Application Binary Interface (ABI) field of the GNU | 23 | Extension to the Application Binary Interface (ABI) field of the GNU |
@@ -24,8 +25,7 @@ system and gives an overview of their function and contents. | |||
24 | 25 | ||
25 | ABI extensions are set in the machine include files. For example, the | 26 | 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 | ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the |
27 | following extension: | 28 | following extension:: |
28 | :: | ||
29 | 29 | ||
30 | ABIEXTENSION = "eabi" | 30 | ABIEXTENSION = "eabi" |
31 | 31 | ||
@@ -37,12 +37,11 @@ system and gives an overview of their function and contents. | |||
37 | requirement on the existence of the package. | 37 | requirement on the existence of the package. |
38 | 38 | ||
39 | Like all package-controlling variables, you must always use them in | 39 | Like all package-controlling variables, you must always use them in |
40 | conjunction with a package name override, as in: | 40 | conjunction with a package name override, as in:: |
41 | :: | ||
42 | 41 | ||
43 | ALLOW_EMPTY_${PN} = "1" | 42 | ALLOW_EMPTY:${PN} = "1" |
44 | ALLOW_EMPTY_${PN}-dev = "1" | 43 | ALLOW_EMPTY:${PN}-dev = "1" |
45 | ALLOW_EMPTY_${PN}-staticdev = "1" | 44 | ALLOW_EMPTY:${PN}-staticdev = "1" |
46 | 45 | ||
47 | :term:`ALTERNATIVE` | 46 | :term:`ALTERNATIVE` |
48 | Lists commands in a package that need an alternative binary naming | 47 | Lists commands in a package that need an alternative binary naming |
@@ -51,25 +50,22 @@ system and gives an overview of their function and contents. | |||
51 | alternatives system to create a different binary naming scheme so the | 50 | alternatives system to create a different binary naming scheme so the |
52 | commands can co-exist. | 51 | commands can co-exist. |
53 | 52 | ||
54 | To use the variable, list out the package's commands that also exist | 53 | To use the variable, list out the package's commands that are also |
55 | as part of another package. For example, if the ``busybox`` package | 54 | provided by another package. For example, if the ``busybox`` package |
56 | has four commands that also exist as part of another package, you | 55 | has four such commands, you identify them as follows:: |
57 | identify them as follows: | ||
58 | :: | ||
59 | 56 | ||
60 | ALTERNATIVE_busybox = "sh sed test bracket" | 57 | ALTERNATIVE:busybox = "sh sed test bracket" |
61 | 58 | ||
62 | For more information on the alternatives system, see the | 59 | For more information on the alternatives system, see the |
63 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | 60 | ":ref:`ref-classes-update-alternatives`" |
64 | section. | 61 | section. |
65 | 62 | ||
66 | :term:`ALTERNATIVE_LINK_NAME` | 63 | :term:`ALTERNATIVE_LINK_NAME` |
67 | Used by the alternatives system to map duplicated commands to actual | 64 | Used by the alternatives system to map duplicated commands to actual |
68 | locations. For example, if the ``bracket`` command provided by the | 65 | locations. For example, if the ``bracket`` command provided by the |
69 | ``busybox`` package is duplicated through another package, you must | 66 | ``busybox`` package is duplicated through another package, you must |
70 | use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual | 67 | use the :term:`ALTERNATIVE_LINK_NAME` variable to specify the actual |
71 | location: | 68 | location:: |
72 | :: | ||
73 | 69 | ||
74 | ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" | 70 | ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" |
75 | 71 | ||
@@ -78,10 +74,10 @@ system and gives an overview of their function and contents. | |||
78 | 74 | ||
79 | .. note:: | 75 | .. note:: |
80 | 76 | ||
81 | If ``ALTERNATIVE_LINK_NAME`` is not defined, it defaults to ``${bindir}/name``. | 77 | If :term:`ALTERNATIVE_LINK_NAME` is not defined, it defaults to ``${bindir}/name``. |
82 | 78 | ||
83 | For more information on the alternatives system, see the | 79 | For more information on the alternatives system, see the |
84 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | 80 | ":ref:`ref-classes-update-alternatives`" |
85 | section. | 81 | section. |
86 | 82 | ||
87 | :term:`ALTERNATIVE_PRIORITY` | 83 | :term:`ALTERNATIVE_PRIORITY` |
@@ -90,15 +86,14 @@ system and gives an overview of their function and contents. | |||
90 | default regardless of the command name or package, a default for | 86 | default regardless of the command name or package, a default for |
91 | specific duplicated commands regardless of the package, or a default | 87 | specific duplicated commands regardless of the package, or a default |
92 | for specific commands tied to particular packages. Here are the | 88 | for specific commands tied to particular packages. Here are the |
93 | available syntax forms: | 89 | available syntax forms:: |
94 | :: | ||
95 | 90 | ||
96 | ALTERNATIVE_PRIORITY = "priority" | 91 | ALTERNATIVE_PRIORITY = "priority" |
97 | ALTERNATIVE_PRIORITY[name] = "priority" | 92 | ALTERNATIVE_PRIORITY[name] = "priority" |
98 | ALTERNATIVE_PRIORITY_pkg[name] = "priority" | 93 | ALTERNATIVE_PRIORITY_pkg[name] = "priority" |
99 | 94 | ||
100 | For more information on the alternatives system, see the | 95 | For more information on the alternatives system, see the |
101 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | 96 | ":ref:`ref-classes-update-alternatives`" |
102 | section. | 97 | section. |
103 | 98 | ||
104 | :term:`ALTERNATIVE_TARGET` | 99 | :term:`ALTERNATIVE_TARGET` |
@@ -107,8 +102,7 @@ system and gives an overview of their function and contents. | |||
107 | default location for all duplicated commands regardless of the | 102 | default location for all duplicated commands regardless of the |
108 | command name or package, a default for specific duplicated commands | 103 | command name or package, a default for specific duplicated commands |
109 | regardless of the package, or a default for specific commands tied to | 104 | regardless of the package, or a default for specific commands tied to |
110 | particular packages. Here are the available syntax forms: | 105 | particular packages. Here are the available syntax forms:: |
111 | :: | ||
112 | 106 | ||
113 | ALTERNATIVE_TARGET = "target" | 107 | ALTERNATIVE_TARGET = "target" |
114 | ALTERNATIVE_TARGET[name] = "target" | 108 | ALTERNATIVE_TARGET[name] = "target" |
@@ -116,11 +110,11 @@ system and gives an overview of their function and contents. | |||
116 | 110 | ||
117 | .. note:: | 111 | .. note:: |
118 | 112 | ||
119 | If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value | 113 | If :term:`ALTERNATIVE_TARGET` is not defined, it inherits the value |
120 | from the :term:`ALTERNATIVE_LINK_NAME` variable. | 114 | from the :term:`ALTERNATIVE_LINK_NAME` variable. |
121 | 115 | ||
122 | If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the | 116 | If :term:`ALTERNATIVE_LINK_NAME` and :term:`ALTERNATIVE_TARGET` are the |
123 | same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" | 117 | same, the target for :term:`ALTERNATIVE_TARGET` has "``.{BPN}``" |
124 | appended to it. | 118 | appended to it. |
125 | 119 | ||
126 | Finally, if the file referenced has not been renamed, the | 120 | Finally, if the file referenced has not been renamed, the |
@@ -129,38 +123,34 @@ system and gives an overview of their function and contents. | |||
129 | task while retaining support for the command if necessary. | 123 | task while retaining support for the command if necessary. |
130 | 124 | ||
131 | For more information on the alternatives system, see the | 125 | For more information on the alternatives system, see the |
132 | ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" | 126 | ":ref:`ref-classes-update-alternatives`" section. |
133 | section. | ||
134 | 127 | ||
135 | :term:`ANY_OF_DISTRO_FEATURES` | 128 | :term:`ANY_OF_DISTRO_FEATURES` |
136 | When inheriting the | 129 | When inheriting the :ref:`ref-classes-features_check` |
137 | :ref:`features_check <ref-classes-features_check>` | ||
138 | class, this variable identifies a list of distribution features where | 130 | class, this variable identifies a list of distribution features where |
139 | at least one must be enabled in the current configuration in order | 131 | 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, | 132 | for the OpenEmbedded build system to build the recipe. In other words, |
141 | if none of the features listed in ``ANY_OF_DISTRO_FEATURES`` | 133 | if none of the features listed in :term:`ANY_OF_DISTRO_FEATURES` |
142 | appear in ``DISTRO_FEATURES`` within the current configuration, then | 134 | appear in :term:`DISTRO_FEATURES` within the current configuration, then |
143 | the recipe will be skipped, and if the build system attempts to build | 135 | the recipe will be skipped, and if the build system attempts to build |
144 | the recipe then an error will be triggered. | 136 | the recipe then an error will be triggered. |
145 | |||
146 | 137 | ||
147 | :term:`APPEND` | 138 | :term:`APPEND` |
148 | An override list of append strings for each target specified with | 139 | An override list of append strings for each target specified with |
149 | :term:`LABELS`. | 140 | :term:`LABELS`. |
150 | 141 | ||
151 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | 142 | See the :ref:`ref-classes-grub-efi` class for more |
152 | information on how this variable is used. | 143 | information on how this variable is used. |
153 | 144 | ||
154 | :term:`AR` | 145 | :term:`AR` |
155 | The minimal command and arguments used to run ``ar``. | 146 | The minimal command and arguments used to run ``ar``. |
156 | 147 | ||
157 | :term:`ARCHIVER_MODE` | 148 | :term:`ARCHIVER_MODE` |
158 | When used with the :ref:`archiver <ref-classes-archiver>` class, | 149 | When used with the :ref:`ref-classes-archiver` class, |
159 | determines the type of information used to create a released archive. | 150 | determines the type of information used to create a released archive. |
160 | You can use this variable to create archives of patched source, | 151 | You can use this variable to create archives of patched source, |
161 | original source, configured source, and so forth by employing the | 152 | original source, configured source, and so forth by employing the |
162 | following variable flags (varflags): | 153 | following variable flags (varflags):: |
163 | :: | ||
164 | 154 | ||
165 | ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. | 155 | ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files. |
166 | ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. | 156 | ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default. |
@@ -182,7 +172,7 @@ system and gives an overview of their function and contents. | |||
182 | attempt to build. Instead, BitBake assumes these recipes have already | 172 | attempt to build. Instead, BitBake assumes these recipes have already |
183 | been built. | 173 | been built. |
184 | 174 | ||
185 | In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native | 175 | In OpenEmbedded-Core, :term:`ASSUME_PROVIDED` mostly specifies native |
186 | tools that should not be built. An example is ``git-native``, which | 176 | 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 | 177 | when specified, allows for the Git binary from the host to be used |
188 | rather than building ``git-native``. | 178 | rather than building ``git-native``. |
@@ -193,65 +183,47 @@ system and gives an overview of their function and contents. | |||
193 | system. Separate multiple entries using spaces. | 183 | system. Separate multiple entries using spaces. |
194 | 184 | ||
195 | As an example, use the following form to add an ``shlib`` provider of | 185 | As an example, use the following form to add an ``shlib`` provider of |
196 | shlibname in packagename with the optional version: | 186 | shlibname in packagename with the optional version:: |
197 | :: | ||
198 | 187 | ||
199 | shlibname:packagename[_version] | 188 | shlibname:packagename[_version] |
200 | 189 | ||
201 | Here is an example that adds a shared library named ``libEGL.so.1`` | 190 | Here is an example that adds a shared library named ``libEGL.so.1`` |
202 | as being provided by the ``libegl-implementation`` package: | 191 | as being provided by the ``libegl-implementation`` package:: |
203 | :: | ||
204 | 192 | ||
205 | ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" | 193 | ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" |
206 | 194 | ||
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` | 195 | :term:`AUTO_LIBNAME_PKGS` |
212 | When the :ref:`debian <ref-classes-debian>` class is inherited, | 196 | When the :ref:`ref-classes-debian` class is inherited, |
213 | which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which | 197 | which is the default behavior, :term:`AUTO_LIBNAME_PKGS` specifies which |
214 | packages should be checked for libraries and renamed according to | 198 | packages should be checked for libraries and renamed according to |
215 | Debian library package naming. | 199 | Debian library package naming. |
216 | 200 | ||
217 | The default value is "${PACKAGES}", which causes the debian class to | 201 | The default value is "${PACKAGES}", which causes the |
218 | act on all packages that are explicitly generated by the recipe. | 202 | :ref:`ref-classes-debian` class to act on all packages that are |
219 | 203 | explicitly generated by the recipe. | |
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 | 204 | ||
225 | :term:`AUTOREV` | 205 | :term:`AUTOREV` |
226 | When ``SRCREV`` is set to the value of this variable, it specifies to | 206 | When :term:`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: | 207 | use the latest source revision in the repository. Here is an example:: |
228 | :: | ||
229 | 208 | ||
230 | SRCREV = "${AUTOREV}" | 209 | SRCREV = "${AUTOREV}" |
231 | 210 | ||
232 | If you use the previous statement to retrieve the latest version of | 211 | If you use the previous statement to retrieve the latest version of |
233 | software, you need to be sure :term:`PV` contains | 212 | software, you need to be sure :term:`PV` contains |
234 | ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you | 213 | ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you have a kernel |
235 | have a kernel recipe that inherits the | 214 | recipe that inherits the :ref:`ref-classes-kernel` class and you |
236 | :ref:`kernel <ref-classes-kernel>` class and you use the previous | 215 | use the previous statement. In this example, ``${SRCPV}`` does not |
237 | statement. In this example, ``${SRCPV}`` does not automatically get | 216 | automatically get into :term:`PV`. Consequently, you need to change |
238 | into ``PV``. Consequently, you need to change ``PV`` in your recipe | 217 | :term:`PV` in your recipe so that it does contain ``${SRCPV}``. |
239 | so that it does contain ``${SRCPV}``. | ||
240 | 218 | ||
241 | For more information see the | 219 | For more information see the |
242 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | 220 | ":ref:`dev-manual/packages:automatically incrementing a package version number`" |
243 | section in the Yocto Project Development Tasks Manual. | 221 | section in the Yocto Project Development Tasks Manual. |
244 | 222 | ||
245 | :term:`AVAILABLE_LICENSES` | 223 | :term:`AUTO_SYSLINUXMENU` |
246 | List of licenses found in the directories specified by | 224 | Enables creating an automatic menu for the syslinux bootloader. You |
247 | :term:`COMMON_LICENSE_DIR` and | 225 | must set this variable in your recipe. The |
248 | :term:`LICENSE_PATH`. | 226 | :ref:`ref-classes-syslinux` class checks this variable. |
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 | 227 | ||
256 | :term:`AVAILTUNES` | 228 | :term:`AVAILTUNES` |
257 | The list of defined CPU and Application Binary Interface (ABI) | 229 | The list of defined CPU and Application Binary Interface (ABI) |
@@ -261,26 +233,36 @@ system and gives an overview of their function and contents. | |||
261 | The list simply presents the tunes that are available. Not all tunes | 233 | The list simply presents the tunes that are available. Not all tunes |
262 | may be compatible with a particular machine configuration, or with | 234 | may be compatible with a particular machine configuration, or with |
263 | each other in a | 235 | each other in a |
264 | :ref:`Multilib <dev-manual/common-tasks:combining multiple versions of library files into one image>` | 236 | :ref:`Multilib <dev-manual/libraries:combining multiple versions of library files into one image>` |
265 | configuration. | 237 | configuration. |
266 | 238 | ||
267 | To add a tune to the list, be sure to append it with spaces using the | 239 | 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 | 240 | "+=" BitBake operator. Do not simply replace the list by using the |
269 | "=" operator. See the | 241 | "=" operator. See the |
270 | ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake | 242 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:basic syntax`" section in the BitBake |
271 | User Manual for more information. | 243 | User Manual for more information. |
272 | 244 | ||
245 | :term:`AZ_SAS` | ||
246 | Azure Storage Shared Access Signature, when using the | ||
247 | :ref:`Azure Storage fetcher (az://) <bitbake-user-manual/bitbake-user-manual-fetching:fetchers>` | ||
248 | This variable can be defined to be used by the fetcher to authenticate | ||
249 | and gain access to non-public artifacts:: | ||
250 | |||
251 | AZ_SAS = ""se=2021-01-01&sp=r&sv=2018-11-09&sr=c&skoid=<skoid>&sig=<signature>"" | ||
252 | |||
253 | For more information see Microsoft's Azure Storage documentation at | ||
254 | https://docs.microsoft.com/en-us/azure/storage/common/storage-sas-overview | ||
255 | |||
273 | :term:`B` | 256 | :term:`B` |
274 | The directory within the :term:`Build Directory` in | 257 | The directory within the :term:`Build Directory` in which the |
275 | which the OpenEmbedded build system places generated objects during a | 258 | OpenEmbedded build system places generated objects during a recipe's |
276 | recipe's build process. By default, this directory is the same as the | 259 | build process. By default, this directory is the same as the |
277 | :term:`S` directory, which is defined as: | 260 | :term:`S` directory, which is defined as:: |
278 | :: | ||
279 | 261 | ||
280 | S = "${WORKDIR}/${BP}" | 262 | S = "${WORKDIR}/${BP}" |
281 | 263 | ||
282 | You can separate the (``S``) directory and the directory pointed to | 264 | You can separate the (:term:`S`) directory and the directory pointed to |
283 | by the ``B`` variable. Most Autotools-based recipes support | 265 | by the :term:`B` variable. Most Autotools-based recipes support |
284 | separating these directories. The build system defaults to using | 266 | separating these directories. The build system defaults to using |
285 | separate directories for ``gcc`` and some kernel recipes. | 267 | separate directories for ``gcc`` and some kernel recipes. |
286 | 268 | ||
@@ -289,17 +271,15 @@ system and gives an overview of their function and contents. | |||
289 | packages are packages installed only through the | 271 | packages are packages installed only through the |
290 | :term:`RRECOMMENDS` variable. You can prevent any | 272 | :term:`RRECOMMENDS` variable. You can prevent any |
291 | of these "recommended" packages from being installed by listing them | 273 | of these "recommended" packages from being installed by listing them |
292 | with the ``BAD_RECOMMENDATIONS`` variable: | 274 | with the :term:`BAD_RECOMMENDATIONS` variable:: |
293 | :: | ||
294 | 275 | ||
295 | BAD_RECOMMENDATIONS = "package_name package_name package_name ..." | 276 | BAD_RECOMMENDATIONS = "package_name package_name package_name ..." |
296 | 277 | ||
297 | You can set this variable globally in your ``local.conf`` file or you | 278 | 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 | 279 | can attach it to a specific image recipe by using the recipe name |
299 | override: | 280 | override:: |
300 | :: | ||
301 | 281 | ||
302 | BAD_RECOMMENDATIONS_pn-target_image = "package_name" | 282 | BAD_RECOMMENDATIONS:pn-target_image = "package_name" |
303 | 283 | ||
304 | It is important to realize that if you choose to not install packages | 284 | 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 | 285 | using this variable and some other packages are dependent on them |
@@ -307,8 +287,8 @@ system and gives an overview of their function and contents. | |||
307 | variable), the OpenEmbedded build system ignores your request and | 287 | variable), the OpenEmbedded build system ignores your request and |
308 | will install the packages to avoid dependency errors. | 288 | will install the packages to avoid dependency errors. |
309 | 289 | ||
310 | Support for this variable exists only when using the IPK and RPM | 290 | This variable is supported only when using the IPK and RPM |
311 | packaging backend. Support does not exist for DEB. | 291 | packaging backends. DEB is not supported. |
312 | 292 | ||
313 | See the :term:`NO_RECOMMENDATIONS` and the | 293 | See the :term:`NO_RECOMMENDATIONS` and the |
314 | :term:`PACKAGE_EXCLUDE` variables for related | 294 | :term:`PACKAGE_EXCLUDE` variables for related |
@@ -316,12 +296,12 @@ system and gives an overview of their function and contents. | |||
316 | 296 | ||
317 | :term:`BASE_LIB` | 297 | :term:`BASE_LIB` |
318 | The library directory name for the CPU or Application Binary | 298 | The library directory name for the CPU or Application Binary |
319 | Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib | 299 | Interface (ABI) tune. The :term:`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`" | 300 | context. See the ":ref:`dev-manual/libraries:combining multiple versions of library files into one image`" |
321 | section in the Yocto Project Development Tasks Manual for information | 301 | section in the Yocto Project Development Tasks Manual for information |
322 | on Multilib. | 302 | on Multilib. |
323 | 303 | ||
324 | The ``BASE_LIB`` variable is defined in the machine include files in | 304 | The :term:`BASE_LIB` variable is defined in the machine include files in |
325 | the :term:`Source Directory`. If Multilib is not | 305 | the :term:`Source Directory`. If Multilib is not |
326 | being used, the value defaults to "lib". | 306 | being used, the value defaults to "lib". |
327 | 307 | ||
@@ -331,16 +311,15 @@ system and gives an overview of their function and contents. | |||
331 | 311 | ||
332 | :term:`BB_ALLOWED_NETWORKS` | 312 | :term:`BB_ALLOWED_NETWORKS` |
333 | Specifies a space-delimited list of hosts that the fetcher is allowed | 313 | Specifies a space-delimited list of hosts that the fetcher is allowed |
334 | to use to obtain the required source code. Following are | 314 | to use to obtain the required source code. Here are |
335 | considerations surrounding this variable: | 315 | considerations surrounding this variable: |
336 | 316 | ||
337 | - This host list is only used if ``BB_NO_NETWORK`` is either not set | 317 | - This host list is only used if :term:`BB_NO_NETWORK` is either not set |
338 | or set to "0". | 318 | or set to "0". |
339 | 319 | ||
340 | - Limited support for wildcard matching against the beginning of | 320 | - There is limited support for wildcard matching against the beginning of |
341 | host names exists. For example, the following setting matches | 321 | host names. For example, the following setting matches |
342 | ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. | 322 | ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``:: |
343 | :: | ||
344 | 323 | ||
345 | BB_ALLOWED_NETWORKS = "*.gnu.org" | 324 | BB_ALLOWED_NETWORKS = "*.gnu.org" |
346 | 325 | ||
@@ -359,14 +338,29 @@ system and gives an overview of their function and contents. | |||
359 | 338 | ||
360 | - Attempts to access networks not in the host list cause a failure. | 339 | - Attempts to access networks not in the host list cause a failure. |
361 | 340 | ||
362 | Using ``BB_ALLOWED_NETWORKS`` in conjunction with | 341 | Using :term:`BB_ALLOWED_NETWORKS` in conjunction with |
363 | :term:`PREMIRRORS` is very useful. Adding the host | 342 | :term:`PREMIRRORS` is very useful. Adding the host |
364 | you want to use to ``PREMIRRORS`` results in the source code being | 343 | you want to use to :term:`PREMIRRORS` results in the source code being |
365 | fetched from an allowed location and avoids raising an error when a | 344 | fetched from an allowed location and avoids raising an error when a |
366 | host that is not allowed is in a :term:`SRC_URI` | 345 | host that is not allowed is in a :term:`SRC_URI` |
367 | statement. This is because the fetcher does not attempt to use the | 346 | statement. This is because the fetcher does not attempt to use the |
368 | host listed in ``SRC_URI`` after a successful fetch from the | 347 | host listed in :term:`SRC_URI` after a successful fetch from the |
369 | ``PREMIRRORS`` occurs. | 348 | :term:`PREMIRRORS` occurs. |
349 | |||
350 | :term:`BB_BASEHASH_IGNORE_VARS` | ||
351 | See :term:`bitbake:BB_BASEHASH_IGNORE_VARS` in the BitBake manual. | ||
352 | |||
353 | :term:`BB_CACHEDIR` | ||
354 | See :term:`bitbake:BB_CACHEDIR` in the BitBake manual. | ||
355 | |||
356 | :term:`BB_CHECK_SSL_CERTS` | ||
357 | See :term:`bitbake:BB_CHECK_SSL_CERTS` in the BitBake manual. | ||
358 | |||
359 | :term:`BB_CONSOLELOG` | ||
360 | See :term:`bitbake:BB_CONSOLELOG` in the BitBake manual. | ||
361 | |||
362 | :term:`BB_CURRENTTASK` | ||
363 | See :term:`bitbake:BB_CURRENTTASK` in the BitBake manual. | ||
370 | 364 | ||
371 | :term:`BB_DANGLINGAPPENDS_WARNONLY` | 365 | :term:`BB_DANGLINGAPPENDS_WARNONLY` |
372 | Defines how BitBake handles situations where an append file | 366 | Defines how BitBake handles situations where an append file |
@@ -382,17 +376,22 @@ system and gives an overview of their function and contents. | |||
382 | 376 | ||
383 | You can change the default behavior by setting this variable to "1", | 377 | 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 | 378 | "yes", or "true" in your ``local.conf`` file, which is located in the |
385 | :term:`Build Directory`: Here is an example: | 379 | :term:`Build Directory`: Here is an example:: |
386 | :: | ||
387 | 380 | ||
388 | BB_DANGLINGAPPENDS_WARNONLY = "1" | 381 | BB_DANGLINGAPPENDS_WARNONLY = "1" |
389 | 382 | ||
383 | :term:`BB_DEFAULT_TASK` | ||
384 | See :term:`bitbake:BB_DEFAULT_TASK` in the BitBake manual. | ||
385 | |||
386 | :term:`BB_DEFAULT_UMASK` | ||
387 | See :term:`bitbake:BB_DEFAULT_UMASK` in the BitBake manual. | ||
388 | |||
390 | :term:`BB_DISKMON_DIRS` | 389 | :term:`BB_DISKMON_DIRS` |
391 | Monitors disk space and available inodes during the build and allows | 390 | Monitors disk space and available inodes during the build and allows |
392 | you to control the build based on these parameters. | 391 | you to control the build based on these parameters. |
393 | 392 | ||
394 | Disk space monitoring is disabled by default. To enable monitoring, | 393 | Disk space monitoring is disabled by default. To enable monitoring, |
395 | add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file | 394 | add the :term:`BB_DISKMON_DIRS` variable to your ``conf/local.conf`` file |
396 | found in the :term:`Build Directory`. Use the | 395 | found in the :term:`Build Directory`. Use the |
397 | following form: | 396 | following form: |
398 | 397 | ||
@@ -403,7 +402,7 @@ system and gives an overview of their function and contents. | |||
403 | where: | 402 | where: |
404 | 403 | ||
405 | action is: | 404 | action is: |
406 | ABORT: Immediately abort the build when | 405 | ABORT: Immediately stop the build when |
407 | a threshold is broken. | 406 | a threshold is broken. |
408 | STOPTASKS: Stop the build after the currently | 407 | STOPTASKS: Stop the build after the currently |
409 | executing tasks have finished when | 408 | executing tasks have finished when |
@@ -432,8 +431,7 @@ system and gives an overview of their function and contents. | |||
432 | not specify G, M, or K, Kbytes is assumed by | 431 | not specify G, M, or K, Kbytes is assumed by |
433 | default. Do not use GB, MB, or KB. | 432 | default. Do not use GB, MB, or KB. |
434 | 433 | ||
435 | Here are some examples: | 434 | Here are some examples:: |
436 | :: | ||
437 | 435 | ||
438 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" | 436 | BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K" |
439 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" | 437 | BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G" |
@@ -442,13 +440,13 @@ system and gives an overview of their function and contents. | |||
442 | The first example works only if you also provide the | 440 | The first example works only if you also provide the |
443 | :term:`BB_DISKMON_WARNINTERVAL` | 441 | :term:`BB_DISKMON_WARNINTERVAL` |
444 | variable in the ``conf/local.conf``. This example causes the build | 442 | variable in the ``conf/local.conf``. This example causes the build |
445 | system to immediately abort when either the disk space in | 443 | system to immediately stop when either the disk space in |
446 | ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops | 444 | ``${TMPDIR}`` drops below 1 Gbyte or the available free inodes drops |
447 | below 100 Kbytes. Because two directories are provided with the | 445 | below 100 Kbytes. Because two directories are provided with the |
448 | variable, the build system also issue a warning when the disk space | 446 | 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 | 447 | in the ``${SSTATE_DIR}`` directory drops below 1 Gbyte or the number |
450 | of free inodes drops below 100 Kbytes. Subsequent warnings are issued | 448 | of free inodes drops below 100 Kbytes. Subsequent warnings are issued |
451 | during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` | 449 | during intervals as defined by the :term:`BB_DISKMON_WARNINTERVAL` |
452 | variable. | 450 | variable. |
453 | 451 | ||
454 | The second example stops the build after all currently executing | 452 | The second example stops the build after all currently executing |
@@ -456,7 +454,7 @@ system and gives an overview of their function and contents. | |||
456 | directory drops below 1 Gbyte. No disk monitoring occurs for the free | 454 | directory drops below 1 Gbyte. No disk monitoring occurs for the free |
457 | inodes in this case. | 455 | inodes in this case. |
458 | 456 | ||
459 | The final example immediately aborts the build when the number of | 457 | The final example immediately stops the build when the number of |
460 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No | 458 | free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No |
461 | disk space monitoring for the directory itself occurs in this case. | 459 | disk space monitoring for the directory itself occurs in this case. |
462 | 460 | ||
@@ -465,16 +463,15 @@ system and gives an overview of their function and contents. | |||
465 | intervals, define the variable in your ``conf/local.conf`` file in | 463 | intervals, define the variable in your ``conf/local.conf`` file in |
466 | the :term:`Build Directory`. | 464 | the :term:`Build Directory`. |
467 | 465 | ||
468 | If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you | 466 | If you are going to use the :term:`BB_DISKMON_WARNINTERVAL` variable, you |
469 | must also use the :term:`BB_DISKMON_DIRS` | 467 | must also use the :term:`BB_DISKMON_DIRS` |
470 | variable and define its action as "WARN". During the build, | 468 | variable and define its action as "WARN". During the build, |
471 | subsequent warnings are issued each time disk space or number of free | 469 | subsequent warnings are issued each time disk space or number of free |
472 | inodes further reduces by the respective interval. | 470 | inodes further reduces by the respective interval. |
473 | 471 | ||
474 | If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you | 472 | If you do not provide a :term:`BB_DISKMON_WARNINTERVAL` variable and you |
475 | do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk | 473 | do use :term:`BB_DISKMON_DIRS` with the "WARN" action, the disk |
476 | monitoring interval defaults to the following: | 474 | monitoring interval defaults to the following:: |
477 | :: | ||
478 | 475 | ||
479 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 476 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
480 | 477 | ||
@@ -497,8 +494,7 @@ system and gives an overview of their function and contents. | |||
497 | G, M, or K for Gbytes, Mbytes, or Kbytes, | 494 | G, M, or K for Gbytes, Mbytes, or Kbytes, |
498 | respectively. You cannot use GB, MB, or KB. | 495 | respectively. You cannot use GB, MB, or KB. |
499 | 496 | ||
500 | Here is an example: | 497 | Here is an example:: |
501 | :: | ||
502 | 498 | ||
503 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" | 499 | BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" |
504 | BB_DISKMON_WARNINTERVAL = "50M,5K" | 500 | BB_DISKMON_WARNINTERVAL = "50M,5K" |
@@ -511,6 +507,18 @@ system and gives an overview of their function and contents. | |||
511 | a respective interval is reached beyond the initial warning (i.e. 1 | 507 | a respective interval is reached beyond the initial warning (i.e. 1 |
512 | Gbytes and 100 Kbytes). | 508 | Gbytes and 100 Kbytes). |
513 | 509 | ||
510 | :term:`BB_ENV_PASSTHROUGH` | ||
511 | See :term:`bitbake:BB_ENV_PASSTHROUGH` in the BitBake manual. | ||
512 | |||
513 | :term:`BB_ENV_PASSTHROUGH_ADDITIONS` | ||
514 | See :term:`bitbake:BB_ENV_PASSTHROUGH_ADDITIONS` in the BitBake manual. | ||
515 | |||
516 | :term:`BB_FETCH_PREMIRRORONLY` | ||
517 | See :term:`bitbake:BB_FETCH_PREMIRRORONLY` in the BitBake manual. | ||
518 | |||
519 | :term:`BB_FILENAME` | ||
520 | See :term:`bitbake:BB_FILENAME` in the BitBake manual. | ||
521 | |||
514 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 522 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
515 | Causes tarballs of the source control repositories (e.g. Git | 523 | Causes tarballs of the source control repositories (e.g. Git |
516 | repositories), including metadata, to be placed in the | 524 | repositories), including metadata, to be placed in the |
@@ -518,8 +526,7 @@ system and gives an overview of their function and contents. | |||
518 | 526 | ||
519 | For performance reasons, creating and placing tarballs of these | 527 | For performance reasons, creating and placing tarballs of these |
520 | repositories is not the default action by the OpenEmbedded build | 528 | repositories is not the default action by the OpenEmbedded build |
521 | system. | 529 | system:: |
522 | :: | ||
523 | 530 | ||
524 | BB_GENERATE_MIRROR_TARBALLS = "1" | 531 | BB_GENERATE_MIRROR_TARBALLS = "1" |
525 | 532 | ||
@@ -527,72 +534,203 @@ system and gives an overview of their function and contents. | |||
527 | ``local.conf`` file in the :term:`Build Directory`. | 534 | ``local.conf`` file in the :term:`Build Directory`. |
528 | 535 | ||
529 | Once you have the tarballs containing your source files, you can | 536 | Once you have the tarballs containing your source files, you can |
530 | clean up your ``DL_DIR`` directory by deleting any Git or other | 537 | clean up your :term:`DL_DIR` directory by deleting any Git or other |
531 | source control work directories. | 538 | source control work directories. |
532 | 539 | ||
540 | :term:`BB_GENERATE_SHALLOW_TARBALLS` | ||
541 | See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual. | ||
542 | |||
543 | :term:`BB_GIT_SHALLOW` | ||
544 | See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual. | ||
545 | |||
546 | :term:`BB_GIT_SHALLOW_DEPTH` | ||
547 | See :term:`bitbake:BB_GIT_SHALLOW_DEPTH` in the BitBake manual. | ||
548 | |||
549 | :term:`BB_HASHCHECK_FUNCTION` | ||
550 | See :term:`bitbake:BB_HASHCHECK_FUNCTION` in the BitBake manual. | ||
551 | |||
552 | :term:`BB_HASHCONFIG_IGNORE_VARS` | ||
553 | See :term:`bitbake:BB_HASHCONFIG_IGNORE_VARS` in the BitBake manual. | ||
554 | |||
555 | :term:`BB_HASHSERVE` | ||
556 | See :term:`bitbake:BB_HASHSERVE` in the BitBake manual. | ||
557 | |||
558 | :term:`BB_HASHSERVE_UPSTREAM` | ||
559 | See :term:`bitbake:BB_HASHSERVE_UPSTREAM` in the BitBake manual. | ||
560 | |||
561 | :term:`BB_INVALIDCONF` | ||
562 | See :term:`bitbake:BB_INVALIDCONF` in the BitBake manual. | ||
563 | |||
564 | :term:`BB_LOADFACTOR_MAX` | ||
565 | The system load threshold above which BitBake will stop runnig extra | ||
566 | tasks. | ||
567 | |||
568 | :term:`BB_LOGCONFIG` | ||
569 | See :term:`bitbake:BB_LOGCONFIG` in the BitBake manual. | ||
570 | |||
571 | :term:`BB_LOGFMT` | ||
572 | See :term:`bitbake:BB_LOGFMT` in the BitBake manual. | ||
573 | |||
574 | :term:`BB_MULTI_PROVIDER_ALLOWED` | ||
575 | See :term:`bitbake:BB_MULTI_PROVIDER_ALLOWED` in the BitBake manual. | ||
576 | |||
577 | :term:`BB_NICE_LEVEL` | ||
578 | See :term:`bitbake:BB_NICE_LEVEL` in the BitBake manual. | ||
579 | |||
580 | :term:`BB_NO_NETWORK` | ||
581 | See :term:`bitbake:BB_NO_NETWORK` in the BitBake manual. | ||
582 | |||
583 | :term:`BB_NUMBER_PARSE_THREADS` | ||
584 | See :term:`bitbake:BB_NUMBER_PARSE_THREADS` in the BitBake manual. | ||
585 | |||
533 | :term:`BB_NUMBER_THREADS` | 586 | :term:`BB_NUMBER_THREADS` |
534 | The maximum number of tasks BitBake should run in parallel at any one | 587 | The maximum number of tasks BitBake should run in parallel at any one |
535 | time. The OpenEmbedded build system automatically configures this | 588 | time. The OpenEmbedded build system automatically configures this |
536 | variable to be equal to the number of cores on the build system. For | 589 | 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 | 590 | example, a system with a dual core processor that also uses |
538 | hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default | 591 | hyper-threading causes the :term:`BB_NUMBER_THREADS` variable to default |
539 | to "4". | 592 | to "4". |
540 | 593 | ||
541 | For single socket systems (i.e. one CPU), you should not have to | 594 | For single socket systems (i.e. one CPU), you should not have to |
542 | override this variable to gain optimal parallelism during builds. | 595 | override this variable to gain optimal parallelism during builds. |
543 | However, if you have very large systems that employ multiple physical | 596 | However, if you have very large systems that employ multiple physical |
544 | CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable | 597 | CPUs, you might want to make sure the :term:`BB_NUMBER_THREADS` variable |
545 | is not set higher than "20". | 598 | is not set higher than "20". |
546 | 599 | ||
547 | For more information on speeding up builds, see the | 600 | For more information on speeding up builds, see the |
548 | ":ref:`dev-manual/common-tasks:speeding up a build`" | 601 | ":ref:`dev-manual/speeding-up-build:speeding up a build`" |
549 | section in the Yocto Project Development Tasks Manual. | 602 | section in the Yocto Project Development Tasks Manual. |
550 | 603 | ||
604 | On the other hand, if your goal is to limit the amount of system | ||
605 | resources consumed by BitBake tasks, setting :term:`BB_NUMBER_THREADS` | ||
606 | to a number lower than the number of CPU threads in your machine | ||
607 | won't be sufficient. That's because each package will still be built | ||
608 | and installed through a number of parallel jobs specified by the | ||
609 | :term:`PARALLEL_MAKE` variable, which is by default the number of CPU | ||
610 | threads in your system, and is not impacted by the | ||
611 | :term:`BB_NUMBER_THREADS` value. | ||
612 | |||
613 | So, if you set :term:`BB_NUMBER_THREADS` to "1" but don't set | ||
614 | :term:`PARALLEL_MAKE`, most of your system resources will be consumed | ||
615 | anyway. | ||
616 | |||
617 | Therefore, if you intend to reduce the load of your build system by | ||
618 | setting :term:`BB_NUMBER_THREADS` to a relatively low value compared | ||
619 | to the number of CPU threads on your system, you should also set | ||
620 | :term:`PARALLEL_MAKE` to a similarly low value. | ||
621 | |||
622 | An alternative to using :term:`BB_NUMBER_THREADS` to keep the usage | ||
623 | of build system resources under control is to use the smarter | ||
624 | :term:`BB_PRESSURE_MAX_CPU`, :term:`BB_PRESSURE_MAX_IO` or | ||
625 | :term:`BB_PRESSURE_MAX_MEMORY` controls. They will prevent BitBake | ||
626 | from starting new tasks as long as thresholds are exceeded. Anyway, | ||
627 | as with :term:`BB_NUMBER_THREADS`, such controls won't prevent the | ||
628 | tasks already being run from using all CPU threads on the system | ||
629 | if :term:`PARALLEL_MAKE` is not set to a low value. | ||
630 | |||
631 | :term:`BB_ORIGENV` | ||
632 | See :term:`bitbake:BB_ORIGENV` in the BitBake manual. | ||
633 | |||
634 | :term:`BB_PRESERVE_ENV` | ||
635 | See :term:`bitbake:BB_PRESERVE_ENV` in the BitBake manual. | ||
636 | |||
637 | :term:`BB_PRESSURE_MAX_CPU` | ||
638 | See :term:`bitbake:BB_PRESSURE_MAX_CPU` in the BitBake manual. | ||
639 | |||
640 | :term:`BB_PRESSURE_MAX_IO` | ||
641 | See :term:`bitbake:BB_PRESSURE_MAX_IO` in the BitBake manual. | ||
642 | |||
643 | :term:`BB_PRESSURE_MAX_MEMORY` | ||
644 | See :term:`bitbake:BB_PRESSURE_MAX_MEMORY` in the BitBake manual. | ||
645 | |||
646 | :term:`BB_RUNFMT` | ||
647 | See :term:`bitbake:BB_RUNFMT` in the BitBake manual. | ||
648 | |||
649 | :term:`BB_RUNTASK` | ||
650 | See :term:`bitbake:BB_RUNTASK` in the BitBake manual. | ||
651 | |||
652 | :term:`BB_SCHEDULER` | ||
653 | See :term:`bitbake:BB_SCHEDULER` in the BitBake manual. | ||
654 | |||
655 | :term:`BB_SCHEDULERS` | ||
656 | See :term:`bitbake:BB_SCHEDULERS` in the BitBake manual. | ||
657 | |||
551 | :term:`BB_SERVER_TIMEOUT` | 658 | :term:`BB_SERVER_TIMEOUT` |
552 | Specifies the time (in seconds) after which to unload the BitBake | 659 | Specifies the time (in seconds) after which to unload the BitBake |
553 | server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how | 660 | server due to inactivity. Set :term:`BB_SERVER_TIMEOUT` to determine how |
554 | long the BitBake server stays resident between invocations. | 661 | long the BitBake server stays resident between invocations. |
555 | 662 | ||
556 | For example, the following statement in your ``local.conf`` file | 663 | For example, the following statement in your ``local.conf`` file |
557 | instructs the server to be unloaded after 20 seconds of inactivity: | 664 | instructs the server to be unloaded after 20 seconds of inactivity:: |
558 | :: | ||
559 | 665 | ||
560 | BB_SERVER_TIMEOUT = "20" | 666 | BB_SERVER_TIMEOUT = "20" |
561 | 667 | ||
562 | If you want the server to never be unloaded, | 668 | If you want the server to never be unloaded, |
563 | set ``BB_SERVER_TIMEOUT`` to "-1". | 669 | set :term:`BB_SERVER_TIMEOUT` to "-1". |
670 | |||
671 | :term:`BB_SETSCENE_DEPVALID` | ||
672 | See :term:`bitbake:BB_SETSCENE_DEPVALID` in the BitBake manual. | ||
673 | |||
674 | :term:`BB_SIGNATURE_EXCLUDE_FLAGS` | ||
675 | See :term:`bitbake:BB_SIGNATURE_EXCLUDE_FLAGS` in the BitBake manual. | ||
676 | |||
677 | :term:`BB_SIGNATURE_HANDLER` | ||
678 | See :term:`bitbake:BB_SIGNATURE_HANDLER` in the BitBake manual. | ||
679 | |||
680 | :term:`BB_SRCREV_POLICY` | ||
681 | See :term:`bitbake:BB_SRCREV_POLICY` in the BitBake manual. | ||
682 | |||
683 | :term:`BB_STRICT_CHECKSUM` | ||
684 | See :term:`bitbake:BB_STRICT_CHECKSUM` in the BitBake manual. | ||
685 | |||
686 | :term:`BB_TASK_IONICE_LEVEL` | ||
687 | See :term:`bitbake:BB_TASK_IONICE_LEVEL` in the BitBake manual. | ||
688 | |||
689 | :term:`BB_TASK_NICE_LEVEL` | ||
690 | See :term:`bitbake:BB_TASK_NICE_LEVEL` in the BitBake manual. | ||
691 | |||
692 | :term:`BB_TASKHASH` | ||
693 | See :term:`bitbake:BB_TASKHASH` in the BitBake manual. | ||
694 | |||
695 | :term:`BB_VERBOSE_LOGS` | ||
696 | See :term:`bitbake:BB_VERBOSE_LOGS` in the BitBake manual. | ||
697 | |||
698 | :term:`BB_WORKERCONTEXT` | ||
699 | See :term:`bitbake:BB_WORKERCONTEXT` in the BitBake manual. | ||
564 | 700 | ||
565 | :term:`BBCLASSEXTEND` | 701 | :term:`BBCLASSEXTEND` |
566 | Allows you to extend a recipe so that it builds variants of the | 702 | Allows you to extend a recipe so that it builds variants of the |
567 | software. Common variants for recipes exist such as "natives" like | 703 | software. There are common variants for recipes as "natives" like |
568 | ``quilt-native``, which is a copy of Quilt built to run on the build | 704 | ``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 | 705 | 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 | 706 | run on the build machine but produces binaries that run on the target |
571 | :term:`MACHINE`; "nativesdk", which targets the SDK | 707 | :term:`MACHINE`; ":ref:`ref-classes-nativesdk`", which |
572 | machine instead of ``MACHINE``; and "mulitlibs" in the form | 708 | targets the SDK machine instead of :term:`MACHINE`; and "mulitlibs" in |
573 | "``multilib:``\ multilib_name". | 709 | the form "``multilib:``\ multilib_name". |
574 | 710 | ||
575 | To build a different variant of the recipe with a minimal amount of | 711 | 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: | 712 | code, it usually is as simple as adding the following to your recipe:: |
577 | :: | ||
578 | 713 | ||
579 | BBCLASSEXTEND =+ "native nativesdk" | 714 | BBCLASSEXTEND =+ "native nativesdk" |
580 | BBCLASSEXTEND =+ "multilib:multilib_name" | 715 | BBCLASSEXTEND =+ "multilib:multilib_name" |
581 | 716 | ||
582 | .. note:: | 717 | .. note:: |
583 | 718 | ||
584 | Internally, the ``BBCLASSEXTEND`` mechanism generates recipe | 719 | Internally, the :term:`BBCLASSEXTEND` mechanism generates recipe |
585 | variants by rewriting variable values and applying overrides such | 720 | variants by rewriting variable values and applying overrides such |
586 | as ``_class-native``. For example, to generate a native version of | 721 | as ``:class-native``. For example, to generate a native version of |
587 | a recipe, a :term:`DEPENDS` on "foo" is rewritten | 722 | a recipe, a :term:`DEPENDS` on "foo" is rewritten |
588 | to a ``DEPENDS`` on "foo-native". | 723 | to a :term:`DEPENDS` on "foo-native". |
589 | 724 | ||
590 | Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. | 725 | Even when using :term:`BBCLASSEXTEND`, the recipe is only parsed once. |
591 | Parsing once adds some limitations. For example, it is not | 726 | Parsing once adds some limitations. For example, it is not |
592 | possible to include a different file depending on the variant, | 727 | possible to include a different file depending on the variant, |
593 | since ``include`` statements are processed when the recipe is | 728 | since ``include`` statements are processed when the recipe is |
594 | parsed. | 729 | parsed. |
595 | 730 | ||
731 | :term:`BBDEBUG` | ||
732 | See :term:`bitbake:BBDEBUG` in the BitBake manual. | ||
733 | |||
596 | :term:`BBFILE_COLLECTIONS` | 734 | :term:`BBFILE_COLLECTIONS` |
597 | Lists the names of configured layers. These names are used to find | 735 | Lists the names of configured layers. These names are used to find |
598 | the other ``BBFILE_*`` variables. Typically, each layer will append | 736 | the other ``BBFILE_*`` variables. Typically, each layer will append |
@@ -610,17 +748,17 @@ system and gives an overview of their function and contents. | |||
610 | This variable is useful in situations where the same recipe appears | 748 | This variable is useful in situations where the same recipe appears |
611 | in more than one layer. Setting this variable allows you to | 749 | in more than one layer. Setting this variable allows you to |
612 | prioritize a layer against other layers that contain the same recipe | 750 | prioritize a layer against other layers that contain the same recipe |
613 | - effectively letting you control the precedence for the multiple | 751 | --- effectively letting you control the precedence for the multiple |
614 | layers. The precedence established through this variable stands | 752 | layers. The precedence established through this variable stands |
615 | regardless of a recipe's version (:term:`PV` variable). For | 753 | 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 | 754 | example, a layer that has a recipe with a higher :term:`PV` value but for |
617 | which the ``BBFILE_PRIORITY`` is set to have a lower precedence still | 755 | which the :term:`BBFILE_PRIORITY` is set to have a lower precedence still |
618 | has a lower precedence. | 756 | has a lower precedence. |
619 | 757 | ||
620 | A larger value for the ``BBFILE_PRIORITY`` variable results in a | 758 | A larger value for the :term:`BBFILE_PRIORITY` variable results in a |
621 | higher precedence. For example, the value 6 has a higher precedence | 759 | higher precedence. For example, the value 6 has a higher precedence |
622 | than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable | 760 | than the value 5. If not specified, the :term:`BBFILE_PRIORITY` variable |
623 | is set based on layer dependencies (see the ``LAYERDEPENDS`` variable | 761 | is set based on layer dependencies (see the :term:`LAYERDEPENDS` variable |
624 | for more information. The default priority, if unspecified for a | 762 | for more information. The default priority, if unspecified for a |
625 | layer with no dependencies, is the lowest defined priority + 1 (or 1 | 763 | layer with no dependencies, is the lowest defined priority + 1 (or 1 |
626 | if no priorities are defined). | 764 | if no priorities are defined). |
@@ -635,7 +773,7 @@ system and gives an overview of their function and contents. | |||
635 | software. | 773 | software. |
636 | 774 | ||
637 | When specifying recipe files, you can pattern match using Python's | 775 | When specifying recipe files, you can pattern match using Python's |
638 | `glob <https://docs.python.org/3/library/glob.html>`_ syntax. | 776 | `glob <https://docs.python.org/3/library/glob.html>`__ syntax. |
639 | For details on the syntax, see the documentation by following the | 777 | For details on the syntax, see the documentation by following the |
640 | previous link. | 778 | previous link. |
641 | 779 | ||
@@ -643,15 +781,16 @@ system and gives an overview of their function and contents. | |||
643 | Activates content when identified layers are present. You identify | 781 | Activates content when identified layers are present. You identify |
644 | the layers by the collections that the layers define. | 782 | the layers by the collections that the layers define. |
645 | 783 | ||
646 | Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files | 784 | Use the :term:`BBFILES_DYNAMIC` variable to avoid ``.bbappend`` files |
647 | whose corresponding ``.bb`` file is in a layer that attempts to | 785 | whose corresponding ``.bb`` file is in a layer that attempts to |
648 | modify other layers through ``.bbappend`` but does not want to | 786 | modify other layers through ``.bbappend`` but does not want to |
649 | introduce a hard dependency on those other layers. | 787 | introduce a hard dependency on those other layers. |
650 | 788 | ||
651 | Use the following form for ``BBFILES_DYNAMIC``: | 789 | Use the following form for :term:`BBFILES_DYNAMIC`: |
652 | collection_name:filename_pattern The following example identifies two | 790 | ``collection_name:filename_pattern``. |
653 | collection names and two filename patterns: | 791 | |
654 | :: | 792 | The following example identifies two collection names and two |
793 | filename patterns:: | ||
655 | 794 | ||
656 | BBFILES_DYNAMIC += " \ | 795 | BBFILES_DYNAMIC += " \ |
657 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ | 796 | clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \ |
@@ -659,7 +798,7 @@ system and gives an overview of their function and contents. | |||
659 | " | 798 | " |
660 | 799 | ||
661 | This next example shows an error message that occurs because invalid | 800 | This next example shows an error message that occurs because invalid |
662 | entries are found, which cause parsing to abort: | 801 | entries are found, which cause parsing to fail: |
663 | 802 | ||
664 | .. code-block:: none | 803 | .. code-block:: none |
665 | 804 | ||
@@ -667,20 +806,22 @@ system and gives an overview of their function and contents. | |||
667 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend | 806 | /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend |
668 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend | 807 | /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend |
669 | 808 | ||
809 | :term:`BBINCLUDED` | ||
810 | See :term:`bitbake:BBINCLUDED` in the BitBake manual. | ||
811 | |||
670 | :term:`BBINCLUDELOGS` | 812 | :term:`BBINCLUDELOGS` |
671 | Variable that controls how BitBake displays logs on build failure. | 813 | Variable that controls how BitBake displays logs on build failure. |
672 | 814 | ||
673 | :term:`BBINCLUDELOGS_LINES` | 815 | :term:`BBINCLUDELOGS_LINES` |
674 | If :term:`BBINCLUDELOGS` is set, specifies the | 816 | If :term:`BBINCLUDELOGS` is set, specifies the |
675 | maximum number of lines from the task log file to print when | 817 | maximum number of lines from the task log file to print when |
676 | reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, | 818 | reporting a failed task. If you do not set :term:`BBINCLUDELOGS_LINES`, |
677 | the entire log is printed. | 819 | the entire log is printed. |
678 | 820 | ||
679 | :term:`BBLAYERS` | 821 | :term:`BBLAYERS` |
680 | Lists the layers to enable during the build. This variable is defined | 822 | Lists the layers to enable during the build. This variable is defined |
681 | in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. | 823 | in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. |
682 | Here is an example: | 824 | Here is an example:: |
683 | :: | ||
684 | 825 | ||
685 | BBLAYERS = " \ | 826 | BBLAYERS = " \ |
686 | /home/scottrif/poky/meta \ | 827 | /home/scottrif/poky/meta \ |
@@ -692,10 +833,13 @@ system and gives an overview of their function and contents. | |||
692 | This example enables four layers, one of which is a custom, | 833 | This example enables four layers, one of which is a custom, |
693 | user-defined layer named ``meta-mykernel``. | 834 | user-defined layer named ``meta-mykernel``. |
694 | 835 | ||
836 | :term:`BBLAYERS_FETCH_DIR` | ||
837 | See :term:`bitbake:BBLAYERS_FETCH_DIR` in the BitBake manual. | ||
838 | |||
695 | :term:`BBMASK` | 839 | :term:`BBMASK` |
696 | Prevents BitBake from processing recipes and recipe append files. | 840 | Prevents BitBake from processing recipes and recipe append files. |
697 | 841 | ||
698 | You can use the ``BBMASK`` variable to "hide" these ``.bb`` and | 842 | You can use the :term:`BBMASK` variable to "hide" these ``.bb`` and |
699 | ``.bbappend`` files. BitBake ignores any recipe or recipe append | 843 | ``.bbappend`` files. BitBake ignores any recipe or recipe append |
700 | files that match any of the expressions. It is as if BitBake does not | 844 | 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 | 845 | see them at all. Consequently, matching files are not parsed or |
@@ -709,14 +853,13 @@ system and gives an overview of their function and contents. | |||
709 | 853 | ||
710 | The following example uses a complete regular expression to tell | 854 | The following example uses a complete regular expression to tell |
711 | BitBake to ignore all recipe and recipe append files in the | 855 | BitBake to ignore all recipe and recipe append files in the |
712 | ``meta-ti/recipes-misc/`` directory: | 856 | ``meta-ti/recipes-misc/`` directory:: |
713 | :: | ||
714 | 857 | ||
715 | BBMASK = "meta-ti/recipes-misc/" | 858 | BBMASK = "meta-ti/recipes-misc/" |
716 | 859 | ||
717 | If you want to mask out multiple directories or recipes, you can | 860 | If you want to mask out multiple directories or recipes, you can |
718 | specify multiple regular expression fragments. This next example | 861 | specify multiple regular expression fragments. This next example |
719 | masks out multiple directories and individual recipes: :: | 862 | masks out multiple directories and individual recipes:: |
720 | 863 | ||
721 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" | 864 | BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" |
722 | BBMASK += "/meta-oe/recipes-support/" | 865 | BBMASK += "/meta-oe/recipes-support/" |
@@ -734,72 +877,55 @@ system and gives an overview of their function and contents. | |||
734 | building targets with multiple configurations. Use this variable in | 877 | building targets with multiple configurations. Use this variable in |
735 | your ``conf/local.conf`` configuration file. Specify a | 878 | your ``conf/local.conf`` configuration file. Specify a |
736 | multiconfigname for each configuration file you are using. For | 879 | multiconfigname for each configuration file you are using. For |
737 | example, the following line specifies three configuration files: | 880 | example, the following line specifies three configuration files:: |
738 | :: | ||
739 | 881 | ||
740 | BBMULTICONFIG = "configA configB configC" | 882 | BBMULTICONFIG = "configA configB configC" |
741 | 883 | ||
742 | Each configuration file you | 884 | Each configuration file you use must reside in a ``multiconfig`` |
743 | use must reside in the :term:`Build Directory` | 885 | subdirectory of a configuration directory within a layer, or |
744 | ``conf/multiconfig`` directory (e.g. | 886 | within the :term:`Build Directory` (e.g. |
745 | build_directory\ ``/conf/multiconfig/configA.conf``). | 887 | ``build_directory/conf/multiconfig/configA.conf`` or |
888 | ``mylayer/conf/multiconfig/configB.conf``). | ||
746 | 889 | ||
747 | For information on how to use ``BBMULTICONFIG`` in an environment | 890 | For information on how to use :term:`BBMULTICONFIG` in an environment |
748 | that supports building targets with multiple configurations, see the | 891 | that supports building targets with multiple configurations, see the |
749 | ":ref:`dev-manual/common-tasks:building images for multiple targets using multiple configurations`" | 892 | ":ref:`dev-manual/building:building images for multiple targets using multiple configurations`" |
750 | section in the Yocto Project Development Tasks Manual. | 893 | section in the Yocto Project Development Tasks Manual. |
751 | 894 | ||
752 | :term:`BBPATH` | 895 | :term:`BBPATH` |
753 | Used by BitBake to locate ``.bbclass`` and configuration files. This | 896 | See :term:`bitbake:BBPATH` in the BitBake manual. |
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 | 897 | ||
771 | :term:`BBSERVER` | 898 | :term:`BBSERVER` |
772 | If defined in the BitBake environment, ``BBSERVER`` points to the | 899 | If defined in the BitBake environment, :term:`BBSERVER` points to the |
773 | BitBake remote server. | 900 | BitBake remote server. |
774 | 901 | ||
775 | Use the following format to export the variable to the BitBake | 902 | Use the following format to export the variable to the BitBake |
776 | environment: | 903 | environment:: |
777 | :: | ||
778 | 904 | ||
779 | export BBSERVER=localhost:$port | 905 | export BBSERVER=localhost:$port |
780 | 906 | ||
781 | By default, ``BBSERVER`` also appears in | 907 | By default, :term:`BBSERVER` also appears in :term:`BB_BASEHASH_IGNORE_VARS`. |
782 | :term:`bitbake:BB_HASHBASE_WHITELIST`. | 908 | Consequently, :term:`BBSERVER` is excluded from checksum and dependency |
783 | Consequently, ``BBSERVER`` is excluded from checksum and dependency | ||
784 | data. | 909 | data. |
785 | 910 | ||
911 | :term:`BBTARGETS` | ||
912 | See :term:`bitbake:BBTARGETS` in the BitBake manual. | ||
913 | |||
786 | :term:`BINCONFIG` | 914 | :term:`BINCONFIG` |
787 | When inheriting the | 915 | When inheriting the :ref:`ref-classes-binconfig-disabled` class, this |
788 | :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, | 916 | variable specifies binary configuration scripts to disable in favor of |
789 | this variable specifies binary configuration scripts to disable in | 917 | using ``pkg-config`` to query the information. The |
790 | favor of using ``pkg-config`` to query the information. The | 918 | :ref:`ref-classes-binconfig-disabled` class will modify the specified |
791 | ``binconfig-disabled`` class will modify the specified scripts to | 919 | scripts to return an error so that calls to them can be easily found |
792 | return an error so that calls to them can be easily found and | 920 | and replaced. |
793 | replaced. | ||
794 | 921 | ||
795 | To add multiple scripts, separate them by spaces. Here is an example | 922 | To add multiple scripts, separate them by spaces. Here is an example |
796 | from the ``libpng`` recipe: | 923 | from the ``libpng`` recipe:: |
797 | :: | ||
798 | 924 | ||
799 | BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" | 925 | BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config" |
800 | 926 | ||
801 | :term:`BINCONFIG_GLOB` | 927 | :term:`BINCONFIG_GLOB` |
802 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | 928 | When inheriting the :ref:`ref-classes-binconfig` class, |
803 | this variable specifies a wildcard for configuration scripts that | 929 | this variable specifies a wildcard for configuration scripts that |
804 | need editing. The scripts are edited to correct any paths that have | 930 | 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 | 931 | been set up during compilation so that they are correct for use when |
@@ -808,7 +934,7 @@ system and gives an overview of their function and contents. | |||
808 | 934 | ||
809 | .. note:: | 935 | .. note:: |
810 | 936 | ||
811 | The ``BINCONFIG_GLOB`` variable uses | 937 | The :term:`BINCONFIG_GLOB` variable uses |
812 | `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, | 938 | `shell globbing <https://tldp.org/LDP/abs/html/globbingref.html>`__, |
813 | which is recognition and expansion of wildcards during pattern | 939 | which is recognition and expansion of wildcards during pattern |
814 | matching. Shell globbing is very similar to | 940 | matching. Shell globbing is very similar to |
@@ -816,16 +942,18 @@ system and gives an overview of their function and contents. | |||
816 | and `glob <https://docs.python.org/3/library/glob.html>`__. | 942 | and `glob <https://docs.python.org/3/library/glob.html>`__. |
817 | 943 | ||
818 | For more information on how this variable works, see | 944 | For more information on how this variable works, see |
819 | ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. | 945 | ``meta/classes-recipe/binconfig.bbclass`` in the :term:`Source Directory`. |
820 | You can also find general | 946 | You can also find general |
821 | information on the class in the | 947 | information on the class in the |
822 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | 948 | ":ref:`ref-classes-binconfig`" section. |
949 | |||
950 | :term:`BITBAKE_UI` | ||
951 | See :term:`bitbake:BITBAKE_UI` in the BitBake manual. | ||
823 | 952 | ||
824 | :term:`BP` | 953 | :term:`BP` |
825 | The base recipe name and version but without any special recipe name | 954 | The base recipe name and version but without any special recipe name |
826 | suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is | 955 | suffix (i.e. ``-native``, ``lib64-``, and so forth). :term:`BP` is |
827 | comprised of the following: | 956 | comprised of the following:: |
828 | :: | ||
829 | 957 | ||
830 | ${BPN}-${PV} | 958 | ${BPN}-${PV} |
831 | 959 | ||
@@ -846,23 +974,23 @@ system and gives an overview of their function and contents. | |||
846 | 974 | ||
847 | :term:`BUILD_ARCH` | 975 | :term:`BUILD_ARCH` |
848 | Specifies the architecture of the build host (e.g. ``i686``). The | 976 | Specifies the architecture of the build host (e.g. ``i686``). The |
849 | OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the | 977 | OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the |
850 | machine name reported by the ``uname`` command. | 978 | machine name reported by the ``uname`` command. |
851 | 979 | ||
852 | :term:`BUILD_AS_ARCH` | 980 | :term:`BUILD_AS_ARCH` |
853 | Specifies the architecture-specific assembler flags for the build | 981 | Specifies the architecture-specific assembler flags for the build |
854 | host. By default, the value of ``BUILD_AS_ARCH`` is empty. | 982 | host. By default, the value of :term:`BUILD_AS_ARCH` is empty. |
855 | 983 | ||
856 | :term:`BUILD_CC_ARCH` | 984 | :term:`BUILD_CC_ARCH` |
857 | Specifies the architecture-specific C compiler flags for the build | 985 | Specifies the architecture-specific C compiler flags for the build |
858 | host. By default, the value of ``BUILD_CC_ARCH`` is empty. | 986 | host. By default, the value of :term:`BUILD_CC_ARCH` is empty. |
859 | 987 | ||
860 | :term:`BUILD_CCLD` | 988 | :term:`BUILD_CCLD` |
861 | Specifies the linker command to be used for the build host when the C | 989 | 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`` | 990 | compiler is being used as the linker. By default, :term:`BUILD_CCLD` |
863 | points to GCC and passes as arguments the value of | 991 | points to GCC and passes as arguments the value of |
864 | :term:`BUILD_CC_ARCH`, assuming | 992 | :term:`BUILD_CC_ARCH`, assuming |
865 | ``BUILD_CC_ARCH`` is set. | 993 | :term:`BUILD_CC_ARCH` is set. |
866 | 994 | ||
867 | :term:`BUILD_CFLAGS` | 995 | :term:`BUILD_CFLAGS` |
868 | Specifies the flags to pass to the C compiler when building for the | 996 | Specifies the flags to pass to the C compiler when building for the |
@@ -884,19 +1012,19 @@ system and gives an overview of their function and contents. | |||
884 | 1012 | ||
885 | :term:`BUILD_FC` | 1013 | :term:`BUILD_FC` |
886 | Specifies the Fortran compiler command for the build host. By | 1014 | Specifies the Fortran compiler command for the build host. By |
887 | default, ``BUILD_FC`` points to Gfortran and passes as arguments the | 1015 | default, :term:`BUILD_FC` points to Gfortran and passes as arguments the |
888 | value of :term:`BUILD_CC_ARCH`, assuming | 1016 | value of :term:`BUILD_CC_ARCH`, assuming |
889 | ``BUILD_CC_ARCH`` is set. | 1017 | :term:`BUILD_CC_ARCH` is set. |
890 | 1018 | ||
891 | :term:`BUILD_LD` | 1019 | :term:`BUILD_LD` |
892 | Specifies the linker command for the build host. By default, | 1020 | Specifies the linker command for the build host. By default, |
893 | ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments | 1021 | :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments |
894 | the value of :term:`BUILD_LD_ARCH`, assuming | 1022 | the value of :term:`BUILD_LD_ARCH`, assuming |
895 | ``BUILD_LD_ARCH`` is set. | 1023 | :term:`BUILD_LD_ARCH` is set. |
896 | 1024 | ||
897 | :term:`BUILD_LD_ARCH` | 1025 | :term:`BUILD_LD_ARCH` |
898 | Specifies architecture-specific linker flags for the build host. By | 1026 | Specifies architecture-specific linker flags for the build host. By |
899 | default, the value of ``BUILD_LD_ARCH`` is empty. | 1027 | default, the value of :term:`BUILD_LD_ARCH` is empty. |
900 | 1028 | ||
901 | :term:`BUILD_LDFLAGS` | 1029 | :term:`BUILD_LDFLAGS` |
902 | Specifies the flags to pass to the linker when building for the build | 1030 | Specifies the flags to pass to the linker when building for the build |
@@ -910,99 +1038,96 @@ system and gives an overview of their function and contents. | |||
910 | the :term:`BUILD_CFLAGS` and | 1038 | the :term:`BUILD_CFLAGS` and |
911 | :term:`BUILDSDK_CFLAGS` default values. | 1039 | :term:`BUILDSDK_CFLAGS` default values. |
912 | 1040 | ||
913 | The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 | 1041 | The default value of the :term:`BUILD_OPTIMIZATION` variable is "-O2 |
914 | -pipe". | 1042 | -pipe". |
915 | 1043 | ||
916 | :term:`BUILD_OS` | 1044 | :term:`BUILD_OS` |
917 | Specifies the operating system in use on the build host (e.g. | 1045 | Specifies the operating system in use on the build host (e.g. |
918 | "linux"). The OpenEmbedded build system sets the value of | 1046 | "linux"). The OpenEmbedded build system sets the value of |
919 | ``BUILD_OS`` from the OS reported by the ``uname`` command - the | 1047 | :term:`BUILD_OS` from the OS reported by the ``uname`` command --- the |
920 | first word, converted to lower-case characters. | 1048 | first word, converted to lower-case characters. |
921 | 1049 | ||
922 | :term:`BUILD_PREFIX` | 1050 | :term:`BUILD_PREFIX` |
923 | The toolchain binary prefix used for native recipes. The OpenEmbedded | 1051 | The toolchain binary prefix used for native recipes. The OpenEmbedded |
924 | build system uses the ``BUILD_PREFIX`` value to set the | 1052 | build system uses the :term:`BUILD_PREFIX` value to set the |
925 | :term:`TARGET_PREFIX` when building for | 1053 | :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes. |
926 | ``native`` recipes. | ||
927 | 1054 | ||
928 | :term:`BUILD_STRIP` | 1055 | :term:`BUILD_STRIP` |
929 | Specifies the command to be used to strip debugging symbols from | 1056 | Specifies the command to be used to strip debugging symbols from |
930 | binaries produced for the build host. By default, ``BUILD_STRIP`` | 1057 | binaries produced for the build host. By default, :term:`BUILD_STRIP` |
931 | points to | 1058 | points to |
932 | ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. | 1059 | ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. |
933 | 1060 | ||
934 | :term:`BUILD_SYS` | 1061 | :term:`BUILD_SYS` |
935 | Specifies the system, including the architecture and the operating | 1062 | Specifies the system, including the architecture and the operating |
936 | system, to use when building for the build host (i.e. when building | 1063 | system, to use when building for the build host (i.e. when building |
937 | ``native`` recipes). | 1064 | :ref:`ref-classes-native` recipes). |
938 | 1065 | ||
939 | The OpenEmbedded build system automatically sets this variable based | 1066 | The OpenEmbedded build system automatically sets this variable based |
940 | on :term:`BUILD_ARCH`, | 1067 | on :term:`BUILD_ARCH`, |
941 | :term:`BUILD_VENDOR`, and | 1068 | :term:`BUILD_VENDOR`, and |
942 | :term:`BUILD_OS`. You do not need to set the | 1069 | :term:`BUILD_OS`. You do not need to set the |
943 | ``BUILD_SYS`` variable yourself. | 1070 | :term:`BUILD_SYS` variable yourself. |
944 | 1071 | ||
945 | :term:`BUILD_VENDOR` | 1072 | :term:`BUILD_VENDOR` |
946 | Specifies the vendor name to use when building for the build host. | 1073 | Specifies the vendor name to use when building for the build host. |
947 | The default value is an empty string (""). | 1074 | The default value is an empty string (""). |
948 | 1075 | ||
949 | :term:`BUILDDIR` | 1076 | :term:`BUILDDIR` |
950 | Points to the location of the :term:`Build Directory`. | 1077 | Points to the location of the :term:`Build Directory`. You can define |
951 | You can define this directory indirectly through the | 1078 | this directory indirectly through the :ref:`structure-core-script` script |
952 | :ref:`structure-core-script` script by passing in a Build | 1079 | by passing in a :term:`Build Directory` path when you run the script. If |
953 | Directory path when you run the script. If you run the script and do | 1080 | you run the script and do not provide a :term:`Build Directory` path, the |
954 | not provide a Build Directory path, the ``BUILDDIR`` defaults to | 1081 | :term:`BUILDDIR` defaults to ``build`` in the current directory. |
955 | ``build`` in the current directory. | ||
956 | 1082 | ||
957 | :term:`BUILDHISTORY_COMMIT` | 1083 | :term:`BUILDHISTORY_COMMIT` |
958 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1084 | When inheriting the :ref:`ref-classes-buildhistory` class, this variable |
959 | class, this variable specifies whether or not to commit the build | 1085 | specifies whether or not to commit the build history output in a local |
960 | history output in a local Git repository. If set to "1", this local | 1086 | Git repository. If set to "1", this local repository will be maintained |
961 | repository will be maintained automatically by the ``buildhistory`` | 1087 | automatically by the :ref:`ref-classes-buildhistory` class and a commit |
962 | class and a commit will be created on every build for changes to each | 1088 | will be created on every build for changes to each top-level subdirectory |
963 | top-level subdirectory of the build history output (images, packages, | 1089 | of the build history output (images, packages, and sdk). If you want to |
964 | and sdk). If you want to track changes to build history over time, | 1090 | track changes to build history over time, you should set this value to |
965 | you should set this value to "1". | 1091 | "1". |
966 | 1092 | ||
967 | By default, the ``buildhistory`` class does not commit the build | 1093 | By default, the :ref:`ref-classes-buildhistory` class |
968 | history output in a local Git repository: | 1094 | enables committing the buildhistory output in a local Git repository:: |
969 | :: | ||
970 | 1095 | ||
971 | BUILDHISTORY_COMMIT ?= "0" | 1096 | BUILDHISTORY_COMMIT ?= "1" |
972 | 1097 | ||
973 | :term:`BUILDHISTORY_COMMIT_AUTHOR` | 1098 | :term:`BUILDHISTORY_COMMIT_AUTHOR` |
974 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1099 | When inheriting the :ref:`ref-classes-buildhistory` |
975 | class, this variable specifies the author to use for each Git commit. | 1100 | class, this variable specifies the author to use for each Git commit. |
976 | In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the | 1101 | In order for the :term:`BUILDHISTORY_COMMIT_AUTHOR` variable to work, the |
977 | :term:`BUILDHISTORY_COMMIT` variable must | 1102 | :term:`BUILDHISTORY_COMMIT` variable must |
978 | be set to "1". | 1103 | be set to "1". |
979 | 1104 | ||
980 | Git requires that the value you provide for the | 1105 | Git requires that the value you provide for the |
981 | ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name | 1106 | :term:`BUILDHISTORY_COMMIT_AUTHOR` variable takes the form of "name |
982 | email@host". Providing an email address or host that is not valid | 1107 | email@host". Providing an email address or host that is not valid |
983 | does not produce an error. | 1108 | does not produce an error. |
984 | 1109 | ||
985 | By default, the ``buildhistory`` class sets the variable as follows: | 1110 | By default, the :ref:`ref-classes-buildhistory` class sets the variable |
986 | :: | 1111 | as follows:: |
987 | 1112 | ||
988 | BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" | 1113 | BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" |
989 | 1114 | ||
990 | :term:`BUILDHISTORY_DIR` | 1115 | :term:`BUILDHISTORY_DIR` |
991 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1116 | When inheriting the :ref:`ref-classes-buildhistory` |
992 | class, this variable specifies the directory in which build history | 1117 | class, this variable specifies the directory in which build history |
993 | information is kept. For more information on how the variable works, | 1118 | information is kept. For more information on how the variable works, |
994 | see the ``buildhistory.class``. | 1119 | see the :ref:`ref-classes-buildhistory` class. |
995 | 1120 | ||
996 | By default, the ``buildhistory`` class sets the directory as follows: | 1121 | By default, the :ref:`ref-classes-buildhistory` class sets the directory |
997 | :: | 1122 | as follows:: |
998 | 1123 | ||
999 | BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" | 1124 | BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" |
1000 | 1125 | ||
1001 | :term:`BUILDHISTORY_FEATURES` | 1126 | :term:`BUILDHISTORY_FEATURES` |
1002 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1127 | When inheriting the :ref:`ref-classes-buildhistory` |
1003 | class, this variable specifies the build history features to be | 1128 | class, this variable specifies the build history features to be |
1004 | enabled. For more information on how build history works, see the | 1129 | enabled. For more information on how build history works, see the |
1005 | ":ref:`dev-manual/common-tasks:maintaining build output quality`" | 1130 | ":ref:`dev-manual/build-quality:maintaining build output quality`" |
1006 | section in the Yocto Project Development Tasks Manual. | 1131 | section in the Yocto Project Development Tasks Manual. |
1007 | 1132 | ||
1008 | You can specify these features in the form of a space-separated list: | 1133 | You can specify these features in the form of a space-separated list: |
@@ -1021,14 +1146,13 @@ system and gives an overview of their function and contents. | |||
1021 | This saves one file per task and lists the SHA-256 checksums for | 1146 | This saves one file per task and lists the SHA-256 checksums for |
1022 | each file staged (i.e. the output of the task). | 1147 | each file staged (i.e. the output of the task). |
1023 | 1148 | ||
1024 | By default, the ``buildhistory`` class enables the following | 1149 | By default, the :ref:`ref-classes-buildhistory` class enables the |
1025 | features: | 1150 | following features:: |
1026 | :: | ||
1027 | 1151 | ||
1028 | BUILDHISTORY_FEATURES ?= "image package sdk" | 1152 | BUILDHISTORY_FEATURES ?= "image package sdk" |
1029 | 1153 | ||
1030 | :term:`BUILDHISTORY_IMAGE_FILES` | 1154 | :term:`BUILDHISTORY_IMAGE_FILES` |
1031 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1155 | When inheriting the :ref:`ref-classes-buildhistory` |
1032 | class, this variable specifies a list of paths to files copied from | 1156 | class, this variable specifies a list of paths to files copied from |
1033 | the image contents into the build history directory under an | 1157 | the image contents into the build history directory under an |
1034 | "image-files" directory in the directory for the image, so that you | 1158 | "image-files" directory in the directory for the image, so that you |
@@ -1038,30 +1162,45 @@ system and gives an overview of their function and contents. | |||
1038 | any file. Specifying an invalid path does not produce an error. | 1162 | any file. Specifying an invalid path does not produce an error. |
1039 | Consequently, you can include files that might not always be present. | 1163 | Consequently, you can include files that might not always be present. |
1040 | 1164 | ||
1041 | By default, the ``buildhistory`` class provides paths to the | 1165 | By default, the :ref:`ref-classes-buildhistory` class provides paths to |
1042 | following files: | 1166 | the following files:: |
1043 | :: | ||
1044 | 1167 | ||
1045 | BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" | 1168 | BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" |
1046 | 1169 | ||
1170 | :term:`BUILDHISTORY_PATH_PREFIX_STRIP` | ||
1171 | When inheriting the :ref:`ref-classes-buildhistory` | ||
1172 | class, this variable specifies a common path prefix that should be | ||
1173 | stripped off the beginning of paths in the task signature list when the | ||
1174 | ``task`` feature is active in :term:`BUILDHISTORY_FEATURES`. This can be | ||
1175 | useful when build history is populated from multiple sources that may not | ||
1176 | all use the same top level directory. | ||
1177 | |||
1178 | By default, the :ref:`ref-classes-buildhistory` class sets the variable | ||
1179 | as follows:: | ||
1180 | |||
1181 | BUILDHISTORY_PATH_PREFIX_STRIP ?= "" | ||
1182 | |||
1183 | In this case, no prefixes will be stripped. | ||
1184 | |||
1047 | :term:`BUILDHISTORY_PUSH_REPO` | 1185 | :term:`BUILDHISTORY_PUSH_REPO` |
1048 | When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` | 1186 | When inheriting the :ref:`ref-classes-buildhistory` class, this variable |
1049 | class, this variable optionally specifies a remote repository to | 1187 | optionally specifies a remote repository to which build history pushes |
1050 | which build history pushes Git changes. In order for | 1188 | Git changes. In order for :term:`BUILDHISTORY_PUSH_REPO` to work, |
1051 | ``BUILDHISTORY_PUSH_REPO`` to work, | 1189 | :term:`BUILDHISTORY_COMMIT` must be set to "1". |
1052 | :term:`BUILDHISTORY_COMMIT` must be set to | ||
1053 | "1". | ||
1054 | 1190 | ||
1055 | The repository should correspond to a remote address that specifies a | 1191 | The repository should correspond to a remote address that specifies a |
1056 | repository as understood by Git, or alternatively to a remote name | 1192 | repository as understood by Git, or alternatively to a remote name |
1057 | that you have set up manually using ``git remote`` within the local | 1193 | that you have set up manually using ``git remote`` within the local |
1058 | repository. | 1194 | repository. |
1059 | 1195 | ||
1060 | By default, the ``buildhistory`` class sets the variable as follows: | 1196 | By default, the :ref:`ref-classes-buildhistory` class sets the variable |
1061 | :: | 1197 | as follows:: |
1062 | 1198 | ||
1063 | BUILDHISTORY_PUSH_REPO ?= "" | 1199 | BUILDHISTORY_PUSH_REPO ?= "" |
1064 | 1200 | ||
1201 | :term:`BUILDNAME` | ||
1202 | See :term:`bitbake:BUILDNAME` in the BitBake manual. | ||
1203 | |||
1065 | :term:`BUILDSDK_CFLAGS` | 1204 | :term:`BUILDSDK_CFLAGS` |
1066 | Specifies the flags to pass to the C compiler when building for the | 1205 | Specifies the flags to pass to the C compiler when building for the |
1067 | SDK. When building in the ``nativesdk-`` context, | 1206 | SDK. When building in the ``nativesdk-`` context, |
@@ -1088,9 +1227,8 @@ system and gives an overview of their function and contents. | |||
1088 | 1227 | ||
1089 | :term:`BUILDSTATS_BASE` | 1228 | :term:`BUILDSTATS_BASE` |
1090 | Points to the location of the directory that holds build statistics | 1229 | Points to the location of the directory that holds build statistics |
1091 | when you use and enable the | 1230 | when you use and enable the :ref:`ref-classes-buildstats` class. The |
1092 | :ref:`buildstats <ref-classes-buildstats>` class. The | 1231 | :term:`BUILDSTATS_BASE` directory defaults to |
1093 | ``BUILDSTATS_BASE`` directory defaults to | ||
1094 | ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. | 1232 | ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. |
1095 | 1233 | ||
1096 | :term:`BUSYBOX_SPLIT_SUID` | 1234 | :term:`BUSYBOX_SPLIT_SUID` |
@@ -1099,10 +1237,13 @@ system and gives an overview of their function and contents. | |||
1099 | ``setuid root``, and one for the remaining features (i.e. those that | 1237 | ``setuid root``, and one for the remaining features (i.e. those that |
1100 | do not require ``setuid root``). | 1238 | do not require ``setuid root``). |
1101 | 1239 | ||
1102 | The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in | 1240 | The :term:`BUSYBOX_SPLIT_SUID` variable defaults to "1", which results in |
1103 | splitting the output executable file. Set the variable to "0" to get | 1241 | splitting the output executable file. Set the variable to "0" to get |
1104 | a single output executable file. | 1242 | a single output executable file. |
1105 | 1243 | ||
1244 | :term:`BZRDIR` | ||
1245 | See :term:`bitbake:BZRDIR` in the BitBake manual. | ||
1246 | |||
1106 | :term:`CACHE` | 1247 | :term:`CACHE` |
1107 | Specifies the directory BitBake uses to store a cache of the | 1248 | Specifies the directory BitBake uses to store a cache of the |
1108 | :term:`Metadata` so it does not need to be parsed every time | 1249 | :term:`Metadata` so it does not need to be parsed every time |
@@ -1116,7 +1257,7 @@ system and gives an overview of their function and contents. | |||
1116 | exported to an environment variable and thus made visible to the | 1257 | exported to an environment variable and thus made visible to the |
1117 | software being built during the compilation step. | 1258 | software being built during the compilation step. |
1118 | 1259 | ||
1119 | Default initialization for ``CFLAGS`` varies depending on what is | 1260 | Default initialization for :term:`CFLAGS` varies depending on what is |
1120 | being built: | 1261 | being built: |
1121 | 1262 | ||
1122 | - :term:`TARGET_CFLAGS` when building for the | 1263 | - :term:`TARGET_CFLAGS` when building for the |
@@ -1132,37 +1273,34 @@ system and gives an overview of their function and contents. | |||
1132 | An internal variable specifying the special class override that | 1273 | An internal variable specifying the special class override that |
1133 | should currently apply (e.g. "class-target", "class-native", and so | 1274 | should currently apply (e.g. "class-target", "class-native", and so |
1134 | forth). The classes that use this variable (e.g. | 1275 | forth). The classes that use this variable (e.g. |
1135 | :ref:`native <ref-classes-native>`, | 1276 | :ref:`ref-classes-native`, :ref:`ref-classes-nativesdk`, and so forth) |
1136 | :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the | 1277 | set the variable to appropriate values. |
1137 | variable to appropriate values. | ||
1138 | 1278 | ||
1139 | .. note:: | 1279 | .. note:: |
1140 | 1280 | ||
1141 | ``CLASSOVERRIDE`` gets its default "class-target" value from the | 1281 | :term:`CLASSOVERRIDE` gets its default "class-target" value from the |
1142 | ``bitbake.conf`` file. | 1282 | ``bitbake.conf`` file. |
1143 | 1283 | ||
1144 | As an example, the following override allows you to install extra | 1284 | As an example, the following override allows you to install extra |
1145 | files, but only when building for the target: | 1285 | files, but only when building for the target:: |
1146 | :: | ||
1147 | 1286 | ||
1148 | do_install_append_class-target() { | 1287 | do_install:append:class-target() { |
1149 | install my-extra-file ${D}${sysconfdir} | 1288 | install my-extra-file ${D}${sysconfdir} |
1150 | } | 1289 | } |
1151 | 1290 | ||
1152 | Here is an example where ``FOO`` is set to | 1291 | Here is an example where ``FOO`` is set to |
1153 | "native" when building for the build host, and to "other" when not | 1292 | "native" when building for the build host, and to "other" when not |
1154 | building for the build host: | 1293 | building for the build host:: |
1155 | :: | ||
1156 | 1294 | ||
1157 | FOO_class-native = "native" | 1295 | FOO:class-native = "native" |
1158 | FOO = "other" | 1296 | FOO = "other" |
1159 | 1297 | ||
1160 | The underlying mechanism behind ``CLASSOVERRIDE`` is simply | 1298 | The underlying mechanism behind :term:`CLASSOVERRIDE` is simply |
1161 | that it is included in the default value of | 1299 | that it is included in the default value of |
1162 | :term:`OVERRIDES`. | 1300 | :term:`OVERRIDES`. |
1163 | 1301 | ||
1164 | :term:`CLEANBROKEN` | 1302 | :term:`CLEANBROKEN` |
1165 | If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the | 1303 | If set to "1" within a recipe, :term:`CLEANBROKEN` specifies that the |
1166 | ``make clean`` command does not work for the software being built. | 1304 | ``make clean`` command does not work for the software being built. |
1167 | Consequently, the OpenEmbedded build system will not try to run | 1305 | Consequently, the OpenEmbedded build system will not try to run |
1168 | ``make clean`` during the :ref:`ref-tasks-configure` | 1306 | ``make clean`` during the :ref:`ref-tasks-configure` |
@@ -1178,6 +1316,26 @@ system and gives an overview of their function and contents. | |||
1178 | optional at the distribution level, in case the hardware supports | 1316 | optional at the distribution level, in case the hardware supports |
1179 | Bluetooth but you do not ever intend to use it. | 1317 | Bluetooth but you do not ever intend to use it. |
1180 | 1318 | ||
1319 | :term:`COMMERCIAL_AUDIO_PLUGINS` | ||
1320 | This variable is specific to the :yocto_git:`GStreamer recipes | ||
1321 | </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. | ||
1322 | It allows to build the GStreamer `"ugly" | ||
1323 | <https://github.com/GStreamer/gst-plugins-ugly>`__ and | ||
1324 | `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ audio plugins. | ||
1325 | |||
1326 | See the :ref:`dev-manual/licenses:other variables related to commercial licenses` | ||
1327 | section for usage details. | ||
1328 | |||
1329 | :term:`COMMERCIAL_VIDEO_PLUGINS` | ||
1330 | This variable is specific to the :yocto_git:`GStreamer recipes | ||
1331 | </poky/tree/meta/recipes-multimedia/gstreamer/gstreamer1.0-meta-base.bb>`. | ||
1332 | It allows to build the GStreamer `"ugly" | ||
1333 | <https://github.com/GStreamer/gst-plugins-ugly>`__ and | ||
1334 | `"bad" <https://github.com/GStreamer/gst-plugins-bad>`__ video plugins. | ||
1335 | |||
1336 | See the :ref:`dev-manual/licenses:other variables related to commercial licenses` | ||
1337 | section for usage details. | ||
1338 | |||
1181 | :term:`COMMON_LICENSE_DIR` | 1339 | :term:`COMMON_LICENSE_DIR` |
1182 | Points to ``meta/files/common-licenses`` in the | 1340 | Points to ``meta/files/common-licenses`` in the |
1183 | :term:`Source Directory`, which is where generic license | 1341 | :term:`Source Directory`, which is where generic license |
@@ -1204,35 +1362,63 @@ system and gives an overview of their function and contents. | |||
1204 | speed since the build system skips parsing recipes not compatible | 1362 | speed since the build system skips parsing recipes not compatible |
1205 | with the current machine. | 1363 | with the current machine. |
1206 | 1364 | ||
1365 | If one wants to have a recipe only available for some architectures | ||
1366 | (here ``aarch64`` and ``mips64``), the following can be used:: | ||
1367 | |||
1368 | COMPATIBLE_MACHINE = "^$" | ||
1369 | COMPATIBLE_MACHINE:arch64 = "^(aarch64)$" | ||
1370 | COMPATIBLE_MACHINE:mips64 = "^(mips64)$" | ||
1371 | |||
1372 | The first line means "match all machines whose :term:`MACHINEOVERRIDES` | ||
1373 | contains the empty string", which will always be none. | ||
1374 | |||
1375 | The second is for matching all machines whose :term:`MACHINEOVERRIDES` | ||
1376 | contains one override which is exactly ``aarch64``. | ||
1377 | |||
1378 | The third is for matching all machines whose :term:`MACHINEOVERRIDES` | ||
1379 | contains one override which is exactly ``mips64``. | ||
1380 | |||
1381 | The same could be achieved with:: | ||
1382 | |||
1383 | COMPATIBLE_MACHINE = "^(aarch64|mips64)$" | ||
1384 | |||
1385 | .. note:: | ||
1386 | |||
1387 | When :term:`COMPATIBLE_MACHINE` is set in a recipe inherits from | ||
1388 | native, the recipe is always skipped. All native recipes must be | ||
1389 | entirely target independent and should not rely on :term:`MACHINE`. | ||
1390 | |||
1207 | :term:`COMPLEMENTARY_GLOB` | 1391 | :term:`COMPLEMENTARY_GLOB` |
1208 | Defines wildcards to match when installing a list of complementary | 1392 | Defines wildcards to match when installing a list of complementary |
1209 | packages for all the packages explicitly (or implicitly) installed in | 1393 | packages for all the packages explicitly (or implicitly) installed in |
1210 | an image. | 1394 | an image. |
1211 | 1395 | ||
1212 | .. note:: | 1396 | The :term:`COMPLEMENTARY_GLOB` variable uses Unix filename pattern matching |
1213 | 1397 | (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), | |
1214 | The ``COMPLEMENTARY_GLOB`` variable uses Unix filename pattern matching | 1398 | which is similar to the Unix style pathname pattern expansion |
1215 | (`fnmatch <https://docs.python.org/3/library/fnmatch.html#module-fnmatch>`__), | 1399 | (`glob <https://docs.python.org/3/library/glob.html>`__). |
1216 | which is similar to the Unix style pathname pattern expansion | ||
1217 | (`glob <https://docs.python.org/3/library/glob.html>`__). | ||
1218 | 1400 | ||
1219 | The resulting list of complementary packages is associated with an | 1401 | The resulting list of complementary packages is associated with an |
1220 | item that can be added to | 1402 | item that can be added to |
1221 | :term:`IMAGE_FEATURES`. An example usage of | 1403 | :term:`IMAGE_FEATURES`. An example usage of |
1222 | this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` | 1404 | this is the "dev-pkgs" item that when added to :term:`IMAGE_FEATURES` |
1223 | will install -dev packages (containing headers and other development | 1405 | will install -dev packages (containing headers and other development |
1224 | files) for every package in the image. | 1406 | files) for every package in the image. |
1225 | 1407 | ||
1226 | To add a new feature item pointing to a wildcard, use a variable flag | 1408 | 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 | 1409 | to specify the feature item name and use the value to specify the |
1228 | wildcard. Here is an example: | 1410 | wildcard. Here is an example:: |
1229 | :: | ||
1230 | 1411 | ||
1231 | COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' | 1412 | COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' |
1232 | 1413 | ||
1414 | .. note:: | ||
1415 | |||
1416 | When installing complementary packages, recommends relationships | ||
1417 | (set via :term:`RRECOMMENDS`) are always ignored. | ||
1418 | |||
1233 | :term:`COMPONENTS_DIR` | 1419 | :term:`COMPONENTS_DIR` |
1234 | Stores sysroot components for each recipe. The OpenEmbedded build | 1420 | Stores sysroot components for each recipe. The OpenEmbedded build |
1235 | system uses ``COMPONENTS_DIR`` when constructing recipe-specific | 1421 | system uses :term:`COMPONENTS_DIR` when constructing recipe-specific |
1236 | sysroots for other recipes. | 1422 | sysroots for other recipes. |
1237 | 1423 | ||
1238 | The default is | 1424 | The default is |
@@ -1242,7 +1428,7 @@ system and gives an overview of their function and contents. | |||
1242 | 1428 | ||
1243 | :term:`CONF_VERSION` | 1429 | :term:`CONF_VERSION` |
1244 | Tracks the version of the local configuration file (i.e. | 1430 | Tracks the version of the local configuration file (i.e. |
1245 | ``local.conf``). The value for ``CONF_VERSION`` increments each time | 1431 | ``local.conf``). The value for :term:`CONF_VERSION` increments each time |
1246 | ``build/conf/`` compatibility changes. | 1432 | ``build/conf/`` compatibility changes. |
1247 | 1433 | ||
1248 | :term:`CONFFILES` | 1434 | :term:`CONFFILES` |
@@ -1252,29 +1438,28 @@ system and gives an overview of their function and contents. | |||
1252 | files you have changed after the original installation and that you | 1438 | files you have changed after the original installation and that you |
1253 | now want to remain unchanged are overwritten. In other words, | 1439 | now want to remain unchanged are overwritten. In other words, |
1254 | editable files might exist in the package that you do not want reset | 1440 | 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`` | 1441 | as part of the package update process. You can use the :term:`CONFFILES` |
1256 | variable to list the files in the package that you wish to prevent | 1442 | variable to list the files in the package that you wish to prevent |
1257 | the PMS from overwriting during this update process. | 1443 | the PMS from overwriting during this update process. |
1258 | 1444 | ||
1259 | To use the ``CONFFILES`` variable, provide a package name override | 1445 | To use the :term:`CONFFILES` variable, provide a package name override |
1260 | that identifies the resulting package. Then, provide a | 1446 | that identifies the resulting package. Then, provide a |
1261 | space-separated list of files. Here is an example: | 1447 | space-separated list of files. Here is an example:: |
1262 | :: | ||
1263 | 1448 | ||
1264 | CONFFILES_${PN} += "${sysconfdir}/file1 \ | 1449 | CONFFILES:${PN} += "${sysconfdir}/file1 \ |
1265 | ${sysconfdir}/file2 ${sysconfdir}/file3" | 1450 | ${sysconfdir}/file2 ${sysconfdir}/file3" |
1266 | 1451 | ||
1267 | A relationship exists between the ``CONFFILES`` and ``FILES`` | 1452 | There is a relationship between the :term:`CONFFILES` and :term:`FILES` |
1268 | variables. The files listed within ``CONFFILES`` must be a subset of | 1453 | variables. The files listed within :term:`CONFFILES` must be a subset of |
1269 | the files listed within ``FILES``. Because the configuration files | 1454 | the files listed within :term:`FILES`. Because the configuration files |
1270 | you provide with ``CONFFILES`` are simply being identified so that | 1455 | you provide with :term:`CONFFILES` are simply being identified so that |
1271 | the PMS will not overwrite them, it makes sense that the files must | 1456 | 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`` | 1457 | already be included as part of the package through the :term:`FILES` |
1273 | variable. | 1458 | variable. |
1274 | 1459 | ||
1275 | .. note:: | 1460 | .. note:: |
1276 | 1461 | ||
1277 | When specifying paths as part of the ``CONFFILES`` variable, it is | 1462 | When specifying paths as part of the :term:`CONFFILES` variable, it is |
1278 | good practice to use appropriate path variables. | 1463 | good practice to use appropriate path variables. |
1279 | For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` | 1464 | For example, ``${sysconfdir}`` rather than ``/etc`` or ``${bindir}`` |
1280 | rather than ``/usr/bin``. You can find a list of these variables at | 1465 | rather than ``/usr/bin``. You can find a list of these variables at |
@@ -1282,24 +1467,24 @@ system and gives an overview of their function and contents. | |||
1282 | :term:`Source Directory`. | 1467 | :term:`Source Directory`. |
1283 | 1468 | ||
1284 | :term:`CONFIG_INITRAMFS_SOURCE` | 1469 | :term:`CONFIG_INITRAMFS_SOURCE` |
1285 | Identifies the initial RAM filesystem (initramfs) source files. The | 1470 | Identifies the initial RAM filesystem (:term:`Initramfs`) source files. The |
1286 | OpenEmbedded build system receives and uses this kernel Kconfig | 1471 | OpenEmbedded build system receives and uses this kernel Kconfig |
1287 | variable as an environment variable. By default, the variable is set | 1472 | variable as an environment variable. By default, the variable is set |
1288 | to null (""). | 1473 | to null (""). |
1289 | 1474 | ||
1290 | The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive | 1475 | The :term:`CONFIG_INITRAMFS_SOURCE` can be either a single cpio archive |
1291 | with a ``.cpio`` suffix or a space-separated list of directories and | 1476 | with a ``.cpio`` suffix or a space-separated list of directories and |
1292 | files for building the initramfs image. A cpio archive should contain | 1477 | files for building the :term:`Initramfs` image. A cpio archive should contain |
1293 | a filesystem archive to be used as an initramfs image. Directories | 1478 | a filesystem archive to be used as an :term:`Initramfs` image. Directories |
1294 | should contain a filesystem layout to be included in the initramfs | 1479 | should contain a filesystem layout to be included in the :term:`Initramfs` |
1295 | image. Files should contain entries according to the format described | 1480 | image. Files should contain entries according to the format described |
1296 | by the ``usr/gen_init_cpio`` program in the kernel tree. | 1481 | by the ``usr/gen_init_cpio`` program in the kernel tree. |
1297 | 1482 | ||
1298 | If you specify multiple directories and files, the initramfs image | 1483 | If you specify multiple directories and files, the :term:`Initramfs` image |
1299 | will be the aggregate of all of them. | 1484 | will be the aggregate of all of them. |
1300 | 1485 | ||
1301 | For information on creating an initramfs, see the | 1486 | For information on creating an :term:`Initramfs`, see the |
1302 | ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | 1487 | ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section |
1303 | in the Yocto Project Development Tasks Manual. | 1488 | in the Yocto Project Development Tasks Manual. |
1304 | 1489 | ||
1305 | :term:`CONFIG_SITE` | 1490 | :term:`CONFIG_SITE` |
@@ -1311,82 +1496,26 @@ system and gives an overview of their function and contents. | |||
1311 | The minimal arguments for GNU configure. | 1496 | The minimal arguments for GNU configure. |
1312 | 1497 | ||
1313 | :term:`CONFLICT_DISTRO_FEATURES` | 1498 | :term:`CONFLICT_DISTRO_FEATURES` |
1314 | When inheriting the | 1499 | When inheriting the :ref:`ref-classes-features_check` |
1315 | :ref:`features_check <ref-classes-features_check>` | ||
1316 | class, this variable identifies distribution features that would be | 1500 | class, this variable identifies distribution features that would be |
1317 | in conflict should the recipe be built. In other words, if the | 1501 | in conflict should the recipe be built. In other words, if the |
1318 | ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also | 1502 | :term:`CONFLICT_DISTRO_FEATURES` variable lists a feature that also |
1319 | appears in ``DISTRO_FEATURES`` within the current configuration, then | 1503 | appears in :term:`DISTRO_FEATURES` within the current configuration, then |
1320 | the recipe will be skipped, and if the build system attempts to build | 1504 | the recipe will be skipped, and if the build system attempts to build |
1321 | the recipe then an error will be triggered. | 1505 | the recipe then an error will be triggered. |
1322 | 1506 | ||
1323 | :term:`COPYLEFT_LICENSE_EXCLUDE` | 1507 | :term:`CONVERSION_CMD` |
1324 | A space-separated list of licenses to exclude from the source | 1508 | This variable is used for storing image conversion commands. |
1325 | archived by the :ref:`archiver <ref-classes-archiver>` class. In | 1509 | Image conversion can convert an image into different objects like: |
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 | 1510 | ||
1331 | .. note:: | 1511 | - Compressed version of the image |
1332 | 1512 | ||
1333 | The ``COPYLEFT_LICENSE_EXCLUDE`` variable takes precedence over the | 1513 | - Checksums for the image |
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 | 1514 | ||
1348 | The default value is set by the | 1515 | An example of :term:`CONVERSION_CMD` from :ref:`ref-classes-image_types` |
1349 | :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which | 1516 | class is:: |
1350 | is inherited by the ``archiver`` class. The default value includes | ||
1351 | "GPL*", "LGPL*", and "AGPL*". | ||
1352 | 1517 | ||
1353 | :term:`COPYLEFT_PN_EXCLUDE` | 1518 | CONVERSION_CMD:lzo = "lzop -9 ${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.${type}" |
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 | 1519 | ||
1391 | :term:`COPY_LIC_DIRS` | 1520 | :term:`COPY_LIC_DIRS` |
1392 | If set to "1" along with the | 1521 | If set to "1" along with the |
@@ -1398,11 +1527,11 @@ system and gives an overview of their function and contents. | |||
1398 | 1527 | ||
1399 | .. note:: | 1528 | .. note:: |
1400 | 1529 | ||
1401 | The ``COPY_LIC_DIRS`` does not offer a path for adding licenses for | 1530 | The :term:`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 | 1531 | newly installed packages to an image, which might be most suitable for |
1403 | read-only filesystems that cannot be upgraded. See the | 1532 | read-only filesystems that cannot be upgraded. See the |
1404 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. | 1533 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. |
1405 | You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" | 1534 | You can also reference the ":ref:`dev-manual/licenses:providing license text`" |
1406 | section in the Yocto Project Development Tasks Manual for | 1535 | section in the Yocto Project Development Tasks Manual for |
1407 | information on providing license text. | 1536 | information on providing license text. |
1408 | 1537 | ||
@@ -1414,14 +1543,77 @@ system and gives an overview of their function and contents. | |||
1414 | 1543 | ||
1415 | .. note:: | 1544 | .. note:: |
1416 | 1545 | ||
1417 | The ``COPY_LIC_MANIFEST`` does not offer a path for adding licenses for | 1546 | The :term:`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 | 1547 | newly installed packages to an image, which might be most suitable for |
1419 | read-only filesystems that cannot be upgraded. See the | 1548 | read-only filesystems that cannot be upgraded. See the |
1420 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. | 1549 | :term:`LICENSE_CREATE_PACKAGE` variable for additional information. |
1421 | You can also reference the ":ref:`dev-manual/common-tasks:providing license text`" | 1550 | You can also reference the ":ref:`dev-manual/licenses:providing license text`" |
1422 | section in the Yocto Project Development Tasks Manual for | 1551 | section in the Yocto Project Development Tasks Manual for |
1423 | information on providing license text. | 1552 | information on providing license text. |
1424 | 1553 | ||
1554 | :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1555 | A space-separated list of licenses to exclude from the source archived by | ||
1556 | the :ref:`ref-classes-archiver` class. In other words, if a license in a | ||
1557 | recipe's :term:`LICENSE` value is in the value of | ||
1558 | :term:`COPYLEFT_LICENSE_EXCLUDE`, then its source is not archived by the | ||
1559 | class. | ||
1560 | |||
1561 | .. note:: | ||
1562 | |||
1563 | The :term:`COPYLEFT_LICENSE_EXCLUDE` variable takes precedence over the | ||
1564 | :term:`COPYLEFT_LICENSE_INCLUDE` variable. | ||
1565 | |||
1566 | The default value, which is "CLOSED Proprietary", for | ||
1567 | :term:`COPYLEFT_LICENSE_EXCLUDE` is set by the | ||
1568 | :ref:`ref-classes-copyleft_filter` class, which | ||
1569 | is inherited by the :ref:`ref-classes-archiver` class. | ||
1570 | |||
1571 | :term:`COPYLEFT_LICENSE_INCLUDE` | ||
1572 | A space-separated list of licenses to include in the source archived | ||
1573 | by the :ref:`ref-classes-archiver` class. In other | ||
1574 | words, if a license in a recipe's :term:`LICENSE` | ||
1575 | value is in the value of :term:`COPYLEFT_LICENSE_INCLUDE`, then its | ||
1576 | source is archived by the class. | ||
1577 | |||
1578 | The default value is set by the :ref:`ref-classes-copyleft_filter` class, | ||
1579 | which is inherited by the :ref:`ref-classes-archiver` class. The default | ||
1580 | value includes "GPL*", "LGPL*", and "AGPL*". | ||
1581 | |||
1582 | :term:`COPYLEFT_PN_EXCLUDE` | ||
1583 | A list of recipes to exclude in the source archived by the | ||
1584 | :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_EXCLUDE` | ||
1585 | variable overrides the license inclusion and exclusion caused through the | ||
1586 | :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1587 | variables, respectively. | ||
1588 | |||
1589 | The default value, which is "" indicating to not explicitly exclude | ||
1590 | any recipes by name, for :term:`COPYLEFT_PN_EXCLUDE` is set by the | ||
1591 | :ref:`ref-classes-copyleft_filter` class, which is inherited by the | ||
1592 | :ref:`ref-classes-archiver` class. | ||
1593 | |||
1594 | :term:`COPYLEFT_PN_INCLUDE` | ||
1595 | A list of recipes to include in the source archived by the | ||
1596 | :ref:`ref-classes-archiver` class. The :term:`COPYLEFT_PN_INCLUDE` | ||
1597 | variable overrides the license inclusion and exclusion caused through the | ||
1598 | :term:`COPYLEFT_LICENSE_INCLUDE` and :term:`COPYLEFT_LICENSE_EXCLUDE` | ||
1599 | variables, respectively. | ||
1600 | |||
1601 | The default value, which is "" indicating to not explicitly include | ||
1602 | any recipes by name, for :term:`COPYLEFT_PN_INCLUDE` is set by the | ||
1603 | :ref:`ref-classes-copyleft_filter` class, which is inherited by the | ||
1604 | :ref:`ref-classes-archiver` class. | ||
1605 | |||
1606 | :term:`COPYLEFT_RECIPE_TYPES` | ||
1607 | A space-separated list of recipe types to include in the source | ||
1608 | archived by the :ref:`archiver <ref-classes-archiver>` class. | ||
1609 | Recipe types are ``target``, :ref:`ref-classes-native`, | ||
1610 | :ref:`ref-classes-nativesdk`, :ref:`ref-classes-cross`, | ||
1611 | :ref:`ref-classes-crosssdk`, and :ref:`ref-classes-cross-canadian`. | ||
1612 | |||
1613 | The default value, which is "target*", for :term:`COPYLEFT_RECIPE_TYPES` | ||
1614 | is set by the :ref:`ref-classes-copyleft_filter` class, which is | ||
1615 | inherited by the :ref:`ref-classes-archiver` class. | ||
1616 | |||
1425 | :term:`CORE_IMAGE_EXTRA_INSTALL` | 1617 | :term:`CORE_IMAGE_EXTRA_INSTALL` |
1426 | Specifies the list of packages to be added to the image. You should | 1618 | 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 | 1619 | only set this variable in the ``local.conf`` configuration file found |
@@ -1434,24 +1626,24 @@ system and gives an overview of their function and contents. | |||
1434 | Specifies the parent directory of the OpenEmbedded-Core Metadata | 1626 | Specifies the parent directory of the OpenEmbedded-Core Metadata |
1435 | layer (i.e. ``meta``). | 1627 | layer (i.e. ``meta``). |
1436 | 1628 | ||
1437 | It is an important distinction that ``COREBASE`` points to the parent | 1629 | It is an important distinction that :term:`COREBASE` points to the parent |
1438 | of this layer and not the layer itself. Consider an example where you | 1630 | 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 | 1631 | have cloned the Poky Git repository and retained the ``poky`` name |
1440 | for your local copy of the repository. In this case, ``COREBASE`` | 1632 | for your local copy of the repository. In this case, :term:`COREBASE` |
1441 | points to the ``poky`` folder because it is the parent directory of | 1633 | points to the ``poky`` folder because it is the parent directory of |
1442 | the ``poky/meta`` layer. | 1634 | the ``poky/meta`` layer. |
1443 | 1635 | ||
1444 | :term:`COREBASE_FILES` | 1636 | :term:`COREBASE_FILES` |
1445 | Lists files from the :term:`COREBASE` directory that | 1637 | Lists files from the :term:`COREBASE` directory that |
1446 | should be copied other than the layers listed in the | 1638 | should be copied other than the layers listed in the |
1447 | ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for | 1639 | ``bblayers.conf`` file. The :term:`COREBASE_FILES` variable allows |
1448 | the purpose of copying metadata from the OpenEmbedded build system | 1640 | to copy metadata from the OpenEmbedded build system |
1449 | into the extensible SDK. | 1641 | into the extensible SDK. |
1450 | 1642 | ||
1451 | Explicitly listing files in ``COREBASE`` is needed because it | 1643 | Explicitly listing files in :term:`COREBASE` is needed because it |
1452 | typically contains build directories and other files that should not | 1644 | typically contains build directories and other files that should not |
1453 | normally be copied into the extensible SDK. Consequently, the value | 1645 | normally be copied into the extensible SDK. Consequently, the value |
1454 | of ``COREBASE_FILES`` is used in order to only copy the files that | 1646 | of :term:`COREBASE_FILES` is used in order to only copy the files that |
1455 | are actually needed. | 1647 | are actually needed. |
1456 | 1648 | ||
1457 | :term:`CPP` | 1649 | :term:`CPP` |
@@ -1463,7 +1655,7 @@ system and gives an overview of their function and contents. | |||
1463 | variable and thus made visible to the software being built during the | 1655 | variable and thus made visible to the software being built during the |
1464 | compilation step. | 1656 | compilation step. |
1465 | 1657 | ||
1466 | Default initialization for ``CPPFLAGS`` varies depending on what is | 1658 | Default initialization for :term:`CPPFLAGS` varies depending on what is |
1467 | being built: | 1659 | being built: |
1468 | 1660 | ||
1469 | - :term:`TARGET_CPPFLAGS` when building for | 1661 | - :term:`TARGET_CPPFLAGS` when building for |
@@ -1477,15 +1669,103 @@ system and gives an overview of their function and contents. | |||
1477 | 1669 | ||
1478 | :term:`CROSS_COMPILE` | 1670 | :term:`CROSS_COMPILE` |
1479 | The toolchain binary prefix for the target tools. The | 1671 | The toolchain binary prefix for the target tools. The |
1480 | ``CROSS_COMPILE`` variable is the same as the | 1672 | :term:`CROSS_COMPILE` variable is the same as the |
1481 | :term:`TARGET_PREFIX` variable. | 1673 | :term:`TARGET_PREFIX` variable. |
1482 | 1674 | ||
1483 | .. note:: | 1675 | .. note:: |
1484 | 1676 | ||
1485 | The OpenEmbedded build system sets the ``CROSS_COMPILE`` | 1677 | The OpenEmbedded build system sets the :term:`CROSS_COMPILE` |
1486 | variable only in certain contexts (e.g. when building for kernel | 1678 | variable only in certain contexts (e.g. when building for kernel |
1487 | and kernel module recipes). | 1679 | and kernel module recipes). |
1488 | 1680 | ||
1681 | :term:`CVE_CHECK_IGNORE` | ||
1682 | This variable is deprecated and should be replaced by :term:`CVE_STATUS`. | ||
1683 | |||
1684 | :term:`CVE_CHECK_SHOW_WARNINGS` | ||
1685 | Specifies whether or not the :ref:`ref-classes-cve-check` | ||
1686 | class should generate warning messages on the console when unpatched | ||
1687 | CVEs are found. The default is "1", but you may wish to set it to "0" if | ||
1688 | you are already examining/processing the logs after the build has | ||
1689 | completed and thus do not need the warning messages. | ||
1690 | |||
1691 | :term:`CVE_CHECK_SKIP_RECIPE` | ||
1692 | The list of package names (:term:`PN`) for which | ||
1693 | CVEs (Common Vulnerabilities and Exposures) are ignored. | ||
1694 | |||
1695 | :term:`CVE_DB_INCR_UPDATE_AGE_THRES` | ||
1696 | Specifies the maximum age of the CVE database in seconds for an | ||
1697 | incremental update (instead of a full-download). Use "0" to force a | ||
1698 | full-download. | ||
1699 | |||
1700 | :term:`CVE_DB_UPDATE_INTERVAL` | ||
1701 | Specifies the CVE database update interval in seconds, as used by | ||
1702 | ``cve-update-db-native``. The default value is "86400" i.e. once a day | ||
1703 | (24*60*60). If the value is set to "0" then the update will be forced | ||
1704 | every time. Alternatively, a negative value e.g. "-1" will disable | ||
1705 | updates entirely. | ||
1706 | |||
1707 | :term:`CVE_PRODUCT` | ||
1708 | In a recipe, defines the name used to match the recipe name | ||
1709 | against the name in the upstream `NIST CVE database <https://nvd.nist.gov/>`__. | ||
1710 | |||
1711 | The default is ${:term:`BPN`} (except for recipes that inherit the | ||
1712 | :ref:`ref-classes-pypi` class where it is set based upon | ||
1713 | :term:`PYPI_PACKAGE`). If it does not match the name in the NIST CVE | ||
1714 | database or matches with multiple entries in the database, the default | ||
1715 | value needs to be changed. | ||
1716 | |||
1717 | Here is an example from the :oe_layerindex:`Berkeley DB recipe </layerindex/recipe/544>`:: | ||
1718 | |||
1719 | CVE_PRODUCT = "oracle_berkeley_db berkeley_db" | ||
1720 | |||
1721 | Sometimes the product name is not specific enough, for example | ||
1722 | "tar" has been matching CVEs for the GNU ``tar`` package and also | ||
1723 | the ``node-tar`` node.js extension. To avoid this problem, use the | ||
1724 | vendor name as a prefix. The syntax for this is:: | ||
1725 | |||
1726 | CVE_PRODUCT = "vendor:package" | ||
1727 | |||
1728 | :term:`CVE_STATUS` | ||
1729 | The CVE ID which is patched or should be ignored. Here is | ||
1730 | an example from the :oe_layerindex:`Python3 recipe</layerindex/recipe/23823>`:: | ||
1731 | |||
1732 | CVE_STATUS[CVE-2020-15523] = "not-applicable-platform: Issue only applies on Windows" | ||
1733 | |||
1734 | It has the format "reason: description" and the description is optional. | ||
1735 | The Reason is mapped to the final CVE state by mapping via | ||
1736 | :term:`CVE_CHECK_STATUSMAP`. See :ref:`dev-manual/vulnerabilities:fixing vulnerabilities in recipes` | ||
1737 | for details. | ||
1738 | |||
1739 | :term:`CVE_STATUS_GROUPS` | ||
1740 | If there are many CVEs with the same status and reason, they can by simplified by using this | ||
1741 | variable instead of many similar lines with :term:`CVE_STATUS`:: | ||
1742 | |||
1743 | CVE_STATUS_GROUPS = "CVE_STATUS_WIN CVE_STATUS_PATCHED" | ||
1744 | |||
1745 | CVE_STATUS_WIN = "CVE-1234-0001 CVE-1234-0002" | ||
1746 | CVE_STATUS_WIN[status] = "not-applicable-platform: Issue only applies on Windows" | ||
1747 | CVE_STATUS_PATCHED = "CVE-1234-0003 CVE-1234-0004" | ||
1748 | CVE_STATUS_PATCHED[status] = "fixed-version: Fixed externally" | ||
1749 | |||
1750 | :term:`CVE_CHECK_STATUSMAP` | ||
1751 | Mapping variable for all possible reasons of :term:`CVE_STATUS`: | ||
1752 | ``Patched``, ``Unpatched`` and ``Ignored``. | ||
1753 | See :ref:`ref-classes-cve-check` or ``meta/conf/cve-check-map.conf`` for more details:: | ||
1754 | |||
1755 | CVE_CHECK_STATUSMAP[cpe-incorrect] = "Ignored" | ||
1756 | |||
1757 | :term:`CVE_VERSION` | ||
1758 | In a recipe, defines the version used to match the recipe version | ||
1759 | against the version in the `NIST CVE database <https://nvd.nist.gov/>`__ | ||
1760 | when usign :ref:`ref-classes-cve-check`. | ||
1761 | |||
1762 | The default is ${:term:`PV`} but if recipes use custom version numbers | ||
1763 | which do not map to upstream software component release versions and the versions | ||
1764 | used in the CVE database, then this variable can be used to set the | ||
1765 | version number for :ref:`ref-classes-cve-check`. Example:: | ||
1766 | |||
1767 | CVE_VERSION = "2.39" | ||
1768 | |||
1489 | :term:`CVSDIR` | 1769 | :term:`CVSDIR` |
1490 | The directory in which files checked out under the CVS system are | 1770 | The directory in which files checked out under the CVS system are |
1491 | stored. | 1771 | stored. |
@@ -1498,7 +1778,7 @@ system and gives an overview of their function and contents. | |||
1498 | exported to an environment variable and thus made visible to the | 1778 | exported to an environment variable and thus made visible to the |
1499 | software being built during the compilation step. | 1779 | software being built during the compilation step. |
1500 | 1780 | ||
1501 | Default initialization for ``CXXFLAGS`` varies depending on what is | 1781 | Default initialization for :term:`CXXFLAGS` varies depending on what is |
1502 | being built: | 1782 | being built: |
1503 | 1783 | ||
1504 | - :term:`TARGET_CXXFLAGS` when building for | 1784 | - :term:`TARGET_CXXFLAGS` when building for |
@@ -1514,8 +1794,7 @@ system and gives an overview of their function and contents. | |||
1514 | The destination directory. The location in the :term:`Build Directory` | 1794 | The destination directory. The location in the :term:`Build Directory` |
1515 | where components are installed by the | 1795 | where components are installed by the |
1516 | :ref:`ref-tasks-install` task. This location defaults | 1796 | :ref:`ref-tasks-install` task. This location defaults |
1517 | to: | 1797 | to:: |
1518 | :: | ||
1519 | 1798 | ||
1520 | ${WORKDIR}/image | 1799 | ${WORKDIR}/image |
1521 | 1800 | ||
@@ -1533,54 +1812,69 @@ system and gives an overview of their function and contents. | |||
1533 | suitable for timestamps. | 1812 | suitable for timestamps. |
1534 | 1813 | ||
1535 | :term:`DEBIAN_NOAUTONAME` | 1814 | :term:`DEBIAN_NOAUTONAME` |
1536 | When the :ref:`debian <ref-classes-debian>` class is inherited, | 1815 | When the :ref:`ref-classes-debian` class is inherited, |
1537 | which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a | 1816 | which is the default behavior, :term:`DEBIAN_NOAUTONAME` specifies a |
1538 | particular package should not be renamed according to Debian library | 1817 | particular package should not be renamed according to Debian library |
1539 | package naming. You must use the package name as an override when you | 1818 | 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: | 1819 | set this variable. Here is an example from the ``fontconfig`` recipe:: |
1541 | :: | ||
1542 | 1820 | ||
1543 | DEBIAN_NOAUTONAME_fontconfig-utils = "1" | 1821 | DEBIAN_NOAUTONAME:fontconfig-utils = "1" |
1544 | 1822 | ||
1545 | :term:`DEBIANNAME` | 1823 | :term:`DEBIANNAME` |
1546 | When the :ref:`debian <ref-classes-debian>` class is inherited, | 1824 | When the :ref:`ref-classes-debian` class is inherited, |
1547 | which is the default behavior, ``DEBIANNAME`` allows you to override | 1825 | which is the default behavior, :term:`DEBIANNAME` allows you to override |
1548 | the library name for an individual package. Overriding the library | 1826 | 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 | 1827 | 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 | 1828 | override when you set this variable. Here is an example from the |
1551 | ``dbus`` recipe: | 1829 | ``dbus`` recipe:: |
1552 | :: | ||
1553 | 1830 | ||
1554 | DEBIANNAME_${PN} = "dbus-1" | 1831 | DEBIANNAME:${PN} = "dbus-1" |
1555 | 1832 | ||
1556 | :term:`DEBUG_BUILD` | 1833 | :term:`DEBUG_BUILD` |
1557 | Specifies to build packages with debugging information. This | 1834 | Specifies to build packages with debugging information. This |
1558 | influences the value of the ``SELECTED_OPTIMIZATION`` variable. | 1835 | influences the value of the :term:`SELECTED_OPTIMIZATION` variable. |
1559 | 1836 | ||
1560 | :term:`DEBUG_OPTIMIZATION` | 1837 | :term:`DEBUG_OPTIMIZATION` |
1561 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | 1838 | The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when |
1562 | compiling a system for debugging. This variable defaults to "-O | 1839 | compiling a system for debugging. This variable defaults to "-O |
1563 | -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". | 1840 | -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". |
1564 | 1841 | ||
1842 | :term:`DEBUG_PREFIX_MAP` | ||
1843 | Allows to set C compiler options, such as ``-fdebug-prefix-map``, | ||
1844 | ``-fmacro-prefix-map``, and ``-ffile-prefix-map``, which allow to | ||
1845 | replace build-time paths by install-time ones in the debugging sections | ||
1846 | of binaries. This makes compiler output files location independent, | ||
1847 | at the cost of having to pass an extra command to tell the debugger | ||
1848 | where source files are. | ||
1849 | |||
1850 | This is used by the Yocto Project to guarantee | ||
1851 | :doc:`/test-manual/reproducible-builds` even when the source code of | ||
1852 | a package uses the ``__FILE__`` or ``assert()`` macros. See the | ||
1853 | `reproducible-builds.org <https://reproducible-builds.org/docs/build-path/>`__ | ||
1854 | website for details. | ||
1855 | |||
1856 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | ||
1857 | not intended to be user-configurable. | ||
1858 | |||
1565 | :term:`DEFAULT_PREFERENCE` | 1859 | :term:`DEFAULT_PREFERENCE` |
1566 | Specifies a weak bias for recipe selection priority. | 1860 | Specifies a weak bias for recipe selection priority. |
1567 | 1861 | ||
1568 | The most common usage of this is variable is to set it to "-1" within | 1862 | 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 | 1863 | 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 | 1864 | 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 | 1865 | by default in the absence of :term:`PREFERRED_VERSION` being used to |
1572 | build the development version. | 1866 | build the development version. |
1573 | 1867 | ||
1574 | .. note:: | 1868 | .. note:: |
1575 | 1869 | ||
1576 | The bias provided by ``DEFAULT_PREFERENCE`` is weak and is overridden | 1870 | The bias provided by :term:`DEFAULT_PREFERENCE` is weak and is overridden |
1577 | by :term:`BBFILE_PRIORITY` if that variable is different between two | 1871 | by :term:`BBFILE_PRIORITY` if that variable is different between two |
1578 | layers that contain different versions of the same recipe. | 1872 | layers that contain different versions of the same recipe. |
1579 | 1873 | ||
1580 | :term:`DEFAULTTUNE` | 1874 | :term:`DEFAULTTUNE` |
1581 | The default CPU and Application Binary Interface (ABI) tunings (i.e. | 1875 | The default CPU and Application Binary Interface (ABI) tunings (i.e. |
1582 | the "tune") used by the OpenEmbedded build system. The | 1876 | the "tune") used by the OpenEmbedded build system. The |
1583 | ``DEFAULTTUNE`` helps define | 1877 | :term:`DEFAULTTUNE` helps define |
1584 | :term:`TUNE_FEATURES`. | 1878 | :term:`TUNE_FEATURES`. |
1585 | 1879 | ||
1586 | The default tune is either implicitly or explicitly set by the | 1880 | The default tune is either implicitly or explicitly set by the |
@@ -1594,83 +1888,79 @@ system and gives an overview of their function and contents. | |||
1594 | needed by the recipe at build time. | 1888 | needed by the recipe at build time. |
1595 | 1889 | ||
1596 | As an example, consider a recipe ``foo`` that contains the following | 1890 | As an example, consider a recipe ``foo`` that contains the following |
1597 | assignment: | 1891 | assignment:: |
1598 | :: | ||
1599 | 1892 | ||
1600 | DEPENDS = "bar" | 1893 | DEPENDS = "bar" |
1601 | 1894 | ||
1602 | The practical effect of the previous | 1895 | The practical effect of the previous assignment is that all files |
1603 | assignment is that all files installed by bar will be available in | 1896 | installed by bar will be available in the appropriate staging sysroot, |
1604 | the appropriate staging sysroot, given by the | 1897 | given by the :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time |
1605 | :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the | 1898 | the :ref:`ref-tasks-configure` task for ``foo`` runs. This mechanism is |
1606 | :ref:`ref-tasks-configure` task for ``foo`` runs. | 1899 | implemented by having :ref:`ref-tasks-configure` depend on the |
1607 | This mechanism is implemented by having ``do_configure`` depend on | 1900 | :ref:`ref-tasks-populate_sysroot` task of each recipe listed in |
1608 | the :ref:`ref-tasks-populate_sysroot` task of | 1901 | :term:`DEPENDS`, through a |
1609 | each recipe listed in ``DEPENDS``, through a | 1902 | ``[``\ :ref:`deptask <bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` |
1610 | ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` | 1903 | declaration in the :ref:`ref-classes-base` class. |
1611 | declaration in the :ref:`base <ref-classes-base>` class. | ||
1612 | 1904 | ||
1613 | .. note:: | 1905 | .. note:: |
1614 | 1906 | ||
1615 | It seldom is necessary to reference, for example, ``STAGING_DIR_HOST`` | 1907 | It seldom is necessary to reference, for example, :term:`STAGING_DIR_HOST` |
1616 | explicitly. The standard classes and build-related variables are | 1908 | explicitly. The standard classes and build-related variables are |
1617 | configured to automatically use the appropriate staging sysroots. | 1909 | configured to automatically use the appropriate staging sysroots. |
1618 | 1910 | ||
1619 | As another example, ``DEPENDS`` can also be used to add utilities | 1911 | As another example, :term:`DEPENDS` can also be used to add utilities |
1620 | that run on the build machine during the build. For example, a recipe | 1912 | 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`` | 1913 | that makes use of a code generator built by the recipe ``codegen`` |
1622 | might have the following: | 1914 | might have the following:: |
1623 | :: | ||
1624 | 1915 | ||
1625 | DEPENDS = "codegen-native" | 1916 | DEPENDS = "codegen-native" |
1626 | 1917 | ||
1627 | For more | 1918 | For more |
1628 | information, see the :ref:`native <ref-classes-native>` class and | 1919 | information, see the :ref:`ref-classes-native` class and |
1629 | the :term:`EXTRANATIVEPATH` variable. | 1920 | the :term:`EXTRANATIVEPATH` variable. |
1630 | 1921 | ||
1631 | .. note:: | 1922 | .. note:: |
1632 | 1923 | ||
1633 | - ``DEPENDS`` is a list of recipe names. Or, to be more precise, | 1924 | - :term:`DEPENDS` is a list of recipe names. Or, to be more precise, |
1634 | it is a list of :term:`PROVIDES` names, which | 1925 | it is a list of :term:`PROVIDES` names, which |
1635 | usually match recipe names. Putting a package name such as | 1926 | usually match recipe names. Putting a package name such as |
1636 | "foo-dev" in ``DEPENDS`` does not make sense. Use "foo" | 1927 | "foo-dev" in :term:`DEPENDS` does not make sense. Use "foo" |
1637 | instead, as this will put files from all the packages that make | 1928 | instead, as this will put files from all the packages that make |
1638 | up ``foo``, which includes those from ``foo-dev``, into the | 1929 | up ``foo``, which includes those from ``foo-dev``, into the |
1639 | sysroot. | 1930 | sysroot. |
1640 | 1931 | ||
1641 | - One recipe having another recipe in ``DEPENDS`` does not by | 1932 | - One recipe having another recipe in :term:`DEPENDS` does not by |
1642 | itself add any runtime dependencies between the packages | 1933 | itself add any runtime dependencies between the packages |
1643 | produced by the two recipes. However, as explained in the | 1934 | produced by the two recipes. However, as explained in the |
1644 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | 1935 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" |
1645 | section in the Yocto Project Overview and Concepts Manual, | 1936 | section in the Yocto Project Overview and Concepts Manual, |
1646 | runtime dependencies will often be added automatically, meaning | 1937 | runtime dependencies will often be added automatically, meaning |
1647 | ``DEPENDS`` alone is sufficient for most recipes. | 1938 | :term:`DEPENDS` alone is sufficient for most recipes. |
1648 | 1939 | ||
1649 | - Counterintuitively, ``DEPENDS`` is often necessary even for | 1940 | - Counterintuitively, :term:`DEPENDS` is often necessary even for |
1650 | recipes that install precompiled components. For example, if | 1941 | recipes that install precompiled components. For example, if |
1651 | ``libfoo`` is a precompiled library that links against | 1942 | ``libfoo`` is a precompiled library that links against |
1652 | ``libbar``, then linking against ``libfoo`` requires both | 1943 | ``libbar``, then linking against ``libfoo`` requires both |
1653 | ``libfoo`` and ``libbar`` to be available in the sysroot. | 1944 | ``libfoo`` and ``libbar`` to be available in the sysroot. |
1654 | Without a ``DEPENDS`` from the recipe that installs ``libfoo`` | 1945 | Without a :term:`DEPENDS` from the recipe that installs ``libfoo`` |
1655 | to the recipe that installs ``libbar``, other recipes might | 1946 | to the recipe that installs ``libbar``, other recipes might |
1656 | fail to link against ``libfoo``. | 1947 | fail to link against ``libfoo``. |
1657 | 1948 | ||
1658 | For information on runtime dependencies, see the | 1949 | For information on runtime dependencies, see the :term:`RDEPENDS` |
1659 | :term:`RDEPENDS` variable. You can also see the | 1950 | variable. You can also see the |
1660 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | 1951 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and |
1661 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | 1952 | ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" |
1662 | BitBake User Manual for additional information on tasks and | 1953 | sections in the BitBake User Manual for additional information on tasks |
1663 | dependencies. | 1954 | and dependencies. |
1664 | 1955 | ||
1665 | :term:`DEPLOY_DIR` | 1956 | :term:`DEPLOY_DIR` |
1666 | Points to the general area that the OpenEmbedded build system uses to | 1957 | Points to the general area that the OpenEmbedded build system uses to |
1667 | place images, packages, SDKs, and other output files that are ready | 1958 | place images, packages, SDKs, and other output files that are ready |
1668 | to be used outside of the build system. By default, this directory | 1959 | to be used outside of the build system. By default, this directory |
1669 | resides within the :term:`Build Directory` as | 1960 | resides within the :term:`Build Directory` as ``${TMPDIR}/deploy``. |
1670 | ``${TMPDIR}/deploy``. | ||
1671 | 1961 | ||
1672 | For more information on the structure of the Build Directory, see | 1962 | For more information on the structure of the Build Directory, see |
1673 | ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. | 1963 | ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. |
1674 | For more detail on the contents of the ``deploy`` directory, see the | 1964 | For more detail on the contents of the ``deploy`` directory, see the |
1675 | ":ref:`overview-manual/concepts:images`", | 1965 | ":ref:`overview-manual/concepts:images`", |
1676 | ":ref:`overview-manual/concepts:package feeds`", and | 1966 | ":ref:`overview-manual/concepts:package feeds`", and |
@@ -1680,19 +1970,17 @@ system and gives an overview of their function and contents. | |||
1680 | :term:`DEPLOY_DIR_DEB` | 1970 | :term:`DEPLOY_DIR_DEB` |
1681 | Points to the area that the OpenEmbedded build system uses to place | 1971 | 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 | 1972 | Debian packages that are ready to be used outside of the build |
1683 | system. This variable applies only when | 1973 | system. This variable applies only when :term:`PACKAGE_CLASSES` contains |
1684 | :term:`PACKAGE_CLASSES` contains | 1974 | ":ref:`ref-classes-package_deb`". |
1685 | "package_deb". | ||
1686 | 1975 | ||
1687 | The BitBake configuration file initially defines the | 1976 | The BitBake configuration file initially defines the |
1688 | ``DEPLOY_DIR_DEB`` variable as a sub-folder of | 1977 | :term:`DEPLOY_DIR_DEB` variable as a sub-folder of |
1689 | :term:`DEPLOY_DIR`: | 1978 | :term:`DEPLOY_DIR`:: |
1690 | :: | ||
1691 | 1979 | ||
1692 | DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" | 1980 | DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb" |
1693 | 1981 | ||
1694 | The :ref:`package_deb <ref-classes-package_deb>` class uses the | 1982 | The :ref:`ref-classes-package_deb` class uses the |
1695 | ``DEPLOY_DIR_DEB`` variable to make sure the | 1983 | :term:`DEPLOY_DIR_DEB` variable to make sure the |
1696 | :ref:`ref-tasks-package_write_deb` task | 1984 | :ref:`ref-tasks-package_write_deb` task |
1697 | writes Debian packages into the appropriate folder. For more | 1985 | writes Debian packages into the appropriate folder. For more |
1698 | information on how packaging works, see the | 1986 | information on how packaging works, see the |
@@ -1707,8 +1995,14 @@ system and gives an overview of their function and contents. | |||
1707 | resides within the :term:`Build Directory` as | 1995 | resides within the :term:`Build Directory` as |
1708 | ``${DEPLOY_DIR}/images/${MACHINE}/``. | 1996 | ``${DEPLOY_DIR}/images/${MACHINE}/``. |
1709 | 1997 | ||
1710 | For more information on the structure of the Build Directory, see | 1998 | It must not be used directly in recipes when deploying files. Instead, |
1711 | ":ref:`ref-manual/structure:the build directory - \`\`build/\`\``" section. | 1999 | it's only useful when a recipe needs to "read" a file already deployed |
2000 | by a dependency. So, it should be filled with the contents of | ||
2001 | :term:`DEPLOYDIR` by the :ref:`ref-classes-deploy` class or with the | ||
2002 | contents of :term:`IMGDEPLOYDIR` by the :ref:`ref-classes-image` class. | ||
2003 | |||
2004 | For more information on the structure of the :term:`Build Directory`, see | ||
2005 | ":ref:`ref-manual/structure:the build directory --- \`\`build/\`\``" section. | ||
1712 | For more detail on the contents of the ``deploy`` directory, see the | 2006 | For more detail on the contents of the ``deploy`` directory, see the |
1713 | ":ref:`overview-manual/concepts:images`" and | 2007 | ":ref:`overview-manual/concepts:images`" and |
1714 | ":ref:`overview-manual/concepts:application development sdk`" sections both in | 2008 | ":ref:`overview-manual/concepts:application development sdk`" sections both in |
@@ -1717,19 +2011,16 @@ system and gives an overview of their function and contents. | |||
1717 | :term:`DEPLOY_DIR_IPK` | 2011 | :term:`DEPLOY_DIR_IPK` |
1718 | Points to the area that the OpenEmbedded build system uses to place | 2012 | 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. | 2013 | IPK packages that are ready to be used outside of the build system. |
1720 | This variable applies only when | 2014 | This variable applies only when :term:`PACKAGE_CLASSES` contains |
1721 | :term:`PACKAGE_CLASSES` contains | 2015 | ":ref:`ref-classes-package_ipk`". |
1722 | "package_ipk". | ||
1723 | 2016 | ||
1724 | The BitBake configuration file initially defines this variable as a | 2017 | The BitBake configuration file initially defines this variable as a |
1725 | sub-folder of :term:`DEPLOY_DIR`: | 2018 | sub-folder of :term:`DEPLOY_DIR`:: |
1726 | :: | ||
1727 | 2019 | ||
1728 | DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" | 2020 | DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk" |
1729 | 2021 | ||
1730 | The :ref:`package_ipk <ref-classes-package_ipk>` class uses the | 2022 | The :ref:`ref-classes-package_ipk` class uses the :term:`DEPLOY_DIR_IPK` |
1731 | ``DEPLOY_DIR_IPK`` variable to make sure the | 2023 | variable to make sure the :ref:`ref-tasks-package_write_ipk` task |
1732 | :ref:`ref-tasks-package_write_ipk` task | ||
1733 | writes IPK packages into the appropriate folder. For more information | 2024 | writes IPK packages into the appropriate folder. For more information |
1734 | on how packaging works, see the | 2025 | on how packaging works, see the |
1735 | ":ref:`overview-manual/concepts:package feeds`" section | 2026 | ":ref:`overview-manual/concepts:package feeds`" section |
@@ -1738,89 +2029,81 @@ system and gives an overview of their function and contents. | |||
1738 | :term:`DEPLOY_DIR_RPM` | 2029 | :term:`DEPLOY_DIR_RPM` |
1739 | Points to the area that the OpenEmbedded build system uses to place | 2030 | 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. | 2031 | RPM packages that are ready to be used outside of the build system. |
1741 | This variable applies only when | 2032 | This variable applies only when :term:`PACKAGE_CLASSES` contains |
1742 | :term:`PACKAGE_CLASSES` contains | 2033 | ":ref:`ref-classes-package_rpm`". |
1743 | "package_rpm". | ||
1744 | 2034 | ||
1745 | The BitBake configuration file initially defines this variable as a | 2035 | The BitBake configuration file initially defines this variable as a |
1746 | sub-folder of :term:`DEPLOY_DIR`: | 2036 | sub-folder of :term:`DEPLOY_DIR`:: |
1747 | :: | ||
1748 | 2037 | ||
1749 | DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" | 2038 | DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm" |
1750 | 2039 | ||
1751 | The :ref:`package_rpm <ref-classes-package_rpm>` class uses the | 2040 | The :ref:`ref-classes-package_rpm` class uses the |
1752 | ``DEPLOY_DIR_RPM`` variable to make sure the | 2041 | :term:`DEPLOY_DIR_RPM` variable to make sure the |
1753 | :ref:`ref-tasks-package_write_rpm` task | 2042 | :ref:`ref-tasks-package_write_rpm` task |
1754 | writes RPM packages into the appropriate folder. For more information | 2043 | writes RPM packages into the appropriate folder. For more information |
1755 | on how packaging works, see the | 2044 | on how packaging works, see the |
1756 | ":ref:`overview-manual/concepts:package feeds`" section | 2045 | ":ref:`overview-manual/concepts:package feeds`" section |
1757 | in the Yocto Project Overview and Concepts Manual. | 2046 | in the Yocto Project Overview and Concepts Manual. |
1758 | 2047 | ||
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` | 2048 | :term:`DEPLOYDIR` |
1781 | When inheriting the :ref:`deploy <ref-classes-deploy>` class, the | 2049 | When inheriting the :ref:`ref-classes-deploy` class, the |
1782 | ``DEPLOYDIR`` points to a temporary work area for deployed files that | 2050 | :term:`DEPLOYDIR` points to a temporary work area for deployed files that |
1783 | is set in the ``deploy`` class as follows: | 2051 | is set in the :ref:`ref-classes-deploy` class as follows:: |
1784 | :: | ||
1785 | 2052 | ||
1786 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" | 2053 | DEPLOYDIR = "${WORKDIR}/deploy-${PN}" |
1787 | 2054 | ||
1788 | Recipes inheriting the ``deploy`` class should copy files to be | 2055 | Recipes inheriting the :ref:`ref-classes-deploy` class should copy files to be |
1789 | deployed into ``DEPLOYDIR``, and the class will take care of copying | 2056 | deployed into :term:`DEPLOYDIR`, and the class will take care of copying |
1790 | them into :term:`DEPLOY_DIR_IMAGE` | 2057 | them into :term:`DEPLOY_DIR_IMAGE` |
1791 | afterwards. | 2058 | afterwards. |
1792 | 2059 | ||
1793 | :term:`DESCRIPTION` | 2060 | :term:`DESCRIPTION` |
1794 | The package description used by package managers. If not set, | 2061 | The package description used by package managers. If not set, |
1795 | ``DESCRIPTION`` takes the value of the :term:`SUMMARY` | 2062 | :term:`DESCRIPTION` takes the value of the :term:`SUMMARY` |
1796 | variable. | 2063 | variable. |
1797 | 2064 | ||
2065 | :term:`DEV_PKG_DEPENDENCY` | ||
2066 | Provides an easy way for recipes to disable or adjust the runtime recommendation | ||
2067 | (:term:`RRECOMMENDS`) of the ``${PN}-dev`` package on the main | ||
2068 | (``${PN}``) package. | ||
2069 | |||
2070 | :term:`DISABLE_STATIC` | ||
2071 | Used in order to disable static linking by default (in order to save | ||
2072 | space, since static libraries are often unused in embedded systems.) | ||
2073 | The default value is " --disable-static", however it can be set to "" | ||
2074 | in order to enable static linking if desired. Certain recipes do this | ||
2075 | individually, and also there is a | ||
2076 | ``meta/conf/distro/include/no-static-libs.inc`` include file that | ||
2077 | disables static linking for a number of recipes. Some software | ||
2078 | packages or build tools (such as CMake) have explicit support for | ||
2079 | enabling / disabling static linking, and in those cases | ||
2080 | :term:`DISABLE_STATIC` is not used. | ||
2081 | |||
1798 | :term:`DISTRO` | 2082 | :term:`DISTRO` |
1799 | The short name of the distribution. For information on the long name | 2083 | The short name of the distribution. For information on the long name |
1800 | of the distribution, see the :term:`DISTRO_NAME` | 2084 | of the distribution, see the :term:`DISTRO_NAME` |
1801 | variable. | 2085 | variable. |
1802 | 2086 | ||
1803 | The ``DISTRO`` variable corresponds to a distribution configuration | 2087 | The :term:`DISTRO` variable corresponds to a distribution configuration |
1804 | file whose root name is the same as the variable's argument and whose | 2088 | file whose root name is the same as the variable's argument and whose |
1805 | filename extension is ``.conf``. For example, the distribution | 2089 | filename extension is ``.conf``. For example, the distribution |
1806 | configuration file for the Poky distribution is named ``poky.conf`` | 2090 | configuration file for the Poky distribution is named ``poky.conf`` |
1807 | and resides in the ``meta-poky/conf/distro`` directory of the | 2091 | and resides in the ``meta-poky/conf/distro`` directory of the |
1808 | :term:`Source Directory`. | 2092 | :term:`Source Directory`. |
1809 | 2093 | ||
1810 | Within that ``poky.conf`` file, the ``DISTRO`` variable is set as | 2094 | Within that ``poky.conf`` file, the :term:`DISTRO` variable is set as |
1811 | follows: | 2095 | follows:: |
1812 | :: | ||
1813 | 2096 | ||
1814 | DISTRO = "poky" | 2097 | DISTRO = "poky" |
1815 | 2098 | ||
1816 | Distribution configuration files are located in a ``conf/distro`` | 2099 | Distribution configuration files are located in a ``conf/distro`` |
1817 | directory within the :term:`Metadata` that contains the | 2100 | directory within the :term:`Metadata` that contains the |
1818 | distribution configuration. The value for ``DISTRO`` must not contain | 2101 | distribution configuration. The value for :term:`DISTRO` must not contain |
1819 | spaces, and is typically all lower-case. | 2102 | spaces, and is typically all lower-case. |
1820 | 2103 | ||
1821 | .. note:: | 2104 | .. note:: |
1822 | 2105 | ||
1823 | If the ``DISTRO`` variable is blank, a set of default configurations | 2106 | If the :term:`DISTRO` variable is blank, a set of default configurations |
1824 | are used, which are specified within | 2107 | are used, which are specified within |
1825 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. | 2108 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. |
1826 | 2109 | ||
@@ -1829,7 +2112,7 @@ system and gives an overview of their function and contents. | |||
1829 | 2112 | ||
1830 | :term:`DISTRO_EXTRA_RDEPENDS` | 2113 | :term:`DISTRO_EXTRA_RDEPENDS` |
1831 | Specifies a list of distro-specific packages to add to all images. | 2114 | Specifies a list of distro-specific packages to add to all images. |
1832 | This variable takes affect through ``packagegroup-base`` so the | 2115 | This variable takes effect through ``packagegroup-base`` so the |
1833 | variable only really applies to the more full-featured images that | 2116 | variable only really applies to the more full-featured images that |
1834 | include ``packagegroup-base``. You can use this variable to keep | 2117 | include ``packagegroup-base``. You can use this variable to keep |
1835 | distro policy out of generic images. As with all other distro | 2118 | distro policy out of generic images. As with all other distro |
@@ -1847,32 +2130,47 @@ system and gives an overview of their function and contents. | |||
1847 | configuration file. | 2130 | configuration file. |
1848 | 2131 | ||
1849 | In most cases, the presence or absence of a feature in | 2132 | In most cases, the presence or absence of a feature in |
1850 | ``DISTRO_FEATURES`` is translated to the appropriate option supplied | 2133 | :term:`DISTRO_FEATURES` is translated to the appropriate option supplied |
1851 | to the configure script during the | 2134 | to the configure script during the |
1852 | :ref:`ref-tasks-configure` task for recipes that | 2135 | :ref:`ref-tasks-configure` task for recipes that |
1853 | optionally support the feature. For example, specifying "x11" in | 2136 | optionally support the feature. For example, specifying "x11" in |
1854 | ``DISTRO_FEATURES``, causes every piece of software built for the | 2137 | :term:`DISTRO_FEATURES`, causes every piece of software built for the |
1855 | target that can optionally support X11 to have its X11 support | 2138 | target that can optionally support X11 to have its X11 support |
1856 | enabled. | 2139 | enabled. |
1857 | 2140 | ||
2141 | .. note:: | ||
2142 | |||
2143 | Just enabling :term:`DISTRO_FEATURES` alone doesn't | ||
2144 | enable feature support for packages. Mechanisms such as making | ||
2145 | :term:`PACKAGECONFIG` track :term:`DISTRO_FEATURES` are used | ||
2146 | to enable/disable package features. | ||
2147 | |||
1858 | Two more examples are Bluetooth and NFS support. For a more complete | 2148 | 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 | 2149 | 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. | 2150 | provide with this variable, see the ":ref:`ref-features-distro`" section. |
1861 | 2151 | ||
1862 | :term:`DISTRO_FEATURES_BACKFILL` | 2152 | :term:`DISTRO_FEATURES_BACKFILL` |
1863 | Features to be added to ``DISTRO_FEATURES`` if not also present in | 2153 | A space-separated list of features to be added to :term:`DISTRO_FEATURES` |
1864 | ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. | 2154 | if not also present in :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED`. |
1865 | 2155 | ||
1866 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | 2156 | 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 | 2157 | not intended to be user-configurable. It is best to just reference |
1868 | the variable to see which distro features are being backfilled for | 2158 | the variable to see which distro features are being |
1869 | all distro configurations. See the ":ref:`ref-features-backfill`" section | 2159 | :ref:`backfilled <ref-features-backfill>` for all distro configurations. |
1870 | for more information. | ||
1871 | 2160 | ||
1872 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` | 2161 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` |
1873 | Features from ``DISTRO_FEATURES_BACKFILL`` that should not be | 2162 | A space-separated list of features from :term:`DISTRO_FEATURES_BACKFILL` |
1874 | backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See | 2163 | that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added |
1875 | the ":ref:`ref-features-backfill`" section for more information. | 2164 | to :term:`DISTRO_FEATURES`) during the build. |
2165 | |||
2166 | This corresponds to an opt-out mechanism. When new default distro | ||
2167 | features are introduced, distribution maintainers can review (`consider`) | ||
2168 | them and decide to exclude them from the | ||
2169 | :ref:`backfilled <ref-features-backfill>` features. Therefore, the | ||
2170 | combination of :term:`DISTRO_FEATURES_BACKFILL` and | ||
2171 | :term:`DISTRO_FEATURES_BACKFILL_CONSIDERED` makes it possible to | ||
2172 | add new default features without breaking existing distributions. | ||
2173 | |||
1876 | 2174 | ||
1877 | :term:`DISTRO_FEATURES_DEFAULT` | 2175 | :term:`DISTRO_FEATURES_DEFAULT` |
1878 | A convenience variable that gives you the default list of distro | 2176 | A convenience variable that gives you the default list of distro |
@@ -1883,26 +2181,24 @@ system and gives an overview of their function and contents. | |||
1883 | able to reuse the default | 2181 | able to reuse the default |
1884 | :term:`DISTRO_FEATURES` options without the | 2182 | :term:`DISTRO_FEATURES` options without the |
1885 | need to write out the full set. Here is an example that uses | 2183 | need to write out the full set. Here is an example that uses |
1886 | ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: | 2184 | :term:`DISTRO_FEATURES_DEFAULT` from a custom distro configuration file:: |
1887 | :: | ||
1888 | 2185 | ||
1889 | DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" | 2186 | DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" |
1890 | 2187 | ||
1891 | :term:`DISTRO_FEATURES_FILTER_NATIVE` | 2188 | :term:`DISTRO_FEATURES_FILTER_NATIVE` |
1892 | Specifies a list of features that if present in the target | 2189 | Specifies a list of features that if present in the target |
1893 | :term:`DISTRO_FEATURES` value should be | 2190 | :term:`DISTRO_FEATURES` value should be |
1894 | included in ``DISTRO_FEATURES`` when building native recipes. This | 2191 | included in :term:`DISTRO_FEATURES` when building native recipes. This |
1895 | variable is used in addition to the features filtered using the | 2192 | variable is used in addition to the features filtered using the |
1896 | :term:`DISTRO_FEATURES_NATIVE` | 2193 | :term:`DISTRO_FEATURES_NATIVE` |
1897 | variable. | 2194 | variable. |
1898 | 2195 | ||
1899 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` | 2196 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` |
1900 | Specifies a list of features that if present in the target | 2197 | Specifies a list of features that if present in the target |
1901 | :term:`DISTRO_FEATURES` value should be | 2198 | :term:`DISTRO_FEATURES` value should be included in |
1902 | included in ``DISTRO_FEATURES`` when building nativesdk recipes. This | 2199 | :term:`DISTRO_FEATURES` when building :ref:`ref-classes-nativesdk` |
1903 | variable is used in addition to the features filtered using the | 2200 | recipes. This variable is used in addition to the features filtered using |
1904 | :term:`DISTRO_FEATURES_NATIVESDK` | 2201 | the :term:`DISTRO_FEATURES_NATIVESDK` variable. |
1905 | variable. | ||
1906 | 2202 | ||
1907 | :term:`DISTRO_FEATURES_NATIVE` | 2203 | :term:`DISTRO_FEATURES_NATIVE` |
1908 | Specifies a list of features that should be included in | 2204 | Specifies a list of features that should be included in |
@@ -1915,25 +2211,23 @@ system and gives an overview of their function and contents. | |||
1915 | :term:`DISTRO_FEATURES_NATIVESDK` | 2211 | :term:`DISTRO_FEATURES_NATIVESDK` |
1916 | Specifies a list of features that should be included in | 2212 | Specifies a list of features that should be included in |
1917 | :term:`DISTRO_FEATURES` when building | 2213 | :term:`DISTRO_FEATURES` when building |
1918 | nativesdk recipes. This variable is used in addition to the features | 2214 | :ref:`ref-classes-nativesdk` recipes. This variable is used |
1919 | filtered using the | 2215 | in addition to the features filtered using the |
1920 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` | 2216 | :term:`DISTRO_FEATURES_FILTER_NATIVESDK` variable. |
1921 | variable. | ||
1922 | 2217 | ||
1923 | :term:`DISTRO_NAME` | 2218 | :term:`DISTRO_NAME` |
1924 | The long name of the distribution. For information on the short name | 2219 | The long name of the distribution. For information on the short name |
1925 | of the distribution, see the :term:`DISTRO` variable. | 2220 | of the distribution, see the :term:`DISTRO` variable. |
1926 | 2221 | ||
1927 | The ``DISTRO_NAME`` variable corresponds to a distribution | 2222 | The :term:`DISTRO_NAME` variable corresponds to a distribution |
1928 | configuration file whose root name is the same as the variable's | 2223 | configuration file whose root name is the same as the variable's |
1929 | argument and whose filename extension is ``.conf``. For example, the | 2224 | argument and whose filename extension is ``.conf``. For example, the |
1930 | distribution configuration file for the Poky distribution is named | 2225 | distribution configuration file for the Poky distribution is named |
1931 | ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory | 2226 | ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory |
1932 | of the :term:`Source Directory`. | 2227 | of the :term:`Source Directory`. |
1933 | 2228 | ||
1934 | Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set | 2229 | Within that ``poky.conf`` file, the :term:`DISTRO_NAME` variable is set |
1935 | as follows: | 2230 | as follows:: |
1936 | :: | ||
1937 | 2231 | ||
1938 | DISTRO_NAME = "Poky (Yocto Project Reference Distro)" | 2232 | DISTRO_NAME = "Poky (Yocto Project Reference Distro)" |
1939 | 2233 | ||
@@ -1943,7 +2237,7 @@ system and gives an overview of their function and contents. | |||
1943 | 2237 | ||
1944 | .. note:: | 2238 | .. note:: |
1945 | 2239 | ||
1946 | If the ``DISTRO_NAME`` variable is blank, a set of default | 2240 | If the :term:`DISTRO_NAME` variable is blank, a set of default |
1947 | configurations are used, which are specified within | 2241 | configurations are used, which are specified within |
1948 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. | 2242 | ``meta/conf/distro/defaultsetup.conf`` also in the Source Directory. |
1949 | 2243 | ||
@@ -1955,26 +2249,30 @@ system and gives an overview of their function and contents. | |||
1955 | distribution. By default, this list includes the value of | 2249 | distribution. By default, this list includes the value of |
1956 | :term:`DISTRO`. | 2250 | :term:`DISTRO`. |
1957 | 2251 | ||
1958 | You can extend ``DISTROOVERRIDES`` to add extra overrides that should | 2252 | You can extend :term:`DISTROOVERRIDES` to add extra overrides that should |
1959 | apply to the distribution. | 2253 | apply to the distribution. |
1960 | 2254 | ||
1961 | The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it | 2255 | The underlying mechanism behind :term:`DISTROOVERRIDES` is simply that it |
1962 | is included in the default value of | 2256 | is included in the default value of |
1963 | :term:`OVERRIDES`. | 2257 | :term:`OVERRIDES`. |
1964 | 2258 | ||
2259 | Here is an example from :yocto_git:`meta-poky/conf/distro/poky-tiny.conf | ||
2260 | </poky/tree/meta-poky/conf/distro/poky-tiny.conf>`:: | ||
2261 | |||
2262 | DISTROOVERRIDES = "poky:poky-tiny" | ||
2263 | |||
1965 | :term:`DL_DIR` | 2264 | :term:`DL_DIR` |
1966 | The central download directory used by the build process to store | 2265 | The central download directory used by the build process to store |
1967 | downloads. By default, ``DL_DIR`` gets files suitable for mirroring | 2266 | downloads. By default, :term:`DL_DIR` gets files suitable for mirroring |
1968 | for everything except Git repositories. If you want tarballs of Git | 2267 | for everything except Git repositories. If you want tarballs of Git |
1969 | repositories, use the | 2268 | repositories, use the |
1970 | :term:`BB_GENERATE_MIRROR_TARBALLS` | 2269 | :term:`BB_GENERATE_MIRROR_TARBALLS` |
1971 | variable. | 2270 | variable. |
1972 | 2271 | ||
1973 | You can set this directory by defining the ``DL_DIR`` variable in the | 2272 | You can set this directory by defining the :term:`DL_DIR` variable in the |
1974 | ``conf/local.conf`` file. This directory is self-maintaining and you | 2273 | ``conf/local.conf`` file. This directory is self-maintaining and you |
1975 | should not have to touch it. By default, the directory is | 2274 | should not have to touch it. By default, the directory is |
1976 | ``downloads`` in the :term:`Build Directory`. | 2275 | ``downloads`` in the :term:`Build Directory`:: |
1977 | :: | ||
1978 | 2276 | ||
1979 | #DL_DIR ?= "${TOPDIR}/downloads" | 2277 | #DL_DIR ?= "${TOPDIR}/downloads" |
1980 | 2278 | ||
@@ -1984,7 +2282,7 @@ system and gives an overview of their function and contents. | |||
1984 | During a first build, the system downloads many different source code | 2282 | During a first build, the system downloads many different source code |
1985 | tarballs from various upstream projects. Downloading can take a | 2283 | tarballs from various upstream projects. Downloading can take a |
1986 | while, particularly if your network connection is slow. Tarballs are | 2284 | while, particularly if your network connection is slow. Tarballs are |
1987 | all stored in the directory defined by ``DL_DIR`` and the build | 2285 | all stored in the directory defined by :term:`DL_DIR` and the build |
1988 | system looks there first to find source tarballs. | 2286 | system looks there first to find source tarballs. |
1989 | 2287 | ||
1990 | .. note:: | 2288 | .. note:: |
@@ -2001,24 +2299,51 @@ system and gives an overview of their function and contents. | |||
2001 | Wiki page. | 2299 | Wiki page. |
2002 | 2300 | ||
2003 | :term:`DOC_COMPRESS` | 2301 | :term:`DOC_COMPRESS` |
2004 | When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` | 2302 | When inheriting the :ref:`ref-classes-compress_doc` |
2005 | class, this variable sets the compression policy used when the | 2303 | class, this variable sets the compression policy used when the |
2006 | OpenEmbedded build system compresses man pages and info pages. By | 2304 | OpenEmbedded build system compresses manual and info pages. By |
2007 | default, the compression method used is gz (gzip). Other policies | 2305 | default, the compression method used is gz (gzip). Other policies |
2008 | available are xz and bz2. | 2306 | available are xz and bz2. |
2009 | 2307 | ||
2010 | For information on policies and on how to use this variable, see the | 2308 | For information on policies and on how to use this variable, see the |
2011 | comments in the ``meta/classes/compress_doc.bbclass`` file. | 2309 | comments in the ``meta/classes-recipe/compress_doc.bbclass`` file. |
2310 | |||
2311 | :term:`DT_FILES` | ||
2312 | Space-separated list of device tree source files to compile using | ||
2313 | a recipe that inherits the :ref:`ref-classes-devicetree` class. These | ||
2314 | are relative to the :term:`DT_FILES_PATH`. | ||
2315 | |||
2316 | For convenience, both ``.dts`` and ``.dtb`` extensions can be used. | ||
2317 | |||
2318 | Use an empty string (default) to build all device tree sources within | ||
2319 | the :term:`DT_FILES_PATH` directory. | ||
2320 | |||
2321 | :term:`DT_FILES_PATH` | ||
2322 | When compiling out-of-tree device tree sources using a recipe that | ||
2323 | inherits the :ref:`ref-classes-devicetree` class, this variable specifies | ||
2324 | the path to the directory containing dts files to build. | ||
2325 | |||
2326 | Defaults to the :term:`S` directory. | ||
2327 | |||
2328 | :term:`DT_PADDING_SIZE` | ||
2329 | When inheriting the :ref:`ref-classes-devicetree` class, this variable | ||
2330 | specifies the size of padding appended to the device tree blob, used as | ||
2331 | extra space typically for additional properties during boot. | ||
2012 | 2332 | ||
2013 | :term:`EFI_PROVIDER` | 2333 | :term:`EFI_PROVIDER` |
2014 | When building bootable images (i.e. where ``hddimg``, ``iso``, or | 2334 | When building bootable images (i.e. where ``hddimg``, ``iso``, or |
2015 | ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the | 2335 | ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the |
2016 | ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The | 2336 | :term:`EFI_PROVIDER` variable specifies the EFI bootloader to use. The |
2017 | default is "grub-efi", but "systemd-boot" can be used instead. | 2337 | default is "grub-efi", but "systemd-boot" can be used instead. |
2018 | 2338 | ||
2019 | See the :ref:`systemd-boot <ref-classes-systemd-boot>` and | 2339 | See the :ref:`ref-classes-systemd-boot` and :ref:`ref-classes-image-live` |
2020 | :ref:`image-live <ref-classes-image-live>` classes for more | 2340 | classes for more information. |
2021 | information. | 2341 | |
2342 | :term:`EFI_UKI_DIR` | ||
2343 | The primary place for the UKI image inside the EFI System Partition. | ||
2344 | |||
2345 | :term:`EFI_UKI_PATH` | ||
2346 | The path for the UKI image inside the root filesystem. | ||
2022 | 2347 | ||
2023 | :term:`ENABLE_BINARY_LOCALE_GENERATION` | 2348 | :term:`ENABLE_BINARY_LOCALE_GENERATION` |
2024 | Variable that controls which locales for ``glibc`` are generated | 2349 | Variable that controls which locales for ``glibc`` are generated |
@@ -2026,18 +2351,16 @@ system and gives an overview of their function and contents. | |||
2026 | less). | 2351 | less). |
2027 | 2352 | ||
2028 | :term:`ERR_REPORT_DIR` | 2353 | :term:`ERR_REPORT_DIR` |
2029 | When used with the :ref:`report-error <ref-classes-report-error>` | 2354 | When used with the :ref:`ref-classes-report-error` class, specifies the |
2030 | class, specifies the path used for storing the debug files created by | 2355 | path used for storing the debug files created by the :ref:`error reporting |
2031 | the :ref:`error reporting | 2356 | tool <dev-manual/error-reporting-tool:using the error reporting tool>`, |
2032 | tool <dev-manual/common-tasks:using the error reporting tool>`, which | 2357 | which allows you to submit build errors you encounter to a central |
2033 | allows you to submit build errors you encounter to a central | ||
2034 | database. By default, the value of this variable is | 2358 | database. By default, the value of this variable is |
2035 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. | 2359 | ``${``\ :term:`LOG_DIR`\ ``}/error-report``. |
2036 | 2360 | ||
2037 | You can set ``ERR_REPORT_DIR`` to the path you want the error | 2361 | You can set :term:`ERR_REPORT_DIR` to the path you want the error |
2038 | reporting tool to store the debug files as follows in your | 2362 | reporting tool to store the debug files as follows in your |
2039 | ``local.conf`` file: | 2363 | ``local.conf`` file:: |
2040 | :: | ||
2041 | 2364 | ||
2042 | ERR_REPORT_DIR = "path" | 2365 | ERR_REPORT_DIR = "path" |
2043 | 2366 | ||
@@ -2046,7 +2369,69 @@ system and gives an overview of their function and contents. | |||
2046 | errors by the OpenEmbedded build system. You set this variable in | 2369 | errors by the OpenEmbedded build system. You set this variable in |
2047 | your distribution configuration file. For a list of the checks you | 2370 | your distribution configuration file. For a list of the checks you |
2048 | can control with this variable, see the | 2371 | can control with this variable, see the |
2049 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | 2372 | ":ref:`ref-classes-insane`" section. |
2373 | |||
2374 | :term:`ESDK_CLASS_INHERIT_DISABLE` | ||
2375 | A list of classes to remove from the :term:`INHERIT` | ||
2376 | value globally within the extensible SDK configuration. The | ||
2377 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the | ||
2378 | default value:: | ||
2379 | |||
2380 | ESDK_CLASS_INHERIT_DISABLE ?= "buildhistory icecc" | ||
2381 | |||
2382 | Some classes are not generally applicable within the extensible SDK | ||
2383 | context. You can use this variable to disable those classes. | ||
2384 | |||
2385 | For additional information on how to customize the extensible SDK's | ||
2386 | configuration, see the | ||
2387 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
2388 | section in the Yocto Project Application Development and the | ||
2389 | Extensible Software Development Kit (eSDK) manual. | ||
2390 | |||
2391 | :term:`ESDK_LOCALCONF_ALLOW` | ||
2392 | A list of variables allowed through from the OpenEmbedded build | ||
2393 | system configuration into the extensible SDK configuration. By | ||
2394 | default, the list of variables is empty and is set in the | ||
2395 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. | ||
2396 | |||
2397 | This list overrides the variables specified using the | ||
2398 | :term:`ESDK_LOCALCONF_REMOVE` variable as well as | ||
2399 | other variables automatically added due to the "/" character | ||
2400 | being found at the start of the | ||
2401 | value, which is usually indicative of being a path and thus might not | ||
2402 | be valid on the system where the SDK is installed. | ||
2403 | |||
2404 | For additional information on how to customize the extensible SDK's | ||
2405 | configuration, see the | ||
2406 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
2407 | section in the Yocto Project Application Development and the | ||
2408 | Extensible Software Development Kit (eSDK) manual. | ||
2409 | |||
2410 | :term:`ESDK_LOCALCONF_REMOVE` | ||
2411 | A list of variables not allowed through from the OpenEmbedded build | ||
2412 | system configuration into the extensible SDK configuration. Usually, | ||
2413 | these are variables that are specific to the machine on which the | ||
2414 | build system is running and thus would be potentially problematic | ||
2415 | within the extensible SDK. | ||
2416 | |||
2417 | By default, :term:`ESDK_LOCALCONF_REMOVE` is set in the | ||
2418 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and | ||
2419 | excludes the following variables: | ||
2420 | |||
2421 | - :term:`CONF_VERSION` | ||
2422 | - :term:`BB_NUMBER_THREADS` | ||
2423 | - :term:`BB_NUMBER_PARSE_THREADS` | ||
2424 | - :term:`PARALLEL_MAKE` | ||
2425 | - :term:`PRSERV_HOST` | ||
2426 | - :term:`SSTATE_MIRRORS` :term:`DL_DIR` | ||
2427 | - :term:`SSTATE_DIR` :term:`TMPDIR` | ||
2428 | - :term:`BB_SERVER_TIMEOUT` | ||
2429 | |||
2430 | For additional information on how to customize the extensible SDK's | ||
2431 | configuration, see the | ||
2432 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
2433 | section in the Yocto Project Application Development and the | ||
2434 | Extensible Software Development Kit (eSDK) manual. | ||
2050 | 2435 | ||
2051 | :term:`EXCLUDE_FROM_SHLIBS` | 2436 | :term:`EXCLUDE_FROM_SHLIBS` |
2052 | Triggers the OpenEmbedded build system's shared libraries resolver to | 2437 | Triggers the OpenEmbedded build system's shared libraries resolver to |
@@ -2060,13 +2445,12 @@ system and gives an overview of their function and contents. | |||
2060 | libraries resolver might implicitly define some dependencies between | 2445 | libraries resolver might implicitly define some dependencies between |
2061 | packages. | 2446 | packages. |
2062 | 2447 | ||
2063 | The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the | 2448 | The :term:`EXCLUDE_FROM_SHLIBS` variable is similar to the |
2064 | :term:`PRIVATE_LIBS` variable, which excludes a | 2449 | :term:`PRIVATE_LIBS` variable, which excludes a |
2065 | package's particular libraries only and not the whole package. | 2450 | package's particular libraries only and not the whole package. |
2066 | 2451 | ||
2067 | Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a | 2452 | Use the :term:`EXCLUDE_FROM_SHLIBS` variable by setting it to "1" for a |
2068 | particular package: | 2453 | particular package:: |
2069 | :: | ||
2070 | 2454 | ||
2071 | EXCLUDE_FROM_SHLIBS = "1" | 2455 | EXCLUDE_FROM_SHLIBS = "1" |
2072 | 2456 | ||
@@ -2081,18 +2465,18 @@ system and gives an overview of their function and contents. | |||
2081 | 2465 | ||
2082 | .. note:: | 2466 | .. note:: |
2083 | 2467 | ||
2084 | Recipes added to ``EXCLUDE_FROM_WORLD`` may still be built during a | 2468 | Recipes added to :term:`EXCLUDE_FROM_WORLD` may still be built during a |
2085 | world build in order to satisfy dependencies of other recipes. Adding | 2469 | 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 | 2470 | a recipe to :term:`EXCLUDE_FROM_WORLD` only ensures that the recipe is not |
2087 | explicitly added to the list of build targets in a world build. | 2471 | explicitly added to the list of build targets in a world build. |
2088 | 2472 | ||
2089 | :term:`EXTENDPE` | 2473 | :term:`EXTENDPE` |
2090 | Used with file and pathnames to create a prefix for a recipe's | 2474 | 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`` | 2475 | version based on the recipe's :term:`PE` value. If :term:`PE` |
2092 | is set and greater than zero for a recipe, ``EXTENDPE`` becomes that | 2476 | is set and greater than zero for a recipe, :term:`EXTENDPE` becomes that |
2093 | value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1"). | 2477 | value (e.g if :term:`PE` is equal to "1" then :term:`EXTENDPE` becomes "1"). |
2094 | If a recipe's ``PE`` is not set (the default) or is equal to zero, | 2478 | If a recipe's :term:`PE` is not set (the default) or is equal to zero, |
2095 | ``EXTENDPE`` becomes "". | 2479 | :term:`EXTENDPE` becomes "". |
2096 | 2480 | ||
2097 | See the :term:`STAMP` variable for an example. | 2481 | See the :term:`STAMP` variable for an example. |
2098 | 2482 | ||
@@ -2100,55 +2484,67 @@ system and gives an overview of their function and contents. | |||
2100 | The full package version specification as it appears on the final | 2484 | The full package version specification as it appears on the final |
2101 | packages produced by a recipe. The variable's value is normally used | 2485 | 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 | 2486 | to fix a runtime dependency to the exact same version of another |
2103 | package in the same recipe: | 2487 | package in the same recipe:: |
2104 | :: | ||
2105 | 2488 | ||
2106 | RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" | 2489 | RDEPENDS:${PN}-additional-module = "${PN} (= ${EXTENDPKGV})" |
2107 | 2490 | ||
2108 | The dependency relationships are intended to force the package | 2491 | The dependency relationships are intended to force the package |
2109 | manager to upgrade these types of packages in lock-step. | 2492 | manager to upgrade these types of packages in lock-step. |
2110 | 2493 | ||
2111 | :term:`EXTERNAL_KERNEL_TOOLS` | 2494 | :term:`EXTERNAL_KERNEL_TOOLS` |
2112 | When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these | 2495 | When set, the :term:`EXTERNAL_KERNEL_TOOLS` variable indicates that these |
2113 | tools are not in the source tree. | 2496 | tools are not in the source tree. |
2114 | 2497 | ||
2115 | When kernel tools are available in the tree, they are preferred over | 2498 | When kernel tools are available in the tree, they are preferred over |
2116 | any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` | 2499 | any externally installed tools. Setting the :term:`EXTERNAL_KERNEL_TOOLS` |
2117 | variable tells the OpenEmbedded build system to prefer the installed | 2500 | variable tells the OpenEmbedded build system to prefer the installed |
2118 | external tools. See the | 2501 | external tools. See the :ref:`ref-classes-kernel-yocto` class in |
2119 | :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in | 2502 | ``meta/classes-recipe`` to see how the variable is used. |
2120 | ``meta/classes`` to see how the variable is used. | 2503 | |
2504 | :term:`KERNEL_LOCALVERSION` | ||
2505 | This variable allows to append a string to the version | ||
2506 | of the kernel image. This corresponds to the ``CONFIG_LOCALVERSION`` | ||
2507 | kernel configuration parameter. | ||
2508 | |||
2509 | Using this variable is only useful when you are using a kernel recipe | ||
2510 | inheriting the :ref:`ref-classes-kernel` class, and which doesn't | ||
2511 | already set a local version. Therefore, setting this variable has no | ||
2512 | impact on ``linux-yocto`` kernels. | ||
2513 | |||
2514 | :term:`EXTERNAL_TOOLCHAIN` | ||
2515 | When you intend to use an | ||
2516 | :ref:`external toolchain <dev-manual/external-toolchain:optionally using an external toolchain>`, | ||
2517 | this variable allows to specify the directory where this toolchain was | ||
2518 | installed. | ||
2121 | 2519 | ||
2122 | :term:`EXTERNALSRC` | 2520 | :term:`EXTERNALSRC` |
2123 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | 2521 | When inheriting the :ref:`ref-classes-externalsrc` |
2124 | class, this variable points to the source tree, which is outside of | 2522 | class, this variable points to the source tree, which is outside of |
2125 | the OpenEmbedded build system. When set, this variable sets the | 2523 | the OpenEmbedded build system. When set, this variable sets the |
2126 | :term:`S` variable, which is what the OpenEmbedded build | 2524 | :term:`S` variable, which is what the OpenEmbedded build |
2127 | system uses to locate unpacked recipe source code. | 2525 | system uses to locate unpacked recipe source code. |
2128 | 2526 | ||
2129 | For more information on ``externalsrc.bbclass``, see the | 2527 | See the ":ref:`ref-classes-externalsrc`" section for details. You |
2130 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2131 | can also find information on how to use this variable in the | 2528 | can also find information on how to use this variable in the |
2132 | ":ref:`dev-manual/common-tasks:building software from an external source`" | 2529 | ":ref:`dev-manual/building:building software from an external source`" |
2133 | section in the Yocto Project Development Tasks Manual. | 2530 | section in the Yocto Project Development Tasks Manual. |
2134 | 2531 | ||
2135 | :term:`EXTERNALSRC_BUILD` | 2532 | :term:`EXTERNALSRC_BUILD` |
2136 | When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` | 2533 | When inheriting the :ref:`ref-classes-externalsrc` |
2137 | class, this variable points to the directory in which the recipe's | 2534 | class, this variable points to the directory in which the recipe's |
2138 | source code is built, which is outside of the OpenEmbedded build | 2535 | source code is built, which is outside of the OpenEmbedded build |
2139 | system. When set, this variable sets the :term:`B` variable, | 2536 | system. When set, this variable sets the :term:`B` variable, |
2140 | which is what the OpenEmbedded build system uses to locate the Build | 2537 | which is what the OpenEmbedded build system uses to locate the |
2141 | Directory. | 2538 | :term:`Build Directory`. |
2142 | 2539 | ||
2143 | For more information on ``externalsrc.bbclass``, see the | 2540 | See the ":ref:`ref-classes-externalsrc`" section for details. You |
2144 | ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You | ||
2145 | can also find information on how to use this variable in the | 2541 | can also find information on how to use this variable in the |
2146 | ":ref:`dev-manual/common-tasks:building software from an external source`" | 2542 | ":ref:`dev-manual/building:building software from an external source`" |
2147 | section in the Yocto Project Development Tasks Manual. | 2543 | section in the Yocto Project Development Tasks Manual. |
2148 | 2544 | ||
2149 | :term:`EXTRA_AUTORECONF` | 2545 | :term:`EXTRA_AUTORECONF` |
2150 | For recipes inheriting the :ref:`autotools <ref-classes-autotools>` | 2546 | For recipes inheriting the :ref:`ref-classes-autotools` |
2151 | class, you can use ``EXTRA_AUTORECONF`` to specify extra options to | 2547 | class, you can use :term:`EXTRA_AUTORECONF` to specify extra options to |
2152 | pass to the ``autoreconf`` command that is executed during the | 2548 | pass to the ``autoreconf`` command that is executed during the |
2153 | :ref:`ref-tasks-configure` task. | 2549 | :ref:`ref-tasks-configure` task. |
2154 | 2550 | ||
@@ -2159,9 +2555,8 @@ system and gives an overview of their function and contents. | |||
2159 | more than one feature, separate them with a space. | 2555 | more than one feature, separate them with a space. |
2160 | 2556 | ||
2161 | Typically, you configure this variable in your ``local.conf`` file, | 2557 | Typically, you configure this variable in your ``local.conf`` file, |
2162 | which is found in the :term:`Build Directory`. | 2558 | which is found in the :term:`Build Directory`. Although you can use this |
2163 | Although you can use this variable from within a recipe, best | 2559 | variable from within a recipe, best practices dictate that you do not. |
2164 | practices dictate that you do not. | ||
2165 | 2560 | ||
2166 | .. note:: | 2561 | .. note:: |
2167 | 2562 | ||
@@ -2170,70 +2565,58 @@ system and gives an overview of their function and contents. | |||
2170 | 2565 | ||
2171 | Here are some examples of features you can add: | 2566 | Here are some examples of features you can add: |
2172 | 2567 | ||
2173 | - "dbg-pkgs" - Adds -dbg packages for all installed packages including | 2568 | - "dbg-pkgs" --- adds -dbg packages for all installed packages including |
2174 | symbol information for debugging and profiling. | 2569 | symbol information for debugging and profiling. |
2175 | 2570 | ||
2176 | - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and | 2571 | - "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 | 2572 | enables post-installation logging. See the 'allow-empty-password' and |
2178 | 'post-install-logging' features in the ":ref:`ref-features-image`" | 2573 | 'post-install-logging' features in the ":ref:`ref-features-image`" |
2179 | section for more information. | 2574 | section for more information. |
2180 | - "dev-pkgs" - Adds -dev packages for all installed packages. This is | 2575 | - "dev-pkgs" --- adds -dev packages for all installed packages. This is |
2181 | useful if you want to develop against the libraries in the image. | 2576 | useful if you want to develop against the libraries in the image. |
2182 | - "read-only-rootfs" - Creates an image whose root filesystem is | 2577 | - "read-only-rootfs" --- creates an image whose root filesystem is |
2183 | read-only. See the | 2578 | read-only. See the |
2184 | ":ref:`dev-manual/common-tasks:creating a read-only root filesystem`" | 2579 | ":ref:`dev-manual/read-only-rootfs:creating a read-only root filesystem`" |
2185 | section in the Yocto Project Development Tasks Manual for more | 2580 | section in the Yocto Project Development Tasks Manual for more |
2186 | information | 2581 | information |
2187 | - "tools-debug" - Adds debugging tools such as gdb and strace. | 2582 | - "tools-debug" --- adds debugging tools such as gdb and strace. |
2188 | - "tools-sdk" - Adds development tools such as gcc, make, | 2583 | - "tools-sdk" --- adds development tools such as gcc, make, |
2189 | pkgconfig and so forth. | 2584 | pkgconfig and so forth. |
2190 | - "tools-testapps" - Adds useful testing tools | 2585 | - "tools-testapps" --- adds useful testing tools |
2191 | such as ts_print, aplay, arecord and so forth. | 2586 | such as ts_print, aplay, arecord and so forth. |
2192 | 2587 | ||
2193 | For a complete list of image features that ships with the Yocto | 2588 | For a complete list of image features that ships with the Yocto |
2194 | Project, see the ":ref:`ref-features-image`" section. | 2589 | Project, see the ":ref:`ref-features-image`" section. |
2195 | 2590 | ||
2196 | For an example that shows how to customize your image by using this | 2591 | 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\`\``" | 2592 | variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" |
2198 | section in the Yocto Project Development Tasks Manual. | 2593 | section in the Yocto Project Development Tasks Manual. |
2199 | 2594 | ||
2200 | :term:`EXTRA_IMAGECMD` | 2595 | :term:`EXTRA_IMAGECMD` |
2201 | Specifies additional options for the image creation command that has | 2596 | Specifies additional options for the image creation command that has |
2202 | been specified in :term:`IMAGE_CMD`. When setting | 2597 | been specified in :term:`IMAGE_CMD`. When setting |
2203 | this variable, use an override for the associated image type. Here is | 2598 | this variable, use an override for the associated image type. Here is |
2204 | an example: | 2599 | an example:: |
2205 | :: | ||
2206 | 2600 | ||
2207 | EXTRA_IMAGECMD_ext3 ?= "-i 4096" | 2601 | EXTRA_IMAGECMD:ext3 ?= "-i 4096" |
2208 | 2602 | ||
2209 | :term:`EXTRA_IMAGEDEPENDS` | 2603 | :term:`EXTRA_IMAGEDEPENDS` |
2210 | A list of recipes to build that do not provide packages for | 2604 | A list of recipes to build that do not provide packages for |
2211 | installing into the root filesystem. | 2605 | installing into the root filesystem. |
2212 | 2606 | ||
2213 | Sometimes a recipe is required to build the final image but is not | 2607 | 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`` | 2608 | needed in the root filesystem. You can use the :term:`EXTRA_IMAGEDEPENDS` |
2215 | variable to list these recipes and thus specify the dependencies. A | 2609 | variable to list these recipes and thus specify the dependencies. A |
2216 | typical example is a required bootloader in a machine configuration. | 2610 | typical example is a required bootloader in a machine configuration. |
2217 | 2611 | ||
2218 | .. note:: | 2612 | .. note:: |
2219 | 2613 | ||
2220 | To add packages to the root filesystem, see the various | 2614 | To add packages to the root filesystem, see the various |
2221 | \*:term:`RDEPENDS` and \*:term:`RRECOMMENDS` variables. | 2615 | :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 | 2616 | ||
2234 | :term:`EXTRA_OECMAKE` | 2617 | :term:`EXTRA_OECMAKE` |
2235 | Additional `CMake <https://cmake.org/overview/>`__ options. See the | 2618 | Additional `CMake <https://cmake.org/overview/>`__ options. See the |
2236 | :ref:`cmake <ref-classes-cmake>` class for additional information. | 2619 | :ref:`ref-classes-cmake` class for additional information. |
2237 | 2620 | ||
2238 | :term:`EXTRA_OECONF` | 2621 | :term:`EXTRA_OECONF` |
2239 | Additional ``configure`` script options. See | 2622 | Additional ``configure`` script options. See |
@@ -2243,30 +2626,44 @@ system and gives an overview of their function and contents. | |||
2243 | :term:`EXTRA_OEMAKE` | 2626 | :term:`EXTRA_OEMAKE` |
2244 | Additional GNU ``make`` options. | 2627 | Additional GNU ``make`` options. |
2245 | 2628 | ||
2246 | Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the | 2629 | Because the :term:`EXTRA_OEMAKE` defaults to "", you need to set the |
2247 | variable to specify any required GNU options. | 2630 | variable to specify any required GNU options. |
2248 | 2631 | ||
2249 | :term:`PARALLEL_MAKE` and | 2632 | :term:`PARALLEL_MAKE` and |
2250 | :term:`PARALLEL_MAKEINST` also make use of | 2633 | :term:`PARALLEL_MAKEINST` also make use of |
2251 | ``EXTRA_OEMAKE`` to pass the required flags. | 2634 | :term:`EXTRA_OEMAKE` to pass the required flags. |
2252 | 2635 | ||
2253 | :term:`EXTRA_OESCONS` | 2636 | :term:`EXTRA_OESCONS` |
2254 | When inheriting the :ref:`scons <ref-classes-scons>` class, this | 2637 | When inheriting the :ref:`ref-classes-scons` class, this |
2255 | variable specifies additional configuration options you want to pass | 2638 | variable specifies additional configuration options you want to pass |
2256 | to the ``scons`` command line. | 2639 | to the ``scons`` command line. |
2257 | 2640 | ||
2641 | :term:`EXTRA_OEMESON` | ||
2642 | Additional `Meson <https://mesonbuild.com/>`__ options. See the | ||
2643 | :ref:`ref-classes-meson` class for additional information. | ||
2644 | |||
2645 | In addition to standard Meson options, such options correspond to | ||
2646 | `Meson build options <https://mesonbuild.com/Build-options.html>`__ | ||
2647 | defined in the ``meson_options.txt`` file in the sources to build. | ||
2648 | Here is an example:: | ||
2649 | |||
2650 | EXTRA_OEMESON = "-Dpython=disabled -Dvalgrind=disabled" | ||
2651 | |||
2652 | Note that any custom value for the Meson ``--buildtype`` option | ||
2653 | should be set through the :term:`MESON_BUILDTYPE` variable. | ||
2654 | |||
2258 | :term:`EXTRA_USERS_PARAMS` | 2655 | :term:`EXTRA_USERS_PARAMS` |
2259 | When inheriting the :ref:`extrausers <ref-classes-extrausers>` | 2656 | When inheriting the :ref:`ref-classes-extrausers` |
2260 | class, this variable provides image level user and group operations. | 2657 | class, this variable provides image level user and group operations. |
2261 | This is a more global method of providing user and group | 2658 | This is a more global method of providing user and group |
2262 | configuration as compared to using the | 2659 | configuration as compared to using the |
2263 | :ref:`useradd <ref-classes-useradd>` class, which ties user and | 2660 | :ref:`ref-classes-useradd` class, which ties user and |
2264 | group configurations to a specific recipe. | 2661 | group configurations to a specific recipe. |
2265 | 2662 | ||
2266 | The set list of commands you can configure using the | 2663 | The set list of commands you can configure using the |
2267 | ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These | 2664 | :term:`EXTRA_USERS_PARAMS` is shown in the |
2268 | commands map to the normal Unix commands of the same names: | 2665 | :ref:`ref-classes-extrausers` class. These commands map to the normal |
2269 | :: | 2666 | Unix commands of the same names:: |
2270 | 2667 | ||
2271 | # EXTRA_USERS_PARAMS = "\ | 2668 | # EXTRA_USERS_PARAMS = "\ |
2272 | # useradd -p '' tester; \ | 2669 | # useradd -p '' tester; \ |
@@ -2277,23 +2674,92 @@ system and gives an overview of their function and contents. | |||
2277 | # usermod -s /bin/sh tester; \ | 2674 | # usermod -s /bin/sh tester; \ |
2278 | # " | 2675 | # " |
2279 | 2676 | ||
2677 | Hardcoded passwords are supported via the ``-p`` parameters for | ||
2678 | ``useradd`` or ``usermod``, but only hashed. | ||
2679 | |||
2680 | Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns | ||
2681 | passwords. First on host, create the (escaped) password hash:: | ||
2682 | |||
2683 | printf "%q" $(mkpasswd -m sha256crypt tester01) | ||
2684 | |||
2685 | The resulting hash is set to a variable and used in ``useradd`` command parameters:: | ||
2686 | |||
2687 | inherit extrausers | ||
2688 | PASSWD = "\$X\$ABC123\$A-Long-Hash" | ||
2689 | EXTRA_USERS_PARAMS = "\ | ||
2690 | useradd -p '${PASSWD}' tester-jim; \ | ||
2691 | useradd -p '${PASSWD}' tester-sue; \ | ||
2692 | " | ||
2693 | |||
2694 | Finally, here is an example that sets the root password:: | ||
2695 | |||
2696 | inherit extrausers | ||
2697 | EXTRA_USERS_PARAMS = "\ | ||
2698 | usermod -p '${PASSWD}' root; \ | ||
2699 | " | ||
2700 | |||
2701 | .. note:: | ||
2702 | |||
2703 | From a security perspective, hardcoding a default password is not | ||
2704 | generally a good idea or even legal in some jurisdictions. It is | ||
2705 | recommended that you do not do this if you are building a production | ||
2706 | image. | ||
2707 | |||
2708 | Additionally there is a special ``passwd-expire`` command that will | ||
2709 | cause the password for a user to be expired and thus force changing it | ||
2710 | on first login, for example:: | ||
2711 | |||
2712 | EXTRA_USERS_PARAMS += " useradd myuser; passwd-expire myuser;" | ||
2713 | |||
2714 | .. note:: | ||
2715 | |||
2716 | At present, ``passwd-expire`` may only work for remote logins when | ||
2717 | using OpenSSH and not dropbear as an SSH server. | ||
2718 | |||
2719 | :term:`EXTRANATIVEPATH` | ||
2720 | A list of subdirectories of | ||
2721 | ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` | ||
2722 | added to the beginning of the environment variable ``PATH``. As an | ||
2723 | example, the following prepends | ||
2724 | "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to | ||
2725 | ``PATH``:: | ||
2726 | |||
2727 | EXTRANATIVEPATH = "foo bar" | ||
2728 | |||
2729 | :term:`FAKEROOT` | ||
2730 | See :term:`bitbake:FAKEROOT` in the BitBake manual. | ||
2731 | |||
2732 | :term:`FAKEROOTBASEENV` | ||
2733 | See :term:`bitbake:FAKEROOTBASEENV` in the BitBake manual. | ||
2734 | |||
2735 | :term:`FAKEROOTCMD` | ||
2736 | See :term:`bitbake:FAKEROOTCMD` in the BitBake manual. | ||
2737 | |||
2738 | :term:`FAKEROOTDIRS` | ||
2739 | See :term:`bitbake:FAKEROOTDIRS` in the BitBake manual. | ||
2740 | |||
2741 | :term:`FAKEROOTENV` | ||
2742 | See :term:`bitbake:FAKEROOTENV` in the BitBake manual. | ||
2743 | |||
2744 | :term:`FAKEROOTNOENV` | ||
2745 | See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual. | ||
2746 | |||
2280 | :term:`FEATURE_PACKAGES` | 2747 | :term:`FEATURE_PACKAGES` |
2281 | Defines one or more packages to include in an image when a specific | 2748 | Defines one or more packages to include in an image when a specific |
2282 | item is included in :term:`IMAGE_FEATURES`. | 2749 | item is included in :term:`IMAGE_FEATURES`. |
2283 | When setting the value, ``FEATURE_PACKAGES`` should have the name of | 2750 | When setting the value, :term:`FEATURE_PACKAGES` should have the name of |
2284 | the feature item as an override. Here is an example: | 2751 | the feature item as an override. Here is an example:: |
2285 | :: | ||
2286 | 2752 | ||
2287 | FEATURE_PACKAGES_widget = "package1 package2" | 2753 | FEATURE_PACKAGES_widget = "package1 package2" |
2288 | 2754 | ||
2289 | In this example, if "widget" were added to ``IMAGE_FEATURES``, | 2755 | In this example, if "widget" were added to :term:`IMAGE_FEATURES`, |
2290 | package1 and package2 would be included in the image. | 2756 | package1 and package2 would be included in the image. |
2291 | 2757 | ||
2292 | .. note:: | 2758 | .. note:: |
2293 | 2759 | ||
2294 | Packages installed by features defined through ``FEATURE_PACKAGES`` | 2760 | Packages installed by features defined through :term:`FEATURE_PACKAGES` |
2295 | are often package groups. While similarly named, you should not | 2761 | are often package groups. While similarly named, you should not |
2296 | confuse the ``FEATURE_PACKAGES`` variable with package groups, which | 2762 | confuse the :term:`FEATURE_PACKAGES` variable with package groups, which |
2297 | are discussed elsewhere in the documentation. | 2763 | are discussed elsewhere in the documentation. |
2298 | 2764 | ||
2299 | :term:`FEED_DEPLOYDIR_BASE_URI` | 2765 | :term:`FEED_DEPLOYDIR_BASE_URI` |
@@ -2302,8 +2768,7 @@ system and gives an overview of their function and contents. | |||
2302 | OPKG to support runtime package management of IPK packages. You set | 2768 | OPKG to support runtime package management of IPK packages. You set |
2303 | this variable in your ``local.conf`` file. | 2769 | this variable in your ``local.conf`` file. |
2304 | 2770 | ||
2305 | Consider the following example: | 2771 | Consider the following example:: |
2306 | :: | ||
2307 | 2772 | ||
2308 | FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" | 2773 | FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir" |
2309 | 2774 | ||
@@ -2314,37 +2779,42 @@ system and gives an overview of their function and contents. | |||
2314 | a set of configuration files for you in your target that work with | 2779 | a set of configuration files for you in your target that work with |
2315 | the feed. | 2780 | the feed. |
2316 | 2781 | ||
2782 | :term:`FETCHCMD` | ||
2783 | See :term:`bitbake:FETCHCMD` in the BitBake manual. | ||
2784 | |||
2785 | :term:`FILE` | ||
2786 | See :term:`bitbake:FILE` in the BitBake manual. | ||
2787 | |||
2317 | :term:`FILES` | 2788 | :term:`FILES` |
2318 | The list of files and directories that are placed in a package. The | 2789 | The list of files and directories that are placed in a package. The |
2319 | :term:`PACKAGES` variable lists the packages | 2790 | :term:`PACKAGES` variable lists the packages |
2320 | generated by a recipe. | 2791 | generated by a recipe. |
2321 | 2792 | ||
2322 | To use the ``FILES`` variable, provide a package name override that | 2793 | To use the :term:`FILES` variable, provide a package name override that |
2323 | identifies the resulting package. Then, provide a space-separated | 2794 | identifies the resulting package. Then, provide a space-separated |
2324 | list of files or paths that identify the files you want included as | 2795 | list of files or paths that identify the files you want included as |
2325 | part of the resulting package. Here is an example: | 2796 | part of the resulting package. Here is an example:: |
2326 | :: | ||
2327 | 2797 | ||
2328 | FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" | 2798 | FILES:${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile" |
2329 | 2799 | ||
2330 | .. note:: | 2800 | .. note:: |
2331 | 2801 | ||
2332 | - When specifying files or paths, you can pattern match using | 2802 | - When specifying files or paths, you can pattern match using |
2333 | Python's | 2803 | Python's |
2334 | `glob <https://docs.python.org/3/library/glob.html>`_ | 2804 | `glob <https://docs.python.org/3/library/glob.html>`__ |
2335 | syntax. For details on the syntax, see the documentation by | 2805 | syntax. For details on the syntax, see the documentation by |
2336 | following the previous link. | 2806 | following the previous link. |
2337 | 2807 | ||
2338 | - When specifying paths as part of the ``FILES`` variable, it is | 2808 | - When specifying paths as part of the :term:`FILES` variable, it is |
2339 | good practice to use appropriate path variables. For example, | 2809 | good practice to use appropriate path variables. For example, |
2340 | use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` | 2810 | use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` |
2341 | rather than ``/usr/bin``. You can find a list of these | 2811 | rather than ``/usr/bin``. You can find a list of these |
2342 | variables at the top of the ``meta/conf/bitbake.conf`` file in | 2812 | variables at the top of the ``meta/conf/bitbake.conf`` file in |
2343 | the :term:`Source Directory`. You will also | 2813 | the :term:`Source Directory`. You will also |
2344 | find the default values of the various ``FILES_*`` variables in | 2814 | find the default values of the various ``FILES:*`` variables in |
2345 | this file. | 2815 | this file. |
2346 | 2816 | ||
2347 | If some of the files you provide with the ``FILES`` variable are | 2817 | If some of the files you provide with the :term:`FILES` variable are |
2348 | editable and you know they should not be overwritten during the | 2818 | editable and you know they should not be overwritten during the |
2349 | package update process by the Package Management System (PMS), you | 2819 | package update process by the Package Management System (PMS), you |
2350 | can identify these files so that the PMS will not overwrite them. See | 2820 | can identify these files so that the PMS will not overwrite them. See |
@@ -2354,29 +2824,26 @@ system and gives an overview of their function and contents. | |||
2354 | :term:`FILES_SOLIBSDEV` | 2824 | :term:`FILES_SOLIBSDEV` |
2355 | Defines the file specification to match | 2825 | Defines the file specification to match |
2356 | :term:`SOLIBSDEV`. In other words, | 2826 | :term:`SOLIBSDEV`. In other words, |
2357 | ``FILES_SOLIBSDEV`` defines the full path name of the development | 2827 | :term:`FILES_SOLIBSDEV` defines the full path name of the development |
2358 | symbolic link (symlink) for shared libraries on the target platform. | 2828 | symbolic link (symlink) for shared libraries on the target platform. |
2359 | 2829 | ||
2360 | The following statement from the ``bitbake.conf`` shows how it is | 2830 | The following statement from the ``bitbake.conf`` shows how it is |
2361 | set: | 2831 | set:: |
2362 | :: | ||
2363 | 2832 | ||
2364 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" | 2833 | FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}" |
2365 | 2834 | ||
2366 | :term:`FILESEXTRAPATHS` | 2835 | :term:`FILESEXTRAPATHS` |
2367 | Extends the search path the OpenEmbedded build system uses when | 2836 | A colon-separated list to extend the search path the OpenEmbedded build |
2368 | looking for files and patches as it processes recipes and append | 2837 | system uses when looking for files and patches as it processes recipes |
2369 | files. The default directories BitBake uses when it processes recipes | 2838 | and append files. The default directories BitBake uses when it processes |
2370 | are initially defined by the :term:`FILESPATH` | 2839 | recipes are initially defined by the :term:`FILESPATH` variable. You can |
2371 | variable. You can extend ``FILESPATH`` variable by using | 2840 | extend :term:`FILESPATH` variable by using :term:`FILESEXTRAPATHS`. |
2372 | ``FILESEXTRAPATHS``. | ||
2373 | 2841 | ||
2374 | Best practices dictate that you accomplish this by using | 2842 | Best practices dictate that you accomplish this by using |
2375 | ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you | 2843 | :term:`FILESEXTRAPATHS` from within a ``.bbappend`` file and that you |
2376 | prepend paths as follows: | 2844 | prepend paths as follows:: |
2377 | :: | ||
2378 | 2845 | ||
2379 | FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" | 2846 | FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}:" |
2380 | 2847 | ||
2381 | In the above example, the build system first | 2848 | In the above example, the build system first |
2382 | looks for files in a directory that has the same name as the | 2849 | looks for files in a directory that has the same name as the |
@@ -2384,7 +2851,7 @@ system and gives an overview of their function and contents. | |||
2384 | 2851 | ||
2385 | .. note:: | 2852 | .. note:: |
2386 | 2853 | ||
2387 | When extending ``FILESEXTRAPATHS``, be sure to use the immediate | 2854 | When extending :term:`FILESEXTRAPATHS`, be sure to use the immediate |
2388 | expansion (``:=``) operator. Immediate expansion makes sure that | 2855 | expansion (``:=``) operator. Immediate expansion makes sure that |
2389 | BitBake evaluates :term:`THISDIR` at the time the | 2856 | BitBake evaluates :term:`THISDIR` at the time the |
2390 | directive is encountered rather than at some later time when | 2857 | directive is encountered rather than at some later time when |
@@ -2396,26 +2863,23 @@ system and gives an overview of their function and contents. | |||
2396 | are directing BitBake to extend the path by prepending directories | 2863 | are directing BitBake to extend the path by prepending directories |
2397 | to the search path. | 2864 | to the search path. |
2398 | 2865 | ||
2399 | Here is another common use: | 2866 | Here is another common use:: |
2400 | :: | ||
2401 | 2867 | ||
2402 | FILESEXTRAPATHS_prepend := "${THISDIR}/files:" | 2868 | FILESEXTRAPATHS:prepend := "${THISDIR}/files:" |
2403 | 2869 | ||
2404 | In this example, the build system extends the | 2870 | In this example, the build system extends the |
2405 | ``FILESPATH`` variable to include a directory named ``files`` that is | 2871 | :term:`FILESPATH` variable to include a directory named ``files`` that is |
2406 | in the same directory as the corresponding append file. | 2872 | in the same directory as the corresponding append file. |
2407 | 2873 | ||
2408 | This next example specifically adds three paths: | 2874 | This next example specifically adds three paths:: |
2409 | :: | ||
2410 | 2875 | ||
2411 | FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" | 2876 | FILESEXTRAPATHS:prepend := "path_1:path_2:path_3:" |
2412 | 2877 | ||
2413 | A final example shows how you can extend the search path and include | 2878 | A final example shows how you can extend the search path and include |
2414 | a :term:`MACHINE`-specific override, which is useful | 2879 | a :term:`MACHINE`-specific override, which is useful |
2415 | in a BSP layer: | 2880 | in a BSP layer:: |
2416 | :: | ||
2417 | 2881 | ||
2418 | FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:" | 2882 | FILESEXTRAPATHS:prepend:intel-x86-common := "${THISDIR}/${PN}:" |
2419 | 2883 | ||
2420 | The previous statement appears in the | 2884 | The previous statement appears in the |
2421 | ``linux-yocto-dev.bbappend`` file, which is found in the | 2885 | ``linux-yocto-dev.bbappend`` file, which is found in the |
@@ -2427,83 +2891,78 @@ system and gives an overview of their function and contents. | |||
2427 | .. note:: | 2891 | .. note:: |
2428 | 2892 | ||
2429 | For a layer that supports a single BSP, the override could just be | 2893 | For a layer that supports a single BSP, the override could just be |
2430 | the value of ``MACHINE``. | 2894 | the value of :term:`MACHINE`. |
2431 | 2895 | ||
2432 | By prepending paths in ``.bbappend`` files, you allow multiple append | 2896 | By prepending paths in ``.bbappend`` files, you allow multiple append |
2433 | files that reside in different layers but are used for the same | 2897 | files that reside in different layers but are used for the same |
2434 | recipe to correctly extend the path. | 2898 | recipe to correctly extend the path. |
2435 | 2899 | ||
2436 | :term:`FILESOVERRIDES` | 2900 | :term:`FILESOVERRIDES` |
2437 | A subset of :term:`OVERRIDES` used by the | 2901 | A colon-separated list to specify a subset of :term:`OVERRIDES` used by |
2438 | OpenEmbedded build system for creating | 2902 | the OpenEmbedded build system for creating :term:`FILESPATH`. The |
2439 | :term:`FILESPATH`. The ``FILESOVERRIDES`` variable | 2903 | :term:`FILESOVERRIDES` variable uses overrides to automatically extend |
2440 | uses overrides to automatically extend the | 2904 | the :term:`FILESPATH` variable. For an example of how that works, see the |
2441 | :term:`FILESPATH` variable. For an example of how | 2905 | :term:`FILESPATH` variable description. Additionally, you find more |
2442 | that works, see the :term:`FILESPATH` variable | 2906 | information on how overrides are handled in the |
2443 | description. Additionally, you find more information on how overrides | 2907 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (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. | 2908 | section of the BitBake User Manual. |
2447 | 2909 | ||
2448 | By default, the ``FILESOVERRIDES`` variable is defined as: | 2910 | By default, the :term:`FILESOVERRIDES` variable is defined as:: |
2449 | :: | ||
2450 | 2911 | ||
2451 | FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" | 2912 | FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" |
2452 | 2913 | ||
2453 | .. note:: | 2914 | .. note:: |
2454 | 2915 | ||
2455 | Do not hand-edit the ``FILESOVERRIDES`` variable. The values match up | 2916 | Do not hand-edit the :term:`FILESOVERRIDES` variable. The values match up |
2456 | with expected overrides and are used in an expected manner by the | 2917 | with expected overrides and are used in an expected manner by the |
2457 | build system. | 2918 | build system. |
2458 | 2919 | ||
2459 | :term:`FILESPATH` | 2920 | :term:`FILESPATH` |
2460 | The default set of directories the OpenEmbedded build system uses | 2921 | A colon-separated list specifying the default set of directories the |
2461 | when searching for patches and files. | 2922 | OpenEmbedded build system uses when searching for patches and files. |
2462 | 2923 | ||
2463 | During the build process, BitBake searches each directory in | 2924 | During the build process, BitBake searches each directory in |
2464 | ``FILESPATH`` in the specified order when looking for files and | 2925 | :term:`FILESPATH` in the specified order when looking for files and |
2465 | patches specified by each ``file://`` URI in a recipe's | 2926 | patches specified by each ``file://`` URI in a recipe's |
2466 | :term:`SRC_URI` statements. | 2927 | :term:`SRC_URI` statements. |
2467 | 2928 | ||
2468 | The default value for the ``FILESPATH`` variable is defined in the | 2929 | The default value for the :term:`FILESPATH` variable is defined in the |
2469 | ``base.bbclass`` class found in ``meta/classes`` in the | 2930 | :ref:`ref-classes-base` class found in ``meta/classes-global`` in the |
2470 | :term:`Source Directory`: | 2931 | :term:`Source Directory`:: |
2471 | :: | ||
2472 | 2932 | ||
2473 | FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ | 2933 | FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \ |
2474 | "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" | 2934 | "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" |
2475 | 2935 | ||
2476 | The | 2936 | The |
2477 | ``FILESPATH`` variable is automatically extended using the overrides | 2937 | :term:`FILESPATH` variable is automatically extended using the overrides |
2478 | from the :term:`FILESOVERRIDES` variable. | 2938 | from the :term:`FILESOVERRIDES` variable. |
2479 | 2939 | ||
2480 | .. note:: | 2940 | .. note:: |
2481 | 2941 | ||
2482 | - Do not hand-edit the ``FILESPATH`` variable. If you want the | 2942 | - Do not hand-edit the :term:`FILESPATH` variable. If you want the |
2483 | build system to look in directories other than the defaults, | 2943 | build system to look in directories other than the defaults, |
2484 | extend the ``FILESPATH`` variable by using the | 2944 | extend the :term:`FILESPATH` variable by using the |
2485 | :term:`FILESEXTRAPATHS` variable. | 2945 | :term:`FILESEXTRAPATHS` variable. |
2486 | 2946 | ||
2487 | - Be aware that the default ``FILESPATH`` directories do not map | 2947 | - Be aware that the default :term:`FILESPATH` directories do not map |
2488 | to directories in custom layers where append files | 2948 | to directories in custom layers where append files |
2489 | (``.bbappend``) are used. If you want the build system to find | 2949 | (``.bbappend``) are used. If you want the build system to find |
2490 | patches or files that reside with your append files, you need | 2950 | patches or files that reside with your append files, you need |
2491 | to extend the ``FILESPATH`` variable by using the | 2951 | to extend the :term:`FILESPATH` variable by using the |
2492 | ``FILESEXTRAPATHS`` variable. | 2952 | :term:`FILESEXTRAPATHS` variable. |
2493 | 2953 | ||
2494 | You can take advantage of this searching behavior in useful ways. For | 2954 | You can take advantage of this searching behavior in useful ways. For |
2495 | example, consider a case where the following directory structure | 2955 | example, consider a case where there is the following directory structure |
2496 | exists for general and machine-specific configurations: | 2956 | for general and machine-specific configurations:: |
2497 | :: | ||
2498 | 2957 | ||
2499 | files/defconfig | 2958 | files/defconfig |
2500 | files/MACHINEA/defconfig | 2959 | files/MACHINEA/defconfig |
2501 | files/MACHINEB/defconfig | 2960 | files/MACHINEB/defconfig |
2502 | 2961 | ||
2503 | Also in the example, the ``SRC_URI`` statement contains | 2962 | Also in the example, the :term:`SRC_URI` statement contains |
2504 | "file://defconfig". Given this scenario, you can set | 2963 | "file://defconfig". Given this scenario, you can set |
2505 | :term:`MACHINE` to "MACHINEA" and cause the build | 2964 | :term:`MACHINE` to "MACHINEA" and cause the build |
2506 | system to use files from ``files/MACHINEA``. Set ``MACHINE`` to | 2965 | system to use files from ``files/MACHINEA``. Set :term:`MACHINE` to |
2507 | "MACHINEB" and the build system uses files from ``files/MACHINEB``. | 2966 | "MACHINEB" and the build system uses files from ``files/MACHINEB``. |
2508 | Finally, for any machine other than "MACHINEA" and "MACHINEB", the | 2967 | Finally, for any machine other than "MACHINEA" and "MACHINEB", the |
2509 | build system uses files from ``files/defconfig``. | 2968 | build system uses files from ``files/defconfig``. |
@@ -2511,7 +2970,7 @@ system and gives an overview of their function and contents. | |||
2511 | You can find out more about the patching process in the | 2970 | You can find out more about the patching process in the |
2512 | ":ref:`overview-manual/concepts:patching`" section | 2971 | ":ref:`overview-manual/concepts:patching`" section |
2513 | in the Yocto Project Overview and Concepts Manual and the | 2972 | in the Yocto Project Overview and Concepts Manual and the |
2514 | ":ref:`dev-manual/common-tasks:patching code`" section in | 2973 | ":ref:`dev-manual/new-recipe:patching code`" section in |
2515 | the Yocto Project Development Tasks Manual. See the | 2974 | the Yocto Project Development Tasks Manual. See the |
2516 | :ref:`ref-tasks-patch` task as well. | 2975 | :ref:`ref-tasks-patch` task as well. |
2517 | 2976 | ||
@@ -2528,69 +2987,121 @@ system and gives an overview of their function and contents. | |||
2528 | permissions setting table, you should place it in your layer or the | 2987 | permissions setting table, you should place it in your layer or the |
2529 | distro's layer. | 2988 | distro's layer. |
2530 | 2989 | ||
2531 | You define the ``FILESYSTEM_PERMS_TABLES`` variable in the | 2990 | You define the :term:`FILESYSTEM_PERMS_TABLES` variable in the |
2532 | ``conf/local.conf`` file, which is found in the :term:`Build Directory`, | 2991 | ``conf/local.conf`` file, which is found in the :term:`Build Directory`, |
2533 | to point to your custom | 2992 | to point to your custom ``fs-perms.txt``. You can specify more than a |
2534 | ``fs-perms.txt``. You can specify more than a single file permissions | 2993 | single file permissions setting table. The paths you specify to these |
2535 | setting table. The paths you specify to these files must be defined | 2994 | files must be defined within the :term:`BBPATH` variable. |
2536 | within the :term:`BBPATH` variable. | ||
2537 | 2995 | ||
2538 | For guidance on how to create your own file permissions settings | 2996 | For guidance on how to create your own file permissions settings |
2539 | table file, examine the existing ``fs-perms.txt``. | 2997 | table file, examine the existing ``fs-perms.txt``. |
2540 | 2998 | ||
2999 | :term:`FIT_ADDRESS_CELLS` | ||
3000 | Specifies the value of the ``#address-cells`` value for the | ||
3001 | description of the FIT image. | ||
3002 | |||
3003 | The default value is set to "1" by the :ref:`ref-classes-kernel-fitimage` | ||
3004 | class, which corresponds to 32 bit addresses. | ||
3005 | |||
3006 | For platforms that need to set 64 bit addresses, for example in | ||
3007 | :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to | ||
3008 | set this value to "2", as two 32 bit values (cells) will be needed | ||
3009 | to represent such addresses. | ||
3010 | |||
3011 | Here is an example setting "0x400000000" as a load address:: | ||
3012 | |||
3013 | FIT_ADDRESS_CELLS = "2" | ||
3014 | UBOOT_LOADADDRESS= "0x04 0x00000000" | ||
3015 | |||
3016 | See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. | ||
3017 | |||
3018 | :term:`FIT_CONF_DEFAULT_DTB` | ||
3019 | Specifies the default device tree binary (dtb) file for a FIT image | ||
3020 | when multiple ones are provided. | ||
3021 | |||
3022 | This variable is used in the :ref:`ref-classes-kernel-fitimage` class. | ||
3023 | |||
2541 | :term:`FIT_DESC` | 3024 | :term:`FIT_DESC` |
2542 | Specifies the description string encoded into a fitImage. The default | 3025 | Specifies the description string encoded into a FIT image. The |
2543 | value is set by the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` | 3026 | default value is set by the :ref:`ref-classes-kernel-fitimage` class as |
2544 | class as follows:: | 3027 | follows:: |
2545 | 3028 | ||
2546 | FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" | 3029 | FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" |
2547 | 3030 | ||
2548 | :term:`FIT_GENERATE_KEYS` | 3031 | :term:`FIT_GENERATE_KEYS` |
2549 | Decides whether to generate the keys for signing fitImage if they | 3032 | Decides whether to generate the keys for signing the FIT image if |
2550 | don't already exist. The keys are created in ``UBOOT_SIGN_KEYDIR``. | 3033 | they don't already exist. The keys are created in |
2551 | The default value is 0. | 3034 | :term:`UBOOT_SIGN_KEYDIR`. The default value is set to "0" |
3035 | by the :ref:`ref-classes-kernel-fitimage` class. | ||
2552 | 3036 | ||
2553 | :term:`FIT_HASH_ALG` | 3037 | :term:`FIT_HASH_ALG` |
2554 | Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. | 3038 | Specifies the hash algorithm used in creating the FIT Image. |
3039 | This variable is set by default to "sha256" by the | ||
3040 | :ref:`ref-classes-kernel-fitimage` class. | ||
3041 | |||
3042 | :term:`FIT_KERNEL_COMP_ALG` | ||
3043 | The compression algorithm to use for the kernel image inside the FIT Image. | ||
3044 | At present, the only supported values are "gzip" (default), "lzo" or "none". | ||
3045 | If you set this variable to anything other than "none" you may also need | ||
3046 | to set :term:`FIT_KERNEL_COMP_ALG_EXTENSION`. | ||
3047 | |||
3048 | This variable is used in the :ref:`ref-classes-kernel-uboot` class. | ||
3049 | |||
3050 | :term:`FIT_KERNEL_COMP_ALG_EXTENSION` | ||
3051 | File extension corresponding to :term:`FIT_KERNEL_COMP_ALG`. The default | ||
3052 | value is set ".gz" by the :ref:`ref-classes-kernel-uboot` class. If you | ||
3053 | set :term:`FIT_KERNEL_COMP_ALG` to "lzo", you may want to set this | ||
3054 | variable to ".lzo". | ||
2555 | 3055 | ||
2556 | :term:`FIT_KEY_GENRSA_ARGS` | 3056 | :term:`FIT_KEY_GENRSA_ARGS` |
2557 | Arguments to openssl genrsa for generating RSA private key for signing | 3057 | Arguments to ``openssl genrsa`` for generating a RSA private key for |
2558 | fitImage. The default value is "-F4". i.e. the public exponent 65537 to | 3058 | signing the FIT image. The default value is set to "-F4" by the |
2559 | use. | 3059 | :ref:`ref-classes-kernel-fitimage` class. |
2560 | 3060 | ||
2561 | :term:`FIT_KEY_REQ_ARGS` | 3061 | :term:`FIT_KEY_REQ_ARGS` |
2562 | Arguments to openssl req for generating certificate for signing fitImage. | 3062 | Arguments to ``openssl req`` for generating a certificate for signing |
2563 | The default value is "-batch -new". batch for non interactive mode | 3063 | the FIT image. The default value is "-batch -new" by the |
2564 | and new for generating new keys. | 3064 | :ref:`ref-classes-kernel-fitimage` class, "batch" for |
3065 | non interactive mode and "new" for generating new keys. | ||
2565 | 3066 | ||
2566 | :term:`FIT_KEY_SIGN_PKCS` | 3067 | :term:`FIT_KEY_SIGN_PKCS` |
2567 | Format for public key ceritifcate used in signing fitImage. | 3068 | Format for the public key certificate used for signing the FIT image. |
2568 | The default value is "x509". | 3069 | The default value is set to "x509" by the |
3070 | :ref:`ref-classes-kernel-fitimage` class. | ||
2569 | 3071 | ||
2570 | :term:`FIT_SIGN_ALG` | 3072 | :term:`FIT_SIGN_ALG` |
2571 | Specifies the signature algorithm used in creating the FIT Image. | 3073 | Specifies the signature algorithm used in creating the FIT Image. |
2572 | For e.g. rsa2048. | 3074 | This variable is set by default to "rsa2048" by the |
3075 | :ref:`ref-classes-kernel-fitimage` class. | ||
2573 | 3076 | ||
2574 | :term:`FIT_SIGN_NUMBITS` | 3077 | :term:`FIT_PAD_ALG` |
2575 | Size of private key in number of bits used in fitImage. The default | 3078 | Specifies the padding algorithm used in creating the FIT Image. |
2576 | value is "2048". | 3079 | The default value is set to "pkcs-1.5" by the |
3080 | :ref:`ref-classes-kernel-fitimage` class. | ||
2577 | 3081 | ||
2578 | :term:`FIT_SIGN_INDIVIDUAL` | 3082 | :term:`FIT_SIGN_INDIVIDUAL` |
2579 | If set to "1", then the :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` | 3083 | If set to "1", then the :ref:`ref-classes-kernel-fitimage` |
2580 | class will sign the kernel, dtb and ramdisk images individually in addition | 3084 | class will sign the kernel, dtb and ramdisk images individually in addition |
2581 | to signing the fitImage itself. This could be useful if you are | 3085 | to signing the FIT image itself. This could be useful if you are |
2582 | intending to verify signatures in another context than booting via | 3086 | intending to verify signatures in another context than booting via |
2583 | U-Boot. | 3087 | U-Boot. |
2584 | 3088 | ||
3089 | This variable is set to "0" by default. | ||
3090 | |||
3091 | :term:`FIT_SIGN_NUMBITS` | ||
3092 | Size of the private key used in the FIT image, in number of bits. | ||
3093 | The default value for this variable is set to "2048" | ||
3094 | by the :ref:`ref-classes-kernel-fitimage` class. | ||
3095 | |||
2585 | :term:`FONT_EXTRA_RDEPENDS` | 3096 | :term:`FONT_EXTRA_RDEPENDS` |
2586 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | 3097 | When inheriting the :ref:`ref-classes-fontcache` class, |
2587 | this variable specifies the runtime dependencies for font packages. | 3098 | this variable specifies the runtime dependencies for font packages. |
2588 | By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". | 3099 | By default, the :term:`FONT_EXTRA_RDEPENDS` is set to "fontconfig-utils". |
2589 | 3100 | ||
2590 | :term:`FONT_PACKAGES` | 3101 | :term:`FONT_PACKAGES` |
2591 | When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, | 3102 | When inheriting the :ref:`ref-classes-fontcache` class, this variable |
2592 | this variable identifies packages containing font files that need to | 3103 | identifies packages containing font files that need to be cached by |
2593 | be cached by Fontconfig. By default, the ``fontcache`` class assumes | 3104 | Fontconfig. By default, the :ref:`ref-classes-fontcache` class assumes |
2594 | that fonts are in the recipe's main package (i.e. | 3105 | that fonts are in the recipe's main package (i.e. |
2595 | ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you | 3106 | ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you |
2596 | need are in a package other than that main package. | 3107 | need are in a package other than that main package. |
@@ -2602,7 +3113,7 @@ system and gives an overview of their function and contents. | |||
2602 | Set the variable to "1" to force the removal of these packages. | 3113 | Set the variable to "1" to force the removal of these packages. |
2603 | 3114 | ||
2604 | :term:`FULL_OPTIMIZATION` | 3115 | :term:`FULL_OPTIMIZATION` |
2605 | The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when | 3116 | The options to pass in :term:`TARGET_CFLAGS` and :term:`CFLAGS` when |
2606 | compiling an optimized system. This variable defaults to "-O2 -pipe | 3117 | compiling an optimized system. This variable defaults to "-O2 -pipe |
2607 | ${DEBUG_FLAGS}". | 3118 | ${DEBUG_FLAGS}". |
2608 | 3119 | ||
@@ -2612,16 +3123,14 @@ system and gives an overview of their function and contents. | |||
2612 | Programming (ROP) attacks much more difficult to execute. | 3123 | Programming (ROP) attacks much more difficult to execute. |
2613 | 3124 | ||
2614 | By default the ``security_flags.inc`` file enables PIE by setting the | 3125 | By default the ``security_flags.inc`` file enables PIE by setting the |
2615 | variable as follows: | 3126 | variable as follows:: |
2616 | :: | ||
2617 | 3127 | ||
2618 | GCCPIE ?= "--enable-default-pie" | 3128 | GCCPIE ?= "--enable-default-pie" |
2619 | 3129 | ||
2620 | :term:`GCCVERSION` | 3130 | :term:`GCCVERSION` |
2621 | Specifies the default version of the GNU C Compiler (GCC) used for | 3131 | Specifies the default version of the GNU C Compiler (GCC) used for |
2622 | compilation. By default, ``GCCVERSION`` is set to "8.x" in the | 3132 | compilation. By default, :term:`GCCVERSION` is set to "8.x" in the |
2623 | ``meta/conf/distro/include/tcmode-default.inc`` include file: | 3133 | ``meta/conf/distro/include/tcmode-default.inc`` include file:: |
2624 | :: | ||
2625 | 3134 | ||
2626 | GCCVERSION ?= "8.%" | 3135 | GCCVERSION ?= "8.%" |
2627 | 3136 | ||
@@ -2631,10 +3140,24 @@ system and gives an overview of their function and contents. | |||
2631 | :term:`GDB` | 3140 | :term:`GDB` |
2632 | The minimal command and arguments to run the GNU Debugger. | 3141 | The minimal command and arguments to run the GNU Debugger. |
2633 | 3142 | ||
3143 | :term:`GIR_EXTRA_LIBS_PATH` | ||
3144 | Allows to specify an extra search path for ``.so`` files | ||
3145 | in GLib related recipes using GObject introspection, | ||
3146 | and which do not compile without this setting. | ||
3147 | See the ":ref:`dev-manual/gobject-introspection:enabling gobject introspection support`" | ||
3148 | section for details. | ||
3149 | |||
2634 | :term:`GITDIR` | 3150 | :term:`GITDIR` |
2635 | The directory in which a local copy of a Git repository is stored | 3151 | The directory in which a local copy of a Git repository is stored |
2636 | when it is cloned. | 3152 | when it is cloned. |
2637 | 3153 | ||
3154 | :term:`GITHUB_BASE_URI` | ||
3155 | When inheriting the :ref:`ref-classes-github-releases` | ||
3156 | class, specifies the base URL for fetching releases for the github | ||
3157 | project you wish to fetch sources from. The default value is as follows:: | ||
3158 | |||
3159 | GITHUB_BASE_URI ?= "https://github.com/${BPN}/${BPN}/releases/" | ||
3160 | |||
2638 | :term:`GLIBC_GENERATE_LOCALES` | 3161 | :term:`GLIBC_GENERATE_LOCALES` |
2639 | Specifies the list of GLIBC locales to generate should you not wish | 3162 | Specifies the list of GLIBC locales to generate should you not wish |
2640 | to generate all LIBC locals, which can be time consuming. | 3163 | to generate all LIBC locals, which can be time consuming. |
@@ -2644,28 +3167,101 @@ system and gives an overview of their function and contents. | |||
2644 | If you specifically remove the locale ``en_US.UTF-8``, you must set | 3167 | If you specifically remove the locale ``en_US.UTF-8``, you must set |
2645 | :term:`IMAGE_LINGUAS` appropriately. | 3168 | :term:`IMAGE_LINGUAS` appropriately. |
2646 | 3169 | ||
2647 | You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. | 3170 | You can set :term:`GLIBC_GENERATE_LOCALES` in your ``local.conf`` file. |
2648 | By default, all locales are generated. | 3171 | By default, all locales are generated:: |
2649 | :: | ||
2650 | 3172 | ||
2651 | GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" | 3173 | GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8" |
2652 | 3174 | ||
3175 | :term:`GO_IMPORT` | ||
3176 | When inheriting the :ref:`ref-classes-go` class, this mandatory variable | ||
3177 | sets the import path for the Go package that will be created for the code | ||
3178 | to build. If you have a ``go.mod`` file in the source directory, this | ||
3179 | typically matches the path in the ``module`` line in this file. | ||
3180 | |||
3181 | Other Go programs importing this package will use this path. | ||
3182 | |||
3183 | Here is an example setting from the | ||
3184 | :yocto_git:`go-helloworld_0.1.bb </poky/tree/meta/recipes-extended/go-examples/go-helloworld_0.1.bb>` | ||
3185 | recipe:: | ||
3186 | |||
3187 | GO_IMPORT = "golang.org/x/example" | ||
3188 | |||
3189 | :term:`GO_INSTALL` | ||
3190 | When inheriting the :ref:`ref-classes-go` class, this optional variable | ||
3191 | specifies which packages in the sources should be compiled and | ||
3192 | installed in the Go build space by the | ||
3193 | `go install <https://go.dev/ref/mod#go-install>`__ command. | ||
3194 | |||
3195 | Here is an example setting from the | ||
3196 | :oe_git:`crucible </meta-openembedded/tree/meta-oe/recipes-support/crucible/>` | ||
3197 | recipe:: | ||
3198 | |||
3199 | GO_INSTALL = "\ | ||
3200 | ${GO_IMPORT}/cmd/crucible \ | ||
3201 | ${GO_IMPORT}/cmd/habtool \ | ||
3202 | " | ||
3203 | |||
3204 | By default, :term:`GO_INSTALL` is defined as:: | ||
3205 | |||
3206 | GO_INSTALL ?= "${GO_IMPORT}/..." | ||
3207 | |||
3208 | The ``...`` wildcard means that it will catch all | ||
3209 | packages found in the sources. | ||
3210 | |||
3211 | See the :term:`GO_INSTALL_FILTEROUT` variable for | ||
3212 | filtering out unwanted packages from the ones | ||
3213 | found from the :term:`GO_INSTALL` value. | ||
3214 | |||
3215 | :term:`GO_INSTALL_FILTEROUT` | ||
3216 | When using the Go "vendor" mechanism to bring in dependencies for a Go | ||
3217 | package, the default :term:`GO_INSTALL` setting, which uses the ``...`` | ||
3218 | wildcard, will include the vendored packages in the build, which produces | ||
3219 | incorrect results. | ||
3220 | |||
3221 | There are also some Go packages that are structured poorly, so that the | ||
3222 | ``...`` wildcard results in building example or test code that should not | ||
3223 | be included in the build, or could fail to build. | ||
3224 | |||
3225 | This optional variable allows for filtering out a subset of the sources. | ||
3226 | It defaults to excluding everything under the ``vendor`` subdirectory | ||
3227 | under package's main directory. This is the normal location for vendored | ||
3228 | packages, but it can be overridden by a recipe to filter out other | ||
3229 | subdirectories if needed. | ||
3230 | |||
3231 | :term:`GO_WORKDIR` | ||
3232 | When using Go Modules, the current working directory must be the directory | ||
3233 | containing the ``go.mod`` file, or one of its subdirectories. When the | ||
3234 | ``go`` tool is used, it will automatically look for the ``go.mod`` file | ||
3235 | in the Go working directory or in any parent directory, but not in | ||
3236 | subdirectories. | ||
3237 | |||
3238 | When using the :ref:`ref-classes-go-mod` class to use Go modules, | ||
3239 | the optional :term:`GO_WORKDIR` variable, defaulting to the value | ||
3240 | of :term:`GO_IMPORT`, allows to specify a different Go working directory. | ||
3241 | |||
2653 | :term:`GROUPADD_PARAM` | 3242 | :term:`GROUPADD_PARAM` |
2654 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 3243 | When inheriting the :ref:`ref-classes-useradd` class, |
2655 | this variable specifies for a package what parameters should be | 3244 | this variable specifies for a package what parameters should be |
2656 | passed to the ``groupadd`` command if you wish to add a group to the | 3245 | passed to the ``groupadd`` command if you wish to add a group to the |
2657 | system when the package is installed. | 3246 | system when the package is installed. |
2658 | 3247 | ||
2659 | Here is an example from the ``dbus`` recipe: | 3248 | Here is an example from the ``dbus`` recipe:: |
2660 | :: | 3249 | |
3250 | GROUPADD_PARAM:${PN} = "-r netdev" | ||
2661 | 3251 | ||
2662 | GROUPADD_PARAM_${PN} = "-r netdev" | 3252 | More than one group can be added by separating each set of different |
3253 | groups' parameters with a semicolon. | ||
3254 | |||
3255 | Here is an example adding multiple groups from the ``useradd-example.bb`` | ||
3256 | file in the ``meta-skeleton`` layer:: | ||
3257 | |||
3258 | GROUPADD_PARAM:${PN} = "-g 880 group1; -g 890 group2" | ||
2663 | 3259 | ||
2664 | For information on the standard Linux shell command | 3260 | For information on the standard Linux shell command |
2665 | ``groupadd``, see https://linux.die.net/man/8/groupadd. | 3261 | ``groupadd``, see https://linux.die.net/man/8/groupadd. |
2666 | 3262 | ||
2667 | :term:`GROUPMEMS_PARAM` | 3263 | :term:`GROUPMEMS_PARAM` |
2668 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 3264 | When inheriting the :ref:`ref-classes-useradd` class, |
2669 | this variable specifies for a package what parameters should be | 3265 | this variable specifies for a package what parameters should be |
2670 | passed to the ``groupmems`` command if you wish to modify the members | 3266 | passed to the ``groupmems`` command if you wish to modify the members |
2671 | of a group when the package is installed. | 3267 | of a group when the package is installed. |
@@ -2679,7 +3275,7 @@ system and gives an overview of their function and contents. | |||
2679 | ``local.conf`` or distribution configuration file to enable graphics | 3275 | ``local.conf`` or distribution configuration file to enable graphics |
2680 | and serial in the menu. | 3276 | and serial in the menu. |
2681 | 3277 | ||
2682 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | 3278 | See the :ref:`ref-classes-grub-efi` class for more |
2683 | information on how this variable is used. | 3279 | information on how this variable is used. |
2684 | 3280 | ||
2685 | :term:`GRUB_OPTS` | 3281 | :term:`GRUB_OPTS` |
@@ -2687,25 +3283,27 @@ system and gives an overview of their function and contents. | |||
2687 | configuration. Use a semi-colon character (``;``) to separate | 3283 | configuration. Use a semi-colon character (``;``) to separate |
2688 | multiple options. | 3284 | multiple options. |
2689 | 3285 | ||
2690 | The ``GRUB_OPTS`` variable is optional. See the | 3286 | The :term:`GRUB_OPTS` variable is optional. See the |
2691 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | 3287 | :ref:`ref-classes-grub-efi` class for more information |
2692 | on how this variable is used. | 3288 | on how this variable is used. |
2693 | 3289 | ||
2694 | :term:`GRUB_TIMEOUT` | 3290 | :term:`GRUB_TIMEOUT` |
2695 | Specifies the timeout before executing the default ``LABEL`` in the | 3291 | Specifies the timeout before executing the default ``LABEL`` in the |
2696 | GNU GRand Unified Bootloader (GRUB). | 3292 | GNU GRand Unified Bootloader (GRUB). |
2697 | 3293 | ||
2698 | The ``GRUB_TIMEOUT`` variable is optional. See the | 3294 | The :term:`GRUB_TIMEOUT` variable is optional. See the |
2699 | :ref:`grub-efi <ref-classes-grub-efi>` class for more information | 3295 | :ref:`ref-classes-grub-efi` class for more information |
2700 | on how this variable is used. | 3296 | on how this variable is used. |
2701 | 3297 | ||
2702 | :term:`GTKIMMODULES_PACKAGES` | 3298 | :term:`GTKIMMODULES_PACKAGES` |
2703 | When inheriting the | 3299 | When inheriting the :ref:`ref-classes-gtk-immodules-cache` class, |
2704 | :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class, | ||
2705 | this variable specifies the packages that contain the GTK+ input | 3300 | this variable specifies the packages that contain the GTK+ input |
2706 | method modules being installed when the modules are in packages other | 3301 | method modules being installed when the modules are in packages other |
2707 | than the main package. | 3302 | than the main package. |
2708 | 3303 | ||
3304 | :term:`HGDIR` | ||
3305 | See :term:`bitbake:HGDIR` in the BitBake manual. | ||
3306 | |||
2709 | :term:`HOMEPAGE` | 3307 | :term:`HOMEPAGE` |
2710 | Website where more information about the software the recipe is | 3308 | Website where more information about the software the recipe is |
2711 | building can be found. | 3309 | building can be found. |
@@ -2729,7 +3327,7 @@ system and gives an overview of their function and contents. | |||
2729 | Specifies architecture-specific compiler flags that are passed to the | 3327 | Specifies architecture-specific compiler flags that are passed to the |
2730 | C compiler. | 3328 | C compiler. |
2731 | 3329 | ||
2732 | Default initialization for ``HOST_CC_ARCH`` varies depending on what | 3330 | Default initialization for :term:`HOST_CC_ARCH` varies depending on what |
2733 | is being built: | 3331 | is being built: |
2734 | 3332 | ||
2735 | - :term:`TARGET_CC_ARCH` when building for the | 3333 | - :term:`TARGET_CC_ARCH` when building for the |
@@ -2749,7 +3347,7 @@ system and gives an overview of their function and contents. | |||
2749 | "linux-musleabi" values possible. | 3347 | "linux-musleabi" values possible. |
2750 | 3348 | ||
2751 | :term:`HOST_PREFIX` | 3349 | :term:`HOST_PREFIX` |
2752 | Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` | 3350 | Specifies the prefix for the cross-compile toolchain. :term:`HOST_PREFIX` |
2753 | is normally the same as :term:`TARGET_PREFIX`. | 3351 | is normally the same as :term:`TARGET_PREFIX`. |
2754 | 3352 | ||
2755 | :term:`HOST_SYS` | 3353 | :term:`HOST_SYS` |
@@ -2774,11 +3372,15 @@ system and gives an overview of their function and contents. | |||
2774 | - Given a recipe being built for a little-endian MIPS target running | 3372 | - Given a recipe being built for a little-endian MIPS target running |
2775 | Linux, the value might be "mipsel-linux". | 3373 | Linux, the value might be "mipsel-linux". |
2776 | 3374 | ||
3375 | :term:`HOST_VENDOR` | ||
3376 | Specifies the name of the vendor. :term:`HOST_VENDOR` is normally the | ||
3377 | same as :term:`TARGET_VENDOR`. | ||
3378 | |||
2777 | :term:`HOSTTOOLS` | 3379 | :term:`HOSTTOOLS` |
2778 | A space-separated list (filter) of tools on the build host that | 3380 | A space-separated list (filter) of tools on the build host that |
2779 | should be allowed to be called from within build tasks. Using this | 3381 | should be allowed to be called from within build tasks. Using this |
2780 | filter helps reduce the possibility of host contamination. If a tool | 3382 | filter helps reduce the possibility of host contamination. If a tool |
2781 | specified in the value of ``HOSTTOOLS`` is not found on the build | 3383 | specified in the value of :term:`HOSTTOOLS` is not found on the build |
2782 | host, the OpenEmbedded build system produces an error and the build | 3384 | host, the OpenEmbedded build system produces an error and the build |
2783 | is not started. | 3385 | is not started. |
2784 | 3386 | ||
@@ -2791,39 +3393,45 @@ system and gives an overview of their function and contents. | |||
2791 | filter helps reduce the possibility of host contamination. Unlike | 3393 | filter helps reduce the possibility of host contamination. Unlike |
2792 | :term:`HOSTTOOLS`, the OpenEmbedded build system | 3394 | :term:`HOSTTOOLS`, the OpenEmbedded build system |
2793 | does not produce an error if a tool specified in the value of | 3395 | does not produce an error if a tool specified in the value of |
2794 | ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can | 3396 | :term:`HOSTTOOLS_NONFATAL` is not found on the build host. Thus, you can |
2795 | use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. | 3397 | use :term:`HOSTTOOLS_NONFATAL` to filter optional host tools. |
2796 | 3398 | ||
2797 | :term:`HOST_VENDOR` | 3399 | :term:`ICECC_CLASS_DISABLE` |
2798 | Specifies the name of the vendor. ``HOST_VENDOR`` is normally the | 3400 | Identifies user classes that you do not want the Icecream distributed |
2799 | same as :term:`TARGET_VENDOR`. | 3401 | compile support to consider. This variable is used by the |
3402 | :ref:`ref-classes-icecc` class. You set this variable in | ||
3403 | your ``local.conf`` file. | ||
3404 | |||
3405 | When you list classes using this variable, the recipes inheriting | ||
3406 | those classes will not benefit from distributed compilation across | ||
3407 | remote hosts. Instead they will be built locally. | ||
2800 | 3408 | ||
2801 | :term:`ICECC_DISABLED` | 3409 | :term:`ICECC_DISABLED` |
2802 | Disables or enables the ``icecc`` (Icecream) function. For more | 3410 | Disables or enables the ``icecc`` (Icecream) function. For more |
2803 | information on this function and best practices for using this | 3411 | information on this function and best practices for using this |
2804 | variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" | 3412 | variable, see the ":ref:`ref-classes-icecc`" |
2805 | section. | 3413 | section. |
2806 | 3414 | ||
2807 | Setting this variable to "1" in your ``local.conf`` disables the | 3415 | Setting this variable to "1" in your ``local.conf`` disables the |
2808 | function: | 3416 | function:: |
2809 | :: | ||
2810 | 3417 | ||
2811 | ICECC_DISABLED ??= "1" | 3418 | ICECC_DISABLED ??= "1" |
2812 | 3419 | ||
2813 | To enable the function, set the variable as follows: | 3420 | To enable the function, set the variable as follows:: |
2814 | :: | ||
2815 | 3421 | ||
2816 | ICECC_DISABLED = "" | 3422 | ICECC_DISABLED = "" |
2817 | 3423 | ||
2818 | :term:`ICECC_ENV_EXEC` | 3424 | :term:`ICECC_ENV_EXEC` |
2819 | Points to the ``icecc-create-env`` script that you provide. This | 3425 | Points to the ``icecc-create-env`` script that you provide. This |
2820 | variable is used by the :ref:`icecc <ref-classes-icecc>` class. You | 3426 | variable is used by the :ref:`ref-classes-icecc` class. You |
2821 | set this variable in your ``local.conf`` file. | 3427 | set this variable in your ``local.conf`` file. |
2822 | 3428 | ||
2823 | If you do not point to a script that you provide, the OpenEmbedded | 3429 | If you do not point to a script that you provide, the OpenEmbedded |
2824 | build system uses the default script provided by the | 3430 | build system uses the default script provided by the |
2825 | ``icecc-create-env.bb`` recipe, which is a modified version and not | 3431 | :oe_git:`icecc-create-env_0.1.bb |
2826 | the one that comes with ``icecc``. | 3432 | </openembedded-core/tree/meta/recipes-devtools/icecc-create-env/icecc-create-env_0.1.bb>` |
3433 | recipe, which is a modified version and not the one that comes with | ||
3434 | ``icecream``. | ||
2827 | 3435 | ||
2828 | :term:`ICECC_PARALLEL_MAKE` | 3436 | :term:`ICECC_PARALLEL_MAKE` |
2829 | Extra options passed to the ``make`` command during the | 3437 | Extra options passed to the ``make`` command during the |
@@ -2842,87 +3450,41 @@ system and gives an overview of their function and contents. | |||
2842 | network lag, available memory, and existing machine loads can all | 3450 | network lag, available memory, and existing machine loads can all |
2843 | affect build time. Consequently, unlike the | 3451 | affect build time. Consequently, unlike the |
2844 | :term:`PARALLEL_MAKE` variable, there is no | 3452 | :term:`PARALLEL_MAKE` variable, there is no |
2845 | rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal | 3453 | rule-of-thumb for setting :term:`ICECC_PARALLEL_MAKE` to achieve optimal |
2846 | performance. | 3454 | performance. |
2847 | 3455 | ||
2848 | If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not | 3456 | If you do not set :term:`ICECC_PARALLEL_MAKE`, the build system does not |
2849 | use it (i.e. the system does not detect and assign the number of | 3457 | use it (i.e. the system does not detect and assign the number of |
2850 | cores as is done with ``PARALLEL_MAKE``). | 3458 | cores as is done with :term:`PARALLEL_MAKE`). |
2851 | 3459 | ||
2852 | :term:`ICECC_PATH` | 3460 | :term:`ICECC_PATH` |
2853 | The location of the ``icecc`` binary. You can set this variable in | 3461 | The location of the ``icecc`` binary. You can set this variable in |
2854 | your ``local.conf`` file. If your ``local.conf`` file does not define | 3462 | your ``local.conf`` file. If your ``local.conf`` file does not define |
2855 | this variable, the :ref:`icecc <ref-classes-icecc>` class attempts | 3463 | this variable, the :ref:`ref-classes-icecc` class attempts |
2856 | to define it by locating ``icecc`` using ``which``. | 3464 | to define it by locating ``icecc`` using ``which``. |
2857 | 3465 | ||
2858 | :term:`ICECC_USER_CLASS_BL` | 3466 | :term:`ICECC_RECIPE_DISABLE` |
2859 | Identifies user classes that you do not want the Icecream distributed | ||
2860 | compile support to consider. This variable is used by the | ||
2861 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | ||
2862 | your ``local.conf`` file. | ||
2863 | |||
2864 | When you list classes using this variable, you are "blacklisting" | ||
2865 | them from distributed compilation across remote hosts. Any classes | ||
2866 | you list will be distributed and compiled locally. | ||
2867 | |||
2868 | :term:`ICECC_USER_PACKAGE_BL` | ||
2869 | Identifies user recipes that you do not want the Icecream distributed | 3467 | Identifies user recipes that you do not want the Icecream distributed |
2870 | compile support to consider. This variable is used by the | 3468 | compile support to consider. This variable is used by the |
2871 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | 3469 | :ref:`ref-classes-icecc` class. You set this variable in |
2872 | your ``local.conf`` file. | 3470 | your ``local.conf`` file. |
2873 | 3471 | ||
2874 | When you list packages using this variable, you are "blacklisting" | 3472 | When you list recipes using this variable, you are excluding them |
2875 | them from distributed compilation across remote hosts. Any packages | 3473 | from distributed compilation across remote hosts. Instead they will |
2876 | you list will be distributed and compiled locally. | 3474 | be built locally. |
2877 | 3475 | ||
2878 | :term:`ICECC_USER_PACKAGE_WL` | 3476 | :term:`ICECC_RECIPE_ENABLE` |
2879 | Identifies user recipes that use an empty | 3477 | Identifies user recipes that use an empty |
2880 | :term:`PARALLEL_MAKE` variable that you want to | 3478 | :term:`PARALLEL_MAKE` variable that you want to |
2881 | force remote distributed compilation on using the Icecream | 3479 | force remote distributed compilation on using the Icecream |
2882 | distributed compile support. This variable is used by the | 3480 | distributed compile support. This variable is used by the |
2883 | :ref:`icecc <ref-classes-icecc>` class. You set this variable in | 3481 | :ref:`ref-classes-icecc` class. You set this variable in |
2884 | your ``local.conf`` file. | 3482 | your ``local.conf`` file. |
2885 | 3483 | ||
2886 | :term:`IMAGE_BASENAME` | 3484 | :term:`IMAGE_BASENAME` |
2887 | The base name of image output files. This variable defaults to the | 3485 | The base name of image output files. This variable defaults to the |
2888 | recipe name (``${``\ :term:`PN`\ ``}``). | 3486 | recipe name (``${``\ :term:`PN`\ ``}``). |
2889 | 3487 | ||
2890 | :term:`IMAGE_EFI_BOOT_FILES` | ||
2891 | A space-separated list of files installed into the boot partition | ||
2892 | when preparing an image using the Wic tool with the | ||
2893 | ``bootimg-efi`` source plugin. By default, | ||
2894 | the files are | ||
2895 | installed under the same name as the source files. To change the | ||
2896 | installed name, separate it from the original name with a semi-colon | ||
2897 | (;). Source files need to be located in | ||
2898 | :term:`DEPLOY_DIR_IMAGE`. Here are two | ||
2899 | examples: | ||
2900 | :: | ||
2901 | |||
2902 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" | ||
2903 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" | ||
2904 | |||
2905 | Alternatively, source files can be picked up using a glob pattern. In | ||
2906 | this case, the destination file must have the same name as the base | ||
2907 | name of the source file path. To install files into a directory | ||
2908 | within the target location, pass its name after a semi-colon (;). | ||
2909 | Here are two examples: | ||
2910 | :: | ||
2911 | |||
2912 | IMAGE_EFI_BOOT_FILES = "boot/loader/*" | ||
2913 | IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" | ||
2914 | |||
2915 | The first example | ||
2916 | installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` | ||
2917 | into the root of the target partition. The second example installs | ||
2918 | the same files into a ``boot`` directory within the target partition. | ||
2919 | |||
2920 | You can find information on how to use the Wic tool in the | ||
2921 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | ||
2922 | section of the Yocto Project Development Tasks Manual. Reference | ||
2923 | material for Wic is located in the | ||
2924 | ":doc:`/ref-manual/kickstart`" chapter. | ||
2925 | |||
2926 | :term:`IMAGE_BOOT_FILES` | 3488 | :term:`IMAGE_BOOT_FILES` |
2927 | A space-separated list of files installed into the boot partition | 3489 | A space-separated list of files installed into the boot partition |
2928 | when preparing an image using the Wic tool with the | 3490 | when preparing an image using the Wic tool with the |
@@ -2932,8 +3494,7 @@ system and gives an overview of their function and contents. | |||
2932 | installed name, separate it from the original name with a semi-colon | 3494 | installed name, separate it from the original name with a semi-colon |
2933 | (;). Source files need to be located in | 3495 | (;). Source files need to be located in |
2934 | :term:`DEPLOY_DIR_IMAGE`. Here are two | 3496 | :term:`DEPLOY_DIR_IMAGE`. Here are two |
2935 | examples: | 3497 | examples:: |
2936 | :: | ||
2937 | 3498 | ||
2938 | IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" | 3499 | IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" |
2939 | IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" | 3500 | IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" |
@@ -2942,8 +3503,7 @@ system and gives an overview of their function and contents. | |||
2942 | this case, the destination file must have the same name as the base | 3503 | this case, the destination file must have the same name as the base |
2943 | name of the source file path. To install files into a directory | 3504 | name of the source file path. To install files into a directory |
2944 | within the target location, pass its name after a semi-colon (;). | 3505 | within the target location, pass its name after a semi-colon (;). |
2945 | Here are two examples: | 3506 | Here are two examples:: |
2946 | :: | ||
2947 | 3507 | ||
2948 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" | 3508 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" |
2949 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" | 3509 | IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" |
@@ -2954,50 +3514,89 @@ system and gives an overview of their function and contents. | |||
2954 | the same files into a ``boot`` directory within the target partition. | 3514 | the same files into a ``boot`` directory within the target partition. |
2955 | 3515 | ||
2956 | You can find information on how to use the Wic tool in the | 3516 | You can find information on how to use the Wic tool in the |
2957 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | 3517 | ":ref:`dev-manual/wic:creating partitioned images using wic`" |
2958 | section of the Yocto Project Development Tasks Manual. Reference | 3518 | section of the Yocto Project Development Tasks Manual. Reference |
2959 | material for Wic is located in the | 3519 | material for Wic is located in the |
2960 | ":doc:`/ref-manual/kickstart`" chapter. | 3520 | ":doc:`/ref-manual/kickstart`" chapter. |
2961 | 3521 | ||
2962 | :term:`IMAGE_CLASSES` | 3522 | :term:`IMAGE_BUILDINFO_FILE` |
2963 | A list of classes that all images should inherit. You typically use | 3523 | When using the :ref:`ref-classes-image-buildinfo` class, |
2964 | this variable to specify the list of classes that register the | 3524 | specifies the file in the image to write the build information into. The |
2965 | different types of images the OpenEmbedded build system creates. | 3525 | default value is "``${sysconfdir}/buildinfo``". |
2966 | 3526 | ||
2967 | The default value for ``IMAGE_CLASSES`` is ``image_types``. You can | 3527 | :term:`IMAGE_BUILDINFO_VARS` |
2968 | set this variable in your ``local.conf`` or in a distribution | 3528 | When using the :ref:`ref-classes-image-buildinfo` class, |
2969 | configuration file. | 3529 | specifies the list of variables to include in the `Build Configuration` |
3530 | section of the output file (as a space-separated list). Defaults to | ||
3531 | ":term:`DISTRO` :term:`DISTRO_VERSION`". | ||
2970 | 3532 | ||
2971 | For more information, see ``meta/classes/image_types.bbclass`` in the | 3533 | :term:`IMAGE_CLASSES` |
2972 | :term:`Source Directory`. | 3534 | A list of classes that all images should inherit. This is typically used |
3535 | to enable functionality across all image recipes. | ||
3536 | |||
3537 | Classes specified in :term:`IMAGE_CLASSES` must be located in the | ||
3538 | ``classes-recipe/`` or ``classes/`` subdirectories. | ||
2973 | 3539 | ||
2974 | :term:`IMAGE_CMD` | 3540 | :term:`IMAGE_CMD` |
2975 | Specifies the command to create the image file for a specific image | 3541 | Specifies the command to create the image file for a specific image |
2976 | type, which corresponds to the value set set in | 3542 | type, which corresponds to the value set in |
2977 | :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, | 3543 | :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, |
2978 | ``btrfs``, and so forth). When setting this variable, you should use | 3544 | ``btrfs``, and so forth). When setting this variable, you should use |
2979 | an override for the associated type. Here is an example: | 3545 | an override for the associated type. Here is an example:: |
2980 | :: | ||
2981 | 3546 | ||
2982 | IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \ | 3547 | IMAGE_CMD:jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} --faketime \ |
2983 | --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ | 3548 | --output=${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.jffs2 \ |
2984 | ${EXTRA_IMAGECMD}" | 3549 | ${EXTRA_IMAGECMD}" |
2985 | 3550 | ||
2986 | You typically do not need to set this variable unless you are adding | 3551 | You typically do not need to set this variable unless you are adding |
2987 | support for a new image type. For more examples on how to set this | 3552 | support for a new image type. For more examples on how to set this |
2988 | variable, see the :ref:`image_types <ref-classes-image_types>` | 3553 | variable, see the :ref:`ref-classes-image_types` |
2989 | class file, which is ``meta/classes/image_types.bbclass``. | 3554 | class file, which is ``meta/classes-recipe/image_types.bbclass``. |
2990 | 3555 | ||
2991 | :term:`IMAGE_DEVICE_TABLES` | 3556 | :term:`IMAGE_DEVICE_TABLES` |
2992 | Specifies one or more files that contain custom device tables that | 3557 | Specifies one or more files that contain custom device tables that |
2993 | are passed to the ``makedevs`` command as part of creating an image. | 3558 | are passed to the ``makedevs`` command as part of creating an image. |
2994 | These files list basic device nodes that should be created under | 3559 | These files list basic device nodes that should be created under |
2995 | ``/dev`` within the image. If ``IMAGE_DEVICE_TABLES`` is not set, | 3560 | ``/dev`` within the image. If :term:`IMAGE_DEVICE_TABLES` is not set, |
2996 | ``files/device_table-minimal.txt`` is used, which is located by | 3561 | ``files/device_table-minimal.txt`` is used, which is located by |
2997 | :term:`BBPATH`. For details on how you should write | 3562 | :term:`BBPATH`. For details on how you should write |
2998 | device table files, see ``meta/files/device_table-minimal.txt`` as an | 3563 | device table files, see ``meta/files/device_table-minimal.txt`` as an |
2999 | example. | 3564 | example. |
3000 | 3565 | ||
3566 | :term:`IMAGE_EFI_BOOT_FILES` | ||
3567 | A space-separated list of files installed into the boot partition | ||
3568 | when preparing an image using the Wic tool with the | ||
3569 | ``bootimg-efi`` source plugin. By default, | ||
3570 | the files are | ||
3571 | installed under the same name as the source files. To change the | ||
3572 | installed name, separate it from the original name with a semi-colon | ||
3573 | (;). Source files need to be located in | ||
3574 | :term:`DEPLOY_DIR_IMAGE`. Here are two | ||
3575 | examples:: | ||
3576 | |||
3577 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE};bz2" | ||
3578 | IMAGE_EFI_BOOT_FILES = "${KERNEL_IMAGETYPE} microcode.cpio" | ||
3579 | |||
3580 | Alternatively, source files can be picked up using a glob pattern. In | ||
3581 | this case, the destination file must have the same name as the base | ||
3582 | name of the source file path. To install files into a directory | ||
3583 | within the target location, pass its name after a semi-colon (;). | ||
3584 | Here are two examples:: | ||
3585 | |||
3586 | IMAGE_EFI_BOOT_FILES = "boot/loader/*" | ||
3587 | IMAGE_EFI_BOOT_FILES = "boot/loader/*;boot/" | ||
3588 | |||
3589 | The first example | ||
3590 | installs all files from ``${DEPLOY_DIR_IMAGE}/boot/loader/`` | ||
3591 | into the root of the target partition. The second example installs | ||
3592 | the same files into a ``boot`` directory within the target partition. | ||
3593 | |||
3594 | You can find information on how to use the Wic tool in the | ||
3595 | ":ref:`dev-manual/wic:creating partitioned images using wic`" | ||
3596 | section of the Yocto Project Development Tasks Manual. Reference | ||
3597 | material for Wic is located in the | ||
3598 | ":doc:`/ref-manual/kickstart`" chapter. | ||
3599 | |||
3001 | :term:`IMAGE_FEATURES` | 3600 | :term:`IMAGE_FEATURES` |
3002 | The primary list of features to include in an image. Typically, you | 3601 | The primary list of features to include in an image. Typically, you |
3003 | configure this variable in an image recipe. Although you can use this | 3602 | configure this variable in an image recipe. Although you can use this |
@@ -3014,15 +3613,14 @@ system and gives an overview of their function and contents. | |||
3014 | the ":ref:`ref-features-image`" section. | 3613 | the ":ref:`ref-features-image`" section. |
3015 | 3614 | ||
3016 | For an example that shows how to customize your image by using this | 3615 | For an example that shows how to customize your image by using this |
3017 | variable, see the ":ref:`dev-manual/common-tasks:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" | 3616 | variable, see the ":ref:`dev-manual/customizing-images:customizing images using custom \`\`image_features\`\` and \`\`extra_image_features\`\``" |
3018 | section in the Yocto Project Development Tasks Manual. | 3617 | section in the Yocto Project Development Tasks Manual. |
3019 | 3618 | ||
3020 | :term:`IMAGE_FSTYPES` | 3619 | :term:`IMAGE_FSTYPES` |
3021 | Specifies the formats the OpenEmbedded build system uses during the | 3620 | Specifies the formats the OpenEmbedded build system uses during the |
3022 | build when creating the root filesystem. For example, setting | 3621 | build when creating the root filesystem. For example, setting |
3023 | ``IMAGE_FSTYPES`` as follows causes the build system to create root | 3622 | :term:`IMAGE_FSTYPES` as follows causes the build system to create root |
3024 | filesystems using two formats: ``.ext3`` and ``.tar.bz2``: | 3623 | filesystems using two formats: ``.ext3`` and ``.tar.bz2``:: |
3025 | :: | ||
3026 | 3624 | ||
3027 | IMAGE_FSTYPES = "ext3 tar.bz2" | 3625 | IMAGE_FSTYPES = "ext3 tar.bz2" |
3028 | 3626 | ||
@@ -3032,31 +3630,29 @@ system and gives an overview of their function and contents. | |||
3032 | .. note:: | 3630 | .. note:: |
3033 | 3631 | ||
3034 | - If an image recipe uses the "inherit image" line and you are | 3632 | - If an image recipe uses the "inherit image" line and you are |
3035 | setting ``IMAGE_FSTYPES`` inside the recipe, you must set | 3633 | setting :term:`IMAGE_FSTYPES` inside the recipe, you must set |
3036 | ``IMAGE_FSTYPES`` prior to using the "inherit image" line. | 3634 | :term:`IMAGE_FSTYPES` prior to using the "inherit image" line. |
3037 | 3635 | ||
3038 | - Due to the way the OpenEmbedded build system processes this | 3636 | - Due to the way the OpenEmbedded build system processes this |
3039 | variable, you cannot update its contents by using ``_append`` | 3637 | variable, you cannot update its contents by using ``:append`` |
3040 | or ``_prepend``. You must use the ``+=`` operator to add one or | 3638 | or ``:prepend``. You must use the ``+=`` operator to add one or |
3041 | more options to the ``IMAGE_FSTYPES`` variable. | 3639 | more options to the :term:`IMAGE_FSTYPES` variable. |
3042 | 3640 | ||
3043 | :term:`IMAGE_INSTALL` | 3641 | :term:`IMAGE_INSTALL` |
3044 | Used by recipes to specify the packages to install into an image | 3642 | Used by recipes to specify the packages to install into an image |
3045 | through the :ref:`image <ref-classes-image>` class. Use the | 3643 | through the :ref:`ref-classes-image` class. Use the |
3046 | ``IMAGE_INSTALL`` variable with care to avoid ordering issues. | 3644 | :term:`IMAGE_INSTALL` variable with care to avoid ordering issues. |
3047 | 3645 | ||
3048 | Image recipes set ``IMAGE_INSTALL`` to specify the packages to | 3646 | Image recipes set :term:`IMAGE_INSTALL` to specify the packages to |
3049 | install into an image through ``image.bbclass``. Additionally, | 3647 | install into an image through :ref:`ref-classes-image`. Additionally, |
3050 | "helper" classes such as the | 3648 | there are "helper" classes such as the :ref:`ref-classes-core-image` |
3051 | :ref:`core-image <ref-classes-core-image>` class exist that can | 3649 | class which can take lists used with :term:`IMAGE_FEATURES` and turn |
3052 | take lists used with ``IMAGE_FEATURES`` and turn them into | 3650 | them into auto-generated entries in :term:`IMAGE_INSTALL` in addition |
3053 | auto-generated entries in ``IMAGE_INSTALL`` in addition to its | 3651 | to its default contents. |
3054 | default contents. | ||
3055 | 3652 | ||
3056 | When you use this variable, it is best to use it as follows: | 3653 | When you use this variable, it is best to use it as follows:: |
3057 | :: | ||
3058 | 3654 | ||
3059 | IMAGE_INSTALL_append = " package-name" | 3655 | IMAGE_INSTALL:append = " package-name" |
3060 | 3656 | ||
3061 | Be sure to include the space | 3657 | Be sure to include the space |
3062 | between the quotation character and the start of the package name or | 3658 | between the quotation character and the start of the package name or |
@@ -3066,39 +3662,38 @@ system and gives an overview of their function and contents. | |||
3066 | 3662 | ||
3067 | - When working with a | 3663 | - When working with a |
3068 | :ref:`core-image-minimal-initramfs <ref-manual/images:images>` | 3664 | :ref:`core-image-minimal-initramfs <ref-manual/images:images>` |
3069 | image, do not use the ``IMAGE_INSTALL`` variable to specify | 3665 | image, do not use the :term:`IMAGE_INSTALL` variable to specify |
3070 | packages for installation. Instead, use the | 3666 | packages for installation. Instead, use the |
3071 | :term:`PACKAGE_INSTALL` variable, which | 3667 | :term:`PACKAGE_INSTALL` variable, which |
3072 | allows the initial RAM filesystem (initramfs) recipe to use a | 3668 | allows the initial RAM filesystem (:term:`Initramfs`) recipe to use a |
3073 | fixed set of packages and not be affected by ``IMAGE_INSTALL``. | 3669 | fixed set of packages and not be affected by :term:`IMAGE_INSTALL`. |
3074 | For information on creating an initramfs, see the | 3670 | For information on creating an :term:`Initramfs`, see the |
3075 | ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" | 3671 | ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" |
3076 | section in the Yocto Project Development Tasks Manual. | 3672 | section in the Yocto Project Development Tasks Manual. |
3077 | 3673 | ||
3078 | - Using ``IMAGE_INSTALL`` with the | 3674 | - Using :term:`IMAGE_INSTALL` with the |
3079 | :ref:`+= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` | 3675 | :ref:`+= <bitbake-user-manual/bitbake-user-manual-metadata:appending (+=) and prepending (=+) with spaces>` |
3080 | BitBake operator within the ``/conf/local.conf`` file or from | 3676 | BitBake operator within the ``/conf/local.conf`` file or from |
3081 | within an image recipe is not recommended. Use of this operator | 3677 | within an image recipe is not recommended. Use of this operator in |
3082 | in these ways can cause ordering issues. Since | 3678 | these ways can cause ordering issues. Since |
3083 | ``core-image.bbclass`` sets ``IMAGE_INSTALL`` to a default | 3679 | :ref:`ref-classes-core-image` sets :term:`IMAGE_INSTALL` to a |
3084 | value using the | 3680 | default value using the |
3085 | :ref:`?= <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` | 3681 | :ref:`?= <bitbake-user-manual/bitbake-user-manual-metadata:setting a default value (?=)>` |
3086 | operator, using a ``+=`` operation against ``IMAGE_INSTALL`` | 3682 | operator, using a ``+=`` operation against :term:`IMAGE_INSTALL` |
3087 | results in unexpected behavior when used within | 3683 | results in unexpected behavior when used within |
3088 | ``conf/local.conf``. Furthermore, the same operation from | 3684 | ``conf/local.conf``. Furthermore, the same operation from within an |
3089 | within an image recipe may or may not succeed depending on the | 3685 | image recipe may or may not succeed depending on the specific |
3090 | specific situation. In both these cases, the behavior is | 3686 | situation. In both these cases, the behavior is contrary to how |
3091 | contrary to how most users expect the ``+=`` operator to work. | 3687 | most users expect the ``+=`` operator to work. |
3092 | 3688 | ||
3093 | :term:`IMAGE_LINGUAS` | 3689 | :term:`IMAGE_LINGUAS` |
3094 | Specifies the list of locales to install into the image during the | 3690 | Specifies the list of locales to install into the image during the |
3095 | root filesystem construction process. The OpenEmbedded build system | 3691 | root filesystem construction process. The OpenEmbedded build system |
3096 | automatically splits locale files, which are used for localization, | 3692 | automatically splits locale files, which are used for localization, |
3097 | into separate packages. Setting the ``IMAGE_LINGUAS`` variable | 3693 | into separate packages. Setting the :term:`IMAGE_LINGUAS` variable |
3098 | ensures that any locale packages that correspond to packages already | 3694 | ensures that any locale packages that correspond to packages already |
3099 | selected for installation into the image are also installed. Here is | 3695 | selected for installation into the image are also installed. Here is |
3100 | an example: | 3696 | an example:: |
3101 | :: | ||
3102 | 3697 | ||
3103 | IMAGE_LINGUAS = "pt-br de-de" | 3698 | IMAGE_LINGUAS = "pt-br de-de" |
3104 | 3699 | ||
@@ -3116,54 +3711,72 @@ system and gives an overview of their function and contents. | |||
3116 | :term:`IMAGE_LINK_NAME` | 3711 | :term:`IMAGE_LINK_NAME` |
3117 | The name of the output image symlink (which does not include | 3712 | The name of the output image symlink (which does not include |
3118 | the version part as :term:`IMAGE_NAME` does). The default value | 3713 | the version part as :term:`IMAGE_NAME` does). The default value |
3119 | is derived using the :term:`IMAGE_BASENAME` and :term:`MACHINE` | 3714 | is derived using the :term:`IMAGE_BASENAME` and |
3120 | variables: | 3715 | :term:`IMAGE_MACHINE_SUFFIX` variables:: |
3121 | :: | 3716 | |
3717 | IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}" | ||
3718 | |||
3719 | .. note:: | ||
3720 | |||
3721 | It is possible to set this to "" to disable symlink creation, | ||
3722 | however, you also need to set :term:`IMAGE_NAME` to still have | ||
3723 | a reasonable value e.g.:: | ||
3724 | |||
3725 | IMAGE_LINK_NAME = "" | ||
3726 | IMAGE_NAME = "${IMAGE_BASENAME}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" | ||
3122 | 3727 | ||
3123 | IMAGE_LINK_NAME ?= "${IMAGE_BASENAME}-${MACHINE}" | 3728 | :term:`IMAGE_MACHINE_SUFFIX` |
3729 | Specifies the by default machine-specific suffix for image file names | ||
3730 | (before the extension). The default value is set as follows:: | ||
3124 | 3731 | ||
3732 | IMAGE_MACHINE_SUFFIX ??= "-${MACHINE}" | ||
3733 | |||
3734 | The default :term:`DEPLOY_DIR_IMAGE` already has a :term:`MACHINE` | ||
3735 | subdirectory, so you may find it unnecessary to also include this suffix | ||
3736 | in the name of every image file. If you prefer to remove the suffix you | ||
3737 | can set this variable to an empty string:: | ||
3738 | |||
3739 | IMAGE_MACHINE_SUFFIX = "" | ||
3740 | |||
3741 | (Not to be confused with :term:`IMAGE_NAME_SUFFIX`.) | ||
3125 | 3742 | ||
3126 | :term:`IMAGE_MANIFEST` | 3743 | :term:`IMAGE_MANIFEST` |
3127 | The manifest file for the image. This file lists all the installed | 3744 | The manifest file for the image. This file lists all the installed |
3128 | packages that make up the image. The file contains package | 3745 | packages that make up the image. The file contains package |
3129 | information on a line-per-package basis as follows: | 3746 | information on a line-per-package basis as follows:: |
3130 | :: | ||
3131 | 3747 | ||
3132 | packagename packagearch version | 3748 | packagename packagearch version |
3133 | 3749 | ||
3134 | The :ref:`image <ref-classes-image>` class defines the manifest | 3750 | The :ref:`rootfs-postcommands <ref-classes-rootfs*>` class defines the manifest |
3135 | file as follows: | 3751 | file as follows:: |
3136 | :: | ||
3137 | 3752 | ||
3138 | IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" | 3753 | IMAGE_MANIFEST ="${IMGDEPLOYDIR}/${IMAGE_NAME}${IMAGE_NAME_SUFFIX}.manifest" |
3139 | 3754 | ||
3140 | The location is | 3755 | The location is |
3141 | derived using the :term:`DEPLOY_DIR_IMAGE` | 3756 | derived using the :term:`IMGDEPLOYDIR` |
3142 | and :term:`IMAGE_NAME` variables. You can find | 3757 | and :term:`IMAGE_NAME` variables. You can find |
3143 | information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" | 3758 | information on how the image is created in the ":ref:`overview-manual/concepts:image generation`" |
3144 | section in the Yocto Project Overview and Concepts Manual. | 3759 | section in the Yocto Project Overview and Concepts Manual. |
3145 | 3760 | ||
3146 | :term:`IMAGE_NAME` | 3761 | :term:`IMAGE_NAME` |
3147 | The name of the output image files minus the extension. This variable | 3762 | The name of the output image files minus the extension. By default |
3148 | is derived using the :term:`IMAGE_BASENAME`, | 3763 | this variable is set using the :term:`IMAGE_LINK_NAME`, and |
3149 | :term:`MACHINE`, and :term:`IMAGE_VERSION_SUFFIX` | 3764 | :term:`IMAGE_VERSION_SUFFIX` variables:: |
3150 | variables: | ||
3151 | :: | ||
3152 | 3765 | ||
3153 | IMAGE_NAME ?= "${IMAGE_BASENAME}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | 3766 | IMAGE_NAME ?= "${IMAGE_LINK_NAME}${IMAGE_VERSION_SUFFIX}" |
3154 | 3767 | ||
3155 | :term:`IMAGE_NAME_SUFFIX` | 3768 | :term:`IMAGE_NAME_SUFFIX` |
3156 | Suffix used for the image output file name - defaults to ``".rootfs"`` | 3769 | Suffix used for the image output filename --- defaults to ``".rootfs"`` |
3157 | to distinguish the image file from other files created during image | 3770 | to distinguish the image file from other files created during image |
3158 | building; however if this suffix is redundant or not desired you can | 3771 | building; however if this suffix is redundant or not desired you can |
3159 | clear the value of this variable (set the value to ""). For example, | 3772 | clear the value of this variable (set the value to ""). For example, |
3160 | this is typically cleared in initramfs image recipes. | 3773 | this is typically cleared in :term:`Initramfs` image recipes. |
3161 | 3774 | ||
3162 | :term:`IMAGE_OVERHEAD_FACTOR` | 3775 | :term:`IMAGE_OVERHEAD_FACTOR` |
3163 | Defines a multiplier that the build system applies to the initial | 3776 | Defines a multiplier that the build system applies to the initial |
3164 | image size for cases when the multiplier times the returned disk | 3777 | image size for cases when the multiplier times the returned disk |
3165 | usage value for the image is greater than the sum of | 3778 | usage value for the image is greater than the sum of |
3166 | ``IMAGE_ROOTFS_SIZE`` and ``IMAGE_ROOTFS_EXTRA_SPACE``. The result of | 3779 | :term:`IMAGE_ROOTFS_SIZE` and :term:`IMAGE_ROOTFS_EXTRA_SPACE`. The result of |
3167 | the multiplier applied to the initial image size creates free disk | 3780 | the multiplier applied to the initial image size creates free disk |
3168 | space in the image as overhead. By default, the build process uses a | 3781 | space in the image as overhead. By default, the build process uses a |
3169 | multiplier of 1.3 for this variable. This default value results in | 3782 | multiplier of 1.3 for this variable. This default value results in |
@@ -3172,40 +3785,31 @@ system and gives an overview of their function and contents. | |||
3172 | post install scripts and the package management system uses disk | 3785 | post install scripts and the package management system uses disk |
3173 | space inside this overhead area. Consequently, the multiplier does | 3786 | space inside this overhead area. Consequently, the multiplier does |
3174 | not produce an image with all the theoretical free disk space. See | 3787 | not produce an image with all the theoretical free disk space. See |
3175 | ``IMAGE_ROOTFS_SIZE`` for information on how the build system | 3788 | :term:`IMAGE_ROOTFS_SIZE` for information on how the build system |
3176 | determines the overall image size. | 3789 | determines the overall image size. |
3177 | 3790 | ||
3178 | The default 30% free disk space typically gives the image enough room | 3791 | The default 30% free disk space typically gives the image enough room |
3179 | to boot and allows for basic post installs while still leaving a | 3792 | to boot and allows for basic post installs while still leaving a |
3180 | small amount of free disk space. If 30% free space is inadequate, you | 3793 | small amount of free disk space. If 30% free space is inadequate, you |
3181 | can increase the default value. For example, the following setting | 3794 | can increase the default value. For example, the following setting |
3182 | gives you 50% free space added to the image: | 3795 | gives you 50% free space added to the image:: |
3183 | :: | ||
3184 | 3796 | ||
3185 | IMAGE_OVERHEAD_FACTOR = "1.5" | 3797 | IMAGE_OVERHEAD_FACTOR = "1.5" |
3186 | 3798 | ||
3187 | Alternatively, you can ensure a specific amount of free disk space is | 3799 | Alternatively, you can ensure a specific amount of free disk space is |
3188 | added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` | 3800 | added to the image by using the :term:`IMAGE_ROOTFS_EXTRA_SPACE` |
3189 | variable. | 3801 | variable. |
3190 | 3802 | ||
3191 | :term:`IMAGE_PKGTYPE` | 3803 | :term:`IMAGE_PKGTYPE` |
3192 | Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the | 3804 | Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the |
3193 | OpenEmbedded build system. The variable is defined appropriately by | 3805 | OpenEmbedded build system. The variable is defined appropriately by |
3194 | the :ref:`package_deb <ref-classes-package_deb>`, | 3806 | the :ref:`ref-classes-package_deb`, :ref:`ref-classes-package_rpm`, |
3195 | :ref:`package_rpm <ref-classes-package_rpm>`, | 3807 | or :ref:`ref-classes-package_ipk` class. |
3196 | :ref:`package_ipk <ref-classes-package_ipk>`, or | ||
3197 | :ref:`package_tar <ref-classes-package_tar>` class. | ||
3198 | 3808 | ||
3199 | .. note:: | 3809 | The :ref:`ref-classes-populate-sdk-*` and :ref:`ref-classes-image` |
3810 | classes use the :term:`IMAGE_PKGTYPE` for packaging up images and SDKs. | ||
3200 | 3811 | ||
3201 | The ``package_tar`` class is broken and is not supported. It is | 3812 | You should not set the :term:`IMAGE_PKGTYPE` manually. Rather, the |
3202 | recommended that you do not use it. | ||
3203 | |||
3204 | The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and | ||
3205 | :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` | ||
3206 | for packaging up images and SDKs. | ||
3207 | |||
3208 | You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the | ||
3209 | variable is set indirectly through the appropriate | 3813 | variable is set indirectly through the appropriate |
3210 | :ref:`package_* <ref-classes-package>` class using the | 3814 | :ref:`package_* <ref-classes-package>` class using the |
3211 | :term:`PACKAGE_CLASSES` variable. The | 3815 | :term:`PACKAGE_CLASSES` variable. The |
@@ -3221,10 +3825,9 @@ system and gives an overview of their function and contents. | |||
3221 | :term:`IMAGE_POSTPROCESS_COMMAND` | 3825 | :term:`IMAGE_POSTPROCESS_COMMAND` |
3222 | Specifies a list of functions to call once the OpenEmbedded build | 3826 | Specifies a list of functions to call once the OpenEmbedded build |
3223 | system creates the final image output files. You can specify | 3827 | system creates the final image output files. You can specify |
3224 | functions separated by semicolons: | 3828 | functions separated by spaces:: |
3225 | :: | ||
3226 | 3829 | ||
3227 | IMAGE_POSTPROCESS_COMMAND += "function; ... " | 3830 | IMAGE_POSTPROCESS_COMMAND += "function" |
3228 | 3831 | ||
3229 | If you need to pass the root filesystem path to a command within the | 3832 | 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 | 3833 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -3235,10 +3838,9 @@ system and gives an overview of their function and contents. | |||
3235 | :term:`IMAGE_PREPROCESS_COMMAND` | 3838 | :term:`IMAGE_PREPROCESS_COMMAND` |
3236 | Specifies a list of functions to call before the OpenEmbedded build | 3839 | Specifies a list of functions to call before the OpenEmbedded build |
3237 | system creates the final image output files. You can specify | 3840 | system creates the final image output files. You can specify |
3238 | functions separated by semicolons: | 3841 | functions separated by spaces:: |
3239 | :: | ||
3240 | 3842 | ||
3241 | IMAGE_PREPROCESS_COMMAND += "function; ... " | 3843 | IMAGE_PREPROCESS_COMMAND += "function" |
3242 | 3844 | ||
3243 | If you need to pass the root filesystem path to a command within the | 3845 | If you need to pass the root filesystem path to a command within the |
3244 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 3846 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -3262,19 +3864,17 @@ system and gives an overview of their function and contents. | |||
3262 | Defines additional free disk space created in the image in Kbytes. By | 3864 | Defines additional free disk space created in the image in Kbytes. By |
3263 | default, this variable is set to "0". This free disk space is added | 3865 | default, this variable is set to "0". This free disk space is added |
3264 | to the image after the build system determines the image size as | 3866 | to the image after the build system determines the image size as |
3265 | described in ``IMAGE_ROOTFS_SIZE``. | 3867 | described in :term:`IMAGE_ROOTFS_SIZE`. |
3266 | 3868 | ||
3267 | This variable is particularly useful when you want to ensure that a | 3869 | This variable is particularly useful when you want to ensure that a |
3268 | specific amount of free disk space is available on a device after an | 3870 | specific amount of free disk space is available on a device after an |
3269 | image is installed and running. For example, to be sure 5 Gbytes of | 3871 | image is installed and running. For example, to be sure 5 Gbytes of |
3270 | free disk space is available, set the variable as follows: | 3872 | free disk space is available, set the variable as follows:: |
3271 | :: | ||
3272 | 3873 | ||
3273 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" | 3874 | IMAGE_ROOTFS_EXTRA_SPACE = "5242880" |
3274 | 3875 | ||
3275 | For example, the Yocto Project Build Appliance specifically requests | 3876 | For example, the Yocto Project Build Appliance specifically requests |
3276 | 40 Gbytes of extra space with the line: | 3877 | 40 Gbytes of extra space with the line:: |
3277 | :: | ||
3278 | 3878 | ||
3279 | IMAGE_ROOTFS_EXTRA_SPACE = "41943040" | 3879 | IMAGE_ROOTFS_EXTRA_SPACE = "41943040" |
3280 | 3880 | ||
@@ -3285,8 +3885,7 @@ system and gives an overview of their function and contents. | |||
3285 | the generated image, a requested size for the image, and requested | 3885 | the generated image, a requested size for the image, and requested |
3286 | additional free disk space to be added to the image. Programatically, | 3886 | additional free disk space to be added to the image. Programatically, |
3287 | the build system determines the final size of the generated image as | 3887 | the build system determines the final size of the generated image as |
3288 | follows: | 3888 | follows:: |
3289 | :: | ||
3290 | 3889 | ||
3291 | if (image-du * overhead) < rootfs-size: | 3890 | if (image-du * overhead) < rootfs-size: |
3292 | internal-rootfs-size = rootfs-size + xspace | 3891 | internal-rootfs-size = rootfs-size + xspace |
@@ -3305,10 +3904,9 @@ system and gives an overview of their function and contents. | |||
3305 | 3904 | ||
3306 | :term:`IMAGE_TYPEDEP` | 3905 | :term:`IMAGE_TYPEDEP` |
3307 | Specifies a dependency from one image type on another. Here is an | 3906 | Specifies a dependency from one image type on another. Here is an |
3308 | example from the :ref:`image-live <ref-classes-image-live>` class: | 3907 | example from the :ref:`ref-classes-image-live` class:: |
3309 | :: | ||
3310 | 3908 | ||
3311 | IMAGE_TYPEDEP_live = "ext3" | 3909 | IMAGE_TYPEDEP:live = "ext3" |
3312 | 3910 | ||
3313 | In the previous example, the variable ensures that when "live" is | 3911 | In the previous example, the variable ensures that when "live" is |
3314 | listed with the :term:`IMAGE_FSTYPES` variable, | 3912 | listed with the :term:`IMAGE_FSTYPES` variable, |
@@ -3327,6 +3925,9 @@ system and gives an overview of their function and contents. | |||
3327 | - cpio.lzma | 3925 | - cpio.lzma |
3328 | - cpio.xz | 3926 | - cpio.xz |
3329 | - cramfs | 3927 | - cramfs |
3928 | - erofs | ||
3929 | - erofs-lz4 | ||
3930 | - erofs-lz4hc | ||
3330 | - ext2 | 3931 | - ext2 |
3331 | - ext2.bz2 | 3932 | - ext2.bz2 |
3332 | - ext2.gz | 3933 | - ext2.gz |
@@ -3359,7 +3960,7 @@ system and gives an overview of their function and contents. | |||
3359 | - wic.lzma | 3960 | - wic.lzma |
3360 | 3961 | ||
3361 | For more information about these types of images, see | 3962 | For more information about these types of images, see |
3362 | ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. | 3963 | ``meta/classes-recipe/image_types*.bbclass`` in the :term:`Source Directory`. |
3363 | 3964 | ||
3364 | :term:`IMAGE_VERSION_SUFFIX` | 3965 | :term:`IMAGE_VERSION_SUFFIX` |
3365 | Version suffix that is part of the default :term:`IMAGE_NAME` and | 3966 | Version suffix that is part of the default :term:`IMAGE_NAME` and |
@@ -3369,99 +3970,85 @@ system and gives an overview of their function and contents. | |||
3369 | desired, and this suffix would then be used consistently across | 3970 | desired, and this suffix would then be used consistently across |
3370 | the build artifacts. | 3971 | the build artifacts. |
3371 | 3972 | ||
3372 | :term:`INC_PR` | 3973 | :term:`IMGDEPLOYDIR` |
3373 | Helps define the recipe revision for recipes that share a common | 3974 | When inheriting the :ref:`ref-classes-image` class directly or |
3374 | ``include`` file. You can think of this variable as part of the | 3975 | through the :ref:`ref-classes-core-image` class, the |
3375 | recipe revision as set from within an include file. | 3976 | :term:`IMGDEPLOYDIR` points to a temporary work area for deployed files |
3376 | 3977 | that is set in the ``image`` class as follows:: | |
3377 | Suppose, for example, you have a set of recipes that are used across | ||
3378 | several projects. And, within each of those recipes the revision (its | ||
3379 | :term:`PR` value) is set accordingly. In this case, when | ||
3380 | the revision of those recipes changes, the burden is on you to find | ||
3381 | all those recipes and be sure that they get changed to reflect the | ||
3382 | updated version of the recipe. In this scenario, it can get | ||
3383 | complicated when recipes that are used in many places and provide | ||
3384 | common functionality are upgraded to a new revision. | ||
3385 | |||
3386 | A more efficient way of dealing with this situation is to set the | ||
3387 | ``INC_PR`` variable inside the ``include`` files that the recipes | ||
3388 | share and then expand the ``INC_PR`` variable within the recipes to | ||
3389 | help define the recipe revision. | ||
3390 | |||
3391 | The following provides an example that shows how to use the | ||
3392 | ``INC_PR`` variable given a common ``include`` file that defines the | ||
3393 | variable. Once the variable is defined in the ``include`` file, you | ||
3394 | can use the variable to set the ``PR`` values in each recipe. You | ||
3395 | will notice that when you set a recipe's ``PR`` you can provide more | ||
3396 | granular revisioning by appending values to the ``INC_PR`` variable: | ||
3397 | :: | ||
3398 | |||
3399 | recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" | ||
3400 | recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" | ||
3401 | recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" | ||
3402 | recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" | ||
3403 | 3978 | ||
3404 | The | 3979 | IMGDEPLOYDIR = "${WORKDIR}/deploy-${PN}-image-complete" |
3405 | first line of the example establishes the baseline revision to be | 3980 | |
3406 | used for all recipes that use the ``include`` file. The remaining | 3981 | Recipes inheriting the :ref:`ref-classes-image` class should copy |
3407 | lines in the example are from individual recipes and show how the | 3982 | files to be deployed into :term:`IMGDEPLOYDIR`, and the class will take |
3408 | ``PR`` value is set. | 3983 | care of copying them into :term:`DEPLOY_DIR_IMAGE` afterwards. |
3409 | 3984 | ||
3410 | :term:`INCOMPATIBLE_LICENSE` | 3985 | :term:`INCOMPATIBLE_LICENSE` |
3411 | Specifies a space-separated list of license names (as they would | 3986 | Specifies a space-separated list of license names (as they would |
3412 | appear in :term:`LICENSE`) that should be excluded | 3987 | appear in :term:`LICENSE`) that should be excluded |
3413 | from the build. Recipes that provide no alternatives to listed | 3988 | from the build (if set globally), or from an image (if set locally |
3989 | in an image recipe). | ||
3990 | |||
3991 | When the variable is set globally, recipes that provide no alternatives to listed | ||
3414 | incompatible licenses are not built. Packages that are individually | 3992 | incompatible licenses are not built. Packages that are individually |
3415 | licensed with the specified incompatible licenses will be deleted. | 3993 | licensed with the specified incompatible licenses will be deleted. |
3994 | Most of the time this does not allow a feasible build (because it becomes impossible | ||
3995 | to satisfy build time dependencies), so the recommended way to | ||
3996 | implement license restrictions is to set the variable in specific | ||
3997 | image recipes where the restrictions must apply. That way there | ||
3998 | are no build time restrictions, but the license check is still | ||
3999 | performed when the image's filesystem is assembled from packages. | ||
4000 | |||
4001 | There is some support for wildcards in this variable's value, | ||
4002 | however it is restricted to specific licenses. Currently only | ||
4003 | these wildcards are allowed and expand as follows: | ||
4004 | |||
4005 | - ``AGPL-3.0*"``: ``AGPL-3.0-only``, ``AGPL-3.0-or-later`` | ||
4006 | - ``GPL-3.0*``: ``GPL-3.0-only``, ``GPL-3.0-or-later`` | ||
4007 | - ``LGPL-3.0*``: ``LGPL-3.0-only``, ``LGPL-3.0-or-later`` | ||
3416 | 4008 | ||
3417 | .. note:: | 4009 | .. note:: |
3418 | 4010 | ||
3419 | This functionality is only regularly tested using the following | 4011 | This functionality is only regularly tested using the following |
3420 | setting: | 4012 | setting:: |
3421 | :: | ||
3422 | 4013 | ||
3423 | INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" | 4014 | INCOMPATIBLE_LICENSE = "GPL-3.0* LGPL-3.0* AGPL-3.0*" |
3424 | 4015 | ||
3425 | 4016 | ||
3426 | Although you can use other settings, you might be required to | 4017 | Although you can use other settings, you might be required to |
3427 | remove dependencies on or provide alternatives to components that | 4018 | remove dependencies on (or provide alternatives to) components that |
3428 | are required to produce a functional system image. | 4019 | are required to produce a functional system image. |
3429 | 4020 | ||
3430 | .. note:: | 4021 | :term:`INCOMPATIBLE_LICENSE_EXCEPTIONS` |
3431 | 4022 | Specifies a space-separated list of package and license pairs that | |
3432 | It is possible to define a list of licenses that are allowed to be | 4023 | are allowed to be used even if the license is specified in |
3433 | used instead of the licenses that are excluded. To do this, define | 4024 | :term:`INCOMPATIBLE_LICENSE`. The package and license pairs are |
3434 | a variable ``COMPATIBLE_LICENSES`` with the names of the licences | 4025 | separated using a colon. Example:: |
3435 | that are allowed. Then define ``INCOMPATIBLE_LICENSE`` as: | ||
3436 | :: | ||
3437 | 4026 | ||
3438 | INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" | 4027 | INCOMPATIBLE_LICENSE_EXCEPTIONS = "gdbserver:GPL-3.0-only gdbserver:LGPL-3.0-only" |
3439 | |||
3440 | |||
3441 | This will result in ``INCOMPATIBLE_LICENSE`` containing the names of | ||
3442 | all licences from :term:`AVAILABLE_LICENSES` except the ones specified | ||
3443 | in ``COMPATIBLE_LICENSES`` , thus only allowing the latter licences to | ||
3444 | be used. | ||
3445 | 4028 | ||
3446 | :term:`INHERIT` | 4029 | :term:`INHERIT` |
3447 | Causes the named class or classes to be inherited globally. Anonymous | 4030 | Causes the named class or classes to be inherited globally. Anonymous |
3448 | functions in the class or classes are not executed for the base | 4031 | functions in the class or classes are not executed for the base |
3449 | configuration and in each individual recipe. The OpenEmbedded build | 4032 | configuration and in each individual recipe. The OpenEmbedded build |
3450 | system ignores changes to ``INHERIT`` in individual recipes. | 4033 | system ignores changes to :term:`INHERIT` in individual recipes. |
4034 | Classes inherited using :term:`INHERIT` must be located in the | ||
4035 | ``classes-global/`` or ``classes/`` subdirectories. | ||
3451 | 4036 | ||
3452 | For more information on ``INHERIT``, see the | 4037 | For more information on :term:`INHERIT`, see the |
3453 | :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" | 4038 | :ref:`bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" |
3454 | section in the Bitbake User Manual. | 4039 | section in the BitBake User Manual. |
3455 | 4040 | ||
3456 | :term:`INHERIT_DISTRO` | 4041 | :term:`INHERIT_DISTRO` |
3457 | Lists classes that will be inherited at the distribution level. It is | 4042 | Lists classes that will be inherited at the distribution level. It is |
3458 | unlikely that you want to edit this variable. | 4043 | unlikely that you want to edit this variable. |
3459 | 4044 | ||
4045 | Classes specified in :term:`INHERIT_DISTRO` must be located in the | ||
4046 | ``classes-global/`` or ``classes/`` subdirectories. | ||
4047 | |||
3460 | The default value of the variable is set as follows in the | 4048 | The default value of the variable is set as follows in the |
3461 | ``meta/conf/distro/defaultsetup.conf`` file: | 4049 | ``meta/conf/distro/defaultsetup.conf`` file:: |
3462 | :: | ||
3463 | 4050 | ||
3464 | INHERIT_DISTRO ?= "debian devshell sstate license" | 4051 | INHERIT_DISTRO ?= "debian devshell sstate license remove-libtool create-spdx" |
3465 | 4052 | ||
3466 | :term:`INHIBIT_DEFAULT_DEPS` | 4053 | :term:`INHIBIT_DEFAULT_DEPS` |
3467 | Prevents the default dependencies, namely the C compiler and standard | 4054 | Prevents the default dependencies, namely the C compiler and standard |
@@ -3482,9 +4069,8 @@ system and gives an overview of their function and contents. | |||
3482 | variable. | 4069 | variable. |
3483 | 4070 | ||
3484 | To prevent the build system from splitting out debug information | 4071 | To prevent the build system from splitting out debug information |
3485 | during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as | 4072 | during packaging, set the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable as |
3486 | follows: | 4073 | follows:: |
3487 | :: | ||
3488 | 4074 | ||
3489 | INHIBIT_PACKAGE_DEBUG_SPLIT = "1" | 4075 | INHIBIT_PACKAGE_DEBUG_SPLIT = "1" |
3490 | 4076 | ||
@@ -3495,7 +4081,7 @@ system and gives an overview of their function and contents. | |||
3495 | 4081 | ||
3496 | By default, the OpenEmbedded build system strips binaries and puts | 4082 | By default, the OpenEmbedded build system strips binaries and puts |
3497 | the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. | 4083 | the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. |
3498 | Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you | 4084 | Consequently, you should not set :term:`INHIBIT_PACKAGE_STRIP` when you |
3499 | plan to debug in general. | 4085 | plan to debug in general. |
3500 | 4086 | ||
3501 | :term:`INHIBIT_SYSROOT_STRIP` | 4087 | :term:`INHIBIT_SYSROOT_STRIP` |
@@ -3504,46 +4090,80 @@ system and gives an overview of their function and contents. | |||
3504 | 4090 | ||
3505 | By default, the OpenEmbedded build system strips binaries in the | 4091 | By default, the OpenEmbedded build system strips binaries in the |
3506 | resulting sysroot. When you specifically set the | 4092 | resulting sysroot. When you specifically set the |
3507 | ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit | 4093 | :term:`INHIBIT_SYSROOT_STRIP` variable to "1" in your recipe, you inhibit |
3508 | this stripping. | 4094 | this stripping. |
3509 | 4095 | ||
3510 | If you want to use this variable, include the | 4096 | If you want to use this variable, include the :ref:`ref-classes-staging` |
3511 | :ref:`staging <ref-classes-staging>` class. This class uses a | 4097 | class. This class uses a ``sys_strip()`` function to test for the variable |
3512 | ``sys_strip()`` function to test for the variable and acts | 4098 | and acts accordingly. |
3513 | accordingly. | ||
3514 | 4099 | ||
3515 | .. note:: | 4100 | .. note:: |
3516 | 4101 | ||
3517 | Use of the ``INHIBIT_SYSROOT_STRIP`` variable occurs in rare and | 4102 | Use of the :term:`INHIBIT_SYSROOT_STRIP` variable occurs in rare and |
3518 | special circumstances. For example, suppose you are building | 4103 | special circumstances. For example, suppose you are building |
3519 | bare-metal firmware by using an external GCC toolchain. Furthermore, | 4104 | bare-metal firmware by using an external GCC toolchain. Furthermore, |
3520 | even if the toolchain's binaries are strippable, other files exist | 4105 | even if the toolchain's binaries are strippable, there are other files |
3521 | that are needed for the build that are not strippable. | 4106 | needed for the build that are not strippable. |
4107 | |||
4108 | :term:`INIT_MANAGER` | ||
4109 | Specifies the system init manager to use. Available options are: | ||
4110 | |||
4111 | - ``sysvinit`` | ||
4112 | - ``systemd`` | ||
4113 | - ``mdev-busybox`` | ||
4114 | |||
4115 | With ``sysvinit``, the init manager is set to | ||
4116 | :wikipedia:`SysVinit <Init#SysV-style>`, the traditional UNIX init | ||
4117 | system. This is the default choice in the Poky distribution, together with | ||
4118 | the Udev device manager (see the ":ref:`device-manager`" section). | ||
4119 | |||
4120 | With ``systemd``, the init manager becomes :wikipedia:`systemd <Systemd>`, | ||
4121 | which comes with the :wikipedia:`udev <Udev>` device manager. | ||
4122 | |||
4123 | With ``mdev-busybox``, the init manager becomes the much simpler BusyBox | ||
4124 | init, together with the BusyBox mdev device manager. This is the simplest | ||
4125 | and lightest solution, and probably the best choice for low-end systems | ||
4126 | with a rather slow CPU and a limited amount of RAM. | ||
4127 | |||
4128 | More concretely, this is used to include | ||
4129 | ``conf/distro/include/init-manager-${INIT_MANAGER}.inc`` into the global | ||
4130 | configuration. You can have a look at the | ||
4131 | :yocto_git:`meta/conf/distro/include/init-manager-*.inc </poky/tree/meta/conf/distro/include>` | ||
4132 | files for more information, and also the ":ref:`init-manager`" | ||
4133 | section in the Yocto Project Development Tasks Manual. | ||
4134 | |||
4135 | :term:`INITRAMFS_DEPLOY_DIR_IMAGE` | ||
4136 | Indicates the deploy directory used by :ref:`ref-tasks-bundle_initramfs` | ||
4137 | where the :term:`INITRAMFS_IMAGE` will be fetched from. This variable is | ||
4138 | set by default to ``${DEPLOY_DIR_IMAGE}`` in the | ||
4139 | :ref:`ref-classes-kernel` class and it's only meant to be changed when | ||
4140 | building an :term:`Initramfs` image from a separate multiconfig via | ||
4141 | :term:`INITRAMFS_MULTICONFIG`. | ||
3522 | 4142 | ||
3523 | :term:`INITRAMFS_FSTYPES` | 4143 | :term:`INITRAMFS_FSTYPES` |
3524 | Defines the format for the output image of an initial RAM filesystem | 4144 | Defines the format for the output image of an initial RAM filesystem |
3525 | (initramfs), which is used during boot. Supported formats are the | 4145 | (:term:`Initramfs`), which is used during boot. Supported formats are the |
3526 | same as those supported by the | 4146 | same as those supported by the |
3527 | :term:`IMAGE_FSTYPES` variable. | 4147 | :term:`IMAGE_FSTYPES` variable. |
3528 | 4148 | ||
3529 | The default value of this variable, which is set in the | 4149 | The default value of this variable, which is set in the |
3530 | ``meta/conf/bitbake.conf`` configuration file in the | 4150 | ``meta/conf/bitbake.conf`` configuration file in the |
3531 | :term:`Source Directory`, is "cpio.gz". The Linux kernel's | 4151 | :term:`Source Directory`, is "cpio.gz". The Linux kernel's |
3532 | initramfs mechanism, as opposed to the initial RAM filesystem | 4152 | :term:`Initramfs` mechanism, as opposed to the initial RAM filesystem |
3533 | `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects | 4153 | :wikipedia:`initrd <Initrd>` mechanism, expects |
3534 | an optionally compressed cpio archive. | 4154 | an optionally compressed cpio archive. |
3535 | 4155 | ||
3536 | :term:`INITRAMFS_IMAGE` | 4156 | :term:`INITRAMFS_IMAGE` |
3537 | Specifies the :term:`PROVIDES` name of an image | 4157 | Specifies the :term:`PROVIDES` name of an image |
3538 | recipe that is used to build an initial RAM filesystem (initramfs) | 4158 | recipe that is used to build an initial RAM filesystem (:term:`Initramfs`) |
3539 | image. In other words, the ``INITRAMFS_IMAGE`` variable causes an | 4159 | image. In other words, the :term:`INITRAMFS_IMAGE` variable causes an |
3540 | additional recipe to be built as a dependency to whatever root | 4160 | additional recipe to be built as a dependency to whatever root |
3541 | filesystem recipe you might be using (e.g. ``core-image-sato``). The | 4161 | filesystem recipe you might be using (e.g. ``core-image-sato``). The |
3542 | initramfs image recipe you provide should set | 4162 | :term:`Initramfs` image recipe you provide should set |
3543 | :term:`IMAGE_FSTYPES` to | 4163 | :term:`IMAGE_FSTYPES` to |
3544 | :term:`INITRAMFS_FSTYPES`. | 4164 | :term:`INITRAMFS_FSTYPES`. |
3545 | 4165 | ||
3546 | An initramfs image provides a temporary root filesystem used for | 4166 | An :term:`Initramfs` image provides a temporary root filesystem used for |
3547 | early system initialization (e.g. loading of modules needed to locate | 4167 | early system initialization (e.g. loading of modules needed to locate |
3548 | and mount the "real" root filesystem). | 4168 | and mount the "real" root filesystem). |
3549 | 4169 | ||
@@ -3551,24 +4171,24 @@ system and gives an overview of their function and contents. | |||
3551 | 4171 | ||
3552 | See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` | 4172 | See the ``meta/recipes-core/images/core-image-minimal-initramfs.bb`` |
3553 | recipe in the :term:`Source Directory` | 4173 | recipe in the :term:`Source Directory` |
3554 | for an example initramfs recipe. To select this sample recipe as | 4174 | for an example :term:`Initramfs` recipe. To select this sample recipe as |
3555 | the one built to provide the initramfs image, set ``INITRAMFS_IMAGE`` | 4175 | the one built to provide the :term:`Initramfs` image, set :term:`INITRAMFS_IMAGE` |
3556 | to "core-image-minimal-initramfs". | 4176 | to "core-image-minimal-initramfs". |
3557 | 4177 | ||
3558 | You can also find more information by referencing the | 4178 | You can also find more information by referencing the |
3559 | ``meta-poky/conf/local.conf.sample.extended`` configuration file in | 4179 | ``meta-poky/conf/templates/default/local.conf.sample.extended`` |
3560 | the Source Directory, the :ref:`image <ref-classes-image>` class, | 4180 | configuration file in the Source Directory, the :ref:`ref-classes-image` |
3561 | and the :ref:`kernel <ref-classes-kernel>` class to see how to use | 4181 | class, and the :ref:`ref-classes-kernel` class to see how to use the |
3562 | the ``INITRAMFS_IMAGE`` variable. | 4182 | :term:`INITRAMFS_IMAGE` variable. |
3563 | 4183 | ||
3564 | If ``INITRAMFS_IMAGE`` is empty, which is the default, then no | 4184 | If :term:`INITRAMFS_IMAGE` is empty, which is the default, then no |
3565 | initramfs image is built. | 4185 | :term:`Initramfs` image is built. |
3566 | 4186 | ||
3567 | For more information, you can also see the | 4187 | For more information, you can also see the |
3568 | :term:`INITRAMFS_IMAGE_BUNDLE` | 4188 | :term:`INITRAMFS_IMAGE_BUNDLE` |
3569 | variable, which allows the generated image to be bundled inside the | 4189 | variable, which allows the generated image to be bundled inside the |
3570 | kernel image. Additionally, for information on creating an initramfs | 4190 | kernel image. Additionally, for information on creating an :term:`Initramfs` |
3571 | image, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | 4191 | image, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section |
3572 | in the Yocto Project Development Tasks Manual. | 4192 | in the Yocto Project Development Tasks Manual. |
3573 | 4193 | ||
3574 | :term:`INITRAMFS_IMAGE_BUNDLE` | 4194 | :term:`INITRAMFS_IMAGE_BUNDLE` |
@@ -3577,102 +4197,121 @@ system and gives an overview of their function and contents. | |||
3577 | extra pass | 4197 | extra pass |
3578 | (:ref:`ref-tasks-bundle_initramfs`) during | 4198 | (:ref:`ref-tasks-bundle_initramfs`) during |
3579 | kernel compilation in order to build a single binary that contains | 4199 | kernel compilation in order to build a single binary that contains |
3580 | both the kernel image and the initial RAM filesystem (initramfs) | 4200 | both the kernel image and the initial RAM filesystem (:term:`Initramfs`) |
3581 | image. This makes use of the | 4201 | image. This makes use of the |
3582 | :term:`CONFIG_INITRAMFS_SOURCE` kernel | 4202 | :term:`CONFIG_INITRAMFS_SOURCE` kernel |
3583 | feature. | 4203 | feature. |
3584 | 4204 | ||
3585 | .. note:: | 4205 | .. note:: |
3586 | 4206 | ||
3587 | Using an extra compilation pass to bundle the initramfs avoids a | 4207 | Bundling the :term:`Initramfs` with the kernel conflates the code in the |
3588 | circular dependency between the kernel recipe and the initramfs | 4208 | :term:`Initramfs` with the GPLv2 licensed Linux kernel binary. Thus only GPLv2 |
3589 | recipe should the initramfs include kernel modules. Should that be | 4209 | compatible software may be part of a bundled :term:`Initramfs`. |
3590 | the case, the initramfs recipe depends on the kernel for the | 4210 | |
3591 | kernel modules, and the kernel depends on the initramfs recipe | 4211 | .. note:: |
3592 | since the initramfs is bundled inside the kernel image. | 4212 | |
4213 | Using an extra compilation pass to bundle the :term:`Initramfs` avoids a | ||
4214 | circular dependency between the kernel recipe and the :term:`Initramfs` | ||
4215 | recipe should the :term:`Initramfs` include kernel modules. Should that be | ||
4216 | the case, the :term:`Initramfs` recipe depends on the kernel for the | ||
4217 | kernel modules, and the kernel depends on the :term:`Initramfs` recipe | ||
4218 | since the :term:`Initramfs` is bundled inside the kernel image. | ||
3593 | 4219 | ||
3594 | The combined binary is deposited into the ``tmp/deploy`` directory, | 4220 | The combined binary is deposited into the ``tmp/deploy`` directory, |
3595 | which is part of the :term:`Build Directory`. | 4221 | which is part of the :term:`Build Directory`. |
3596 | 4222 | ||
3597 | Setting the variable to "1" in a configuration file causes the | 4223 | Setting the variable to "1" in a configuration file causes the |
3598 | OpenEmbedded build system to generate a kernel image with the | 4224 | OpenEmbedded build system to generate a kernel image with the |
3599 | initramfs specified in ``INITRAMFS_IMAGE`` bundled within: | 4225 | :term:`Initramfs` specified in :term:`INITRAMFS_IMAGE` bundled within:: |
3600 | :: | ||
3601 | 4226 | ||
3602 | INITRAMFS_IMAGE_BUNDLE = "1" | 4227 | INITRAMFS_IMAGE_BUNDLE = "1" |
3603 | 4228 | ||
3604 | By default, the | 4229 | By default, the :ref:`ref-classes-kernel` class sets this variable to a |
3605 | :ref:`kernel <ref-classes-kernel>` class sets this variable to a | 4230 | null string as follows:: |
3606 | null string as follows: | ||
3607 | :: | ||
3608 | 4231 | ||
3609 | INITRAMFS_IMAGE_BUNDLE ?= "" | 4232 | INITRAMFS_IMAGE_BUNDLE ?= "" |
3610 | 4233 | ||
3611 | .. note:: | 4234 | .. note:: |
3612 | 4235 | ||
3613 | You must set the ``INITRAMFS_IMAGE_BUNDLE`` variable in a | 4236 | You must set the :term:`INITRAMFS_IMAGE_BUNDLE` variable in a |
3614 | configuration file. You cannot set the variable in a recipe file. | 4237 | configuration file. You cannot set the variable in a recipe file. |
3615 | 4238 | ||
3616 | See the | 4239 | See the |
3617 | :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/local.conf.sample.extended>` | 4240 | :yocto_git:`local.conf.sample.extended </poky/tree/meta-poky/conf/templates/default/local.conf.sample.extended>` |
3618 | file for additional information. Also, for information on creating an | 4241 | file for additional information. Also, for information on creating an |
3619 | initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | 4242 | :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section |
3620 | in the Yocto Project Development Tasks Manual. | 4243 | in the Yocto Project Development Tasks Manual. |
3621 | 4244 | ||
4245 | :term:`INITRAMFS_IMAGE_NAME` | ||
4246 | |||
4247 | This value needs to stay in sync with :term:`IMAGE_LINK_NAME`, but with | ||
4248 | :term:`INITRAMFS_IMAGE` instead of :term:`IMAGE_BASENAME`. The default value | ||
4249 | is set as follows: | ||
4250 | |||
4251 | INITRAMFS_IMAGE_NAME ?= "${@['${INITRAMFS_IMAGE}${IMAGE_MACHINE_SUFFIX}', ''][d.getVar('INITRAMFS_IMAGE') == '']}" | ||
4252 | |||
4253 | That is, if :term:`INITRAMFS_IMAGE` is set, the value of | ||
4254 | :term:`INITRAMFS_IMAGE_NAME` will be set based upon | ||
4255 | :term:`INITRAMFS_IMAGE` and :term:`IMAGE_MACHINE_SUFFIX`. | ||
4256 | |||
4257 | |||
3622 | :term:`INITRAMFS_LINK_NAME` | 4258 | :term:`INITRAMFS_LINK_NAME` |
3623 | The link name of the initial RAM filesystem image. This variable is | 4259 | The link name of the initial RAM filesystem image. This variable is |
3624 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | 4260 | set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as |
3625 | follows: | 4261 | follows:: |
3626 | :: | ||
3627 | 4262 | ||
3628 | INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" | 4263 | INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" |
3629 | 4264 | ||
3630 | The value of the | 4265 | The value of the |
3631 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | 4266 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same |
3632 | file, has the following value: | 4267 | file, has the following value:: |
3633 | :: | ||
3634 | 4268 | ||
3635 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | 4269 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" |
3636 | 4270 | ||
3637 | See the :term:`MACHINE` variable for additional | 4271 | See the :term:`MACHINE` variable for additional |
3638 | information. | 4272 | information. |
3639 | 4273 | ||
4274 | :term:`INITRAMFS_MULTICONFIG` | ||
4275 | Defines the multiconfig to create a multiconfig dependency to be used by | ||
4276 | the :ref:`ref-classes-kernel` class. | ||
4277 | |||
4278 | This allows the kernel to bundle an :term:`INITRAMFS_IMAGE` coming from | ||
4279 | a separate multiconfig, this is meant to be used in addition to :term:`INITRAMFS_DEPLOY_DIR_IMAGE`. | ||
4280 | |||
4281 | For more information on how to bundle an :term:`Initramfs` image from a separate | ||
4282 | multiconfig see the ":ref:`dev-manual/building:Bundling an Initramfs Image From a Separate Multiconfig`" | ||
4283 | section in the Yocto Project Development Tasks Manual. | ||
4284 | |||
3640 | :term:`INITRAMFS_NAME` | 4285 | :term:`INITRAMFS_NAME` |
3641 | The base name of the initial RAM filesystem image. This variable is | 4286 | The base name of the initial RAM filesystem image. This variable is |
3642 | set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | 4287 | set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as |
3643 | follows: | 4288 | follows:: |
3644 | :: | ||
3645 | 4289 | ||
3646 | INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" | 4290 | INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" |
3647 | 4291 | ||
3648 | The value of the :term:`KERNEL_ARTIFACT_NAME` | 4292 | See :term:`KERNEL_ARTIFACT_NAME` for additional information. |
3649 | variable, which is set in the same file, has the following value: | ||
3650 | :: | ||
3651 | |||
3652 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3653 | 4293 | ||
3654 | :term:`INITRD` | 4294 | :term:`INITRD` |
3655 | Indicates list of filesystem images to concatenate and use as an | 4295 | Indicates list of filesystem images to concatenate and use as an |
3656 | initial RAM disk (``initrd``). | 4296 | initial RAM disk (``initrd``). |
3657 | 4297 | ||
3658 | The ``INITRD`` variable is an optional variable used with the | 4298 | The :term:`INITRD` variable is an optional variable used with the |
3659 | :ref:`image-live <ref-classes-image-live>` class. | 4299 | :ref:`ref-classes-image-live` class. |
3660 | 4300 | ||
3661 | :term:`INITRD_IMAGE` | 4301 | :term:`INITRD_IMAGE` |
3662 | When building a "live" bootable image (i.e. when | 4302 | When building a "live" bootable image (i.e. when |
3663 | :term:`IMAGE_FSTYPES` contains "live"), | 4303 | :term:`IMAGE_FSTYPES` contains "live"), |
3664 | ``INITRD_IMAGE`` specifies the image recipe that should be built to | 4304 | :term:`INITRD_IMAGE` specifies the image recipe that should be built to |
3665 | provide the initial RAM disk image. The default value is | 4305 | provide the initial RAM disk image. The default value is |
3666 | "core-image-minimal-initramfs". | 4306 | "core-image-minimal-initramfs". |
3667 | 4307 | ||
3668 | See the :ref:`image-live <ref-classes-image-live>` class for more | 4308 | See the :ref:`ref-classes-image-live` class for more information. |
3669 | information. | ||
3670 | 4309 | ||
3671 | :term:`INITSCRIPT_NAME` | 4310 | :term:`INITSCRIPT_NAME` |
3672 | The filename of the initialization script as installed to | 4311 | The filename of the initialization script as installed to |
3673 | ``${sysconfdir}/init.d``. | 4312 | ``${sysconfdir}/init.d``. |
3674 | 4313 | ||
3675 | This variable is used in recipes when using ``update-rc.d.bbclass``. | 4314 | This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. |
3676 | The variable is mandatory. | 4315 | The variable is mandatory. |
3677 | 4316 | ||
3678 | :term:`INITSCRIPT_PACKAGES` | 4317 | :term:`INITSCRIPT_PACKAGES` |
@@ -3680,13 +4319,12 @@ system and gives an overview of their function and contents. | |||
3680 | are specified, you need to append the package name to the other | 4319 | are specified, you need to append the package name to the other |
3681 | ``INITSCRIPT_*`` as an override. | 4320 | ``INITSCRIPT_*`` as an override. |
3682 | 4321 | ||
3683 | This variable is used in recipes when using ``update-rc.d.bbclass``. | 4322 | This variable is used in recipes when using :ref:`ref-classes-update-rc.d`. |
3684 | The variable is optional and defaults to the :term:`PN` | 4323 | The variable is optional and defaults to the :term:`PN` |
3685 | variable. | 4324 | variable. |
3686 | 4325 | ||
3687 | :term:`INITSCRIPT_PARAMS` | 4326 | :term:`INITSCRIPT_PARAMS` |
3688 | Specifies the options to pass to ``update-rc.d``. Here is an example: | 4327 | Specifies the options to pass to ``update-rc.d``. Here is an example:: |
3689 | :: | ||
3690 | 4328 | ||
3691 | INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." | 4329 | INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." |
3692 | 4330 | ||
@@ -3694,9 +4332,9 @@ system and gives an overview of their function and contents. | |||
3694 | in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. | 4332 | in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. |
3695 | 4333 | ||
3696 | The variable's default value is "defaults", which is set in the | 4334 | The variable's default value is "defaults", which is set in the |
3697 | :ref:`update-rc.d <ref-classes-update-rc.d>` class. | 4335 | :ref:`ref-classes-update-rc.d` class. |
3698 | 4336 | ||
3699 | The value in ``INITSCRIPT_PARAMS`` is passed through to the | 4337 | The value in :term:`INITSCRIPT_PARAMS` is passed through to the |
3700 | ``update-rc.d`` command. For more information on valid parameters, | 4338 | ``update-rc.d`` command. For more information on valid parameters, |
3701 | please see the ``update-rc.d`` manual page at | 4339 | please see the ``update-rc.d`` manual page at |
3702 | https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html | 4340 | https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html |
@@ -3706,17 +4344,16 @@ system and gives an overview of their function and contents. | |||
3706 | recipe. For example, to skip the check for symbolic link ``.so`` | 4344 | recipe. For example, to skip the check for symbolic link ``.so`` |
3707 | files in the main package of a recipe, add the following to the | 4345 | files in the main package of a recipe, add the following to the |
3708 | recipe. The package name override must be used, which in this example | 4346 | recipe. The package name override must be used, which in this example |
3709 | is ``${PN}``: | 4347 | is ``${PN}``:: |
3710 | :: | ||
3711 | 4348 | ||
3712 | INSANE_SKIP_${PN} += "dev-so" | 4349 | INSANE_SKIP:${PN} += "dev-so" |
3713 | 4350 | ||
3714 | See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a | 4351 | See the ":ref:`ref-classes-insane`" section for a |
3715 | list of the valid QA checks you can specify using this variable. | 4352 | list of the valid QA checks you can specify using this variable. |
3716 | 4353 | ||
3717 | :term:`INSTALL_TIMEZONE_FILE` | 4354 | :term:`INSTALL_TIMEZONE_FILE` |
3718 | By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. | 4355 | By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. |
3719 | Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the | 4356 | Set the :term:`INSTALL_TIMEZONE_FILE` variable to "0" at the |
3720 | configuration level to disable this behavior. | 4357 | configuration level to disable this behavior. |
3721 | 4358 | ||
3722 | :term:`IPK_FEED_URIS` | 4359 | :term:`IPK_FEED_URIS` |
@@ -3737,7 +4374,7 @@ system and gives an overview of their function and contents. | |||
3737 | - qemu | 4374 | - qemu |
3738 | - mips | 4375 | - mips |
3739 | 4376 | ||
3740 | You define the ``KARCH`` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. | 4377 | You define the :term:`KARCH` variable in the :ref:`kernel-dev/advanced:bsp descriptions`. |
3741 | 4378 | ||
3742 | :term:`KBRANCH` | 4379 | :term:`KBRANCH` |
3743 | A regular expression used by the build process to explicitly identify | 4380 | A regular expression used by the build process to explicitly identify |
@@ -3748,34 +4385,31 @@ system and gives an overview of their function and contents. | |||
3748 | Values for this variable are set in the kernel's recipe file and the | 4385 | Values for this variable are set in the kernel's recipe file and the |
3749 | kernel's append file. For example, if you are using the | 4386 | kernel's append file. For example, if you are using the |
3750 | ``linux-yocto_4.12`` kernel, the kernel recipe file is the | 4387 | ``linux-yocto_4.12`` kernel, the kernel recipe file is the |
3751 | ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` | 4388 | ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. :term:`KBRANCH` |
3752 | is set as follows in that kernel recipe file: | 4389 | is set as follows in that kernel recipe file:: |
3753 | :: | ||
3754 | 4390 | ||
3755 | KBRANCH ?= "standard/base" | 4391 | KBRANCH ?= "standard/base" |
3756 | 4392 | ||
3757 | This variable is also used from the kernel's append file to identify | 4393 | This variable is also used from the kernel's append file to identify |
3758 | the kernel branch specific to a particular machine or target | 4394 | the kernel branch specific to a particular machine or target |
3759 | hardware. Continuing with the previous kernel example, the kernel's | 4395 | hardware. Continuing with the previous kernel example, the kernel's |
3760 | append file (i.e. ``linux-yocto_4.12.bbappend``) is located in the | 4396 | append file is located in the |
3761 | BSP layer for a given machine. For example, the append file for the | 4397 | BSP layer for a given machine. For example, the append file for the |
3762 | Beaglebone, EdgeRouter, and generic versions of both 32 and 64-bit IA | 4398 | Beaglebone and generic versions of both 32 and 64-bit IA |
3763 | machines (``meta-yocto-bsp``) is named | 4399 | machines (``meta-yocto-bsp``) is named |
3764 | ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. | 4400 | ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_6.1.bbappend``. |
3765 | Here are the related statements from that append file: | 4401 | Here are the related statements from that append file:: |
3766 | :: | ||
3767 | 4402 | ||
3768 | KBRANCH_genericx86 = "standard/base" | 4403 | KBRANCH:genericx86 = "v6.1/standard/base" |
3769 | KBRANCH_genericx86-64 = "standard/base" | 4404 | KBRANCH:genericx86-64 = "v6.1/standard/base" |
3770 | KBRANCH_edgerouter = "standard/edgerouter" | 4405 | KBRANCH:beaglebone-yocto = "v6.1/standard/beaglebone" |
3771 | KBRANCH_beaglebone = "standard/beaglebone" | ||
3772 | 4406 | ||
3773 | The ``KBRANCH`` statements | 4407 | The :term:`KBRANCH` statements |
3774 | identify the kernel branch to use when building for each supported | 4408 | identify the kernel branch to use when building for each supported |
3775 | BSP. | 4409 | BSP. |
3776 | 4410 | ||
3777 | :term:`KBUILD_DEFCONFIG` | 4411 | :term:`KBUILD_DEFCONFIG` |
3778 | When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` | 4412 | When used with the :ref:`ref-classes-kernel-yocto` |
3779 | class, specifies an "in-tree" kernel configuration file for use | 4413 | class, specifies an "in-tree" kernel configuration file for use |
3780 | during a kernel build. | 4414 | during a kernel build. |
3781 | 4415 | ||
@@ -3784,60 +4418,118 @@ system and gives an overview of their function and contents. | |||
3784 | would place patch files and configuration fragment files (i.e. | 4418 | would place patch files and configuration fragment files (i.e. |
3785 | "out-of-tree"). However, if you want to use a ``defconfig`` file that | 4419 | "out-of-tree"). However, if you want to use a ``defconfig`` file that |
3786 | is part of the kernel tree (i.e. "in-tree"), you can use the | 4420 | is part of the kernel tree (i.e. "in-tree"), you can use the |
3787 | ``KBUILD_DEFCONFIG`` variable and append the | 4421 | :term:`KBUILD_DEFCONFIG` variable and append the |
3788 | :term:`KMACHINE` variable to point to the | 4422 | :term:`KMACHINE` variable to point to the |
3789 | ``defconfig`` file. | 4423 | ``defconfig`` file. |
3790 | 4424 | ||
3791 | To use the variable, set it in the append file for your kernel recipe | 4425 | To use the variable, set it in the append file for your kernel recipe |
3792 | using the following form: | 4426 | using the following form:: |
3793 | :: | ||
3794 | 4427 | ||
3795 | KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file | 4428 | KBUILD_DEFCONFIG:<machine> ?= "defconfig_file" |
3796 | 4429 | ||
3797 | Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses | 4430 | Here is an example from a "raspberrypi2" :term:`MACHINE` build that uses |
3798 | a ``defconfig`` file named "bcm2709_defconfig": | 4431 | a ``defconfig`` file named "bcm2709_defconfig":: |
3799 | :: | ||
3800 | 4432 | ||
3801 | KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" | 4433 | KBUILD_DEFCONFIG:raspberrypi2 = "bcm2709_defconfig" |
3802 | 4434 | ||
3803 | As an alternative, you can use the following within your append file: | 4435 | As an alternative, you can use the following within your append file:: |
3804 | :: | ||
3805 | 4436 | ||
3806 | KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file | 4437 | KBUILD_DEFCONFIG:pn-linux-yocto ?= "defconfig_file" |
3807 | 4438 | ||
3808 | For more | 4439 | For more |
3809 | information on how to use the ``KBUILD_DEFCONFIG`` variable, see the | 4440 | information on how to use the :term:`KBUILD_DEFCONFIG` variable, see the |
3810 | ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" | 4441 | ":ref:`kernel-dev/common:using an "in-tree" \`\`defconfig\`\` file`" |
3811 | section in the Yocto Project Linux Kernel Development Manual. | 4442 | section in the Yocto Project Linux Kernel Development Manual. |
3812 | 4443 | ||
4444 | :term:`KCONFIG_MODE` | ||
4445 | When used with the :ref:`ref-classes-kernel-yocto` | ||
4446 | class, specifies the kernel configuration values to use for options | ||
4447 | not specified in the provided ``defconfig`` file. Valid options are:: | ||
4448 | |||
4449 | KCONFIG_MODE = "alldefconfig" | ||
4450 | KCONFIG_MODE = "allnoconfig" | ||
4451 | |||
4452 | In ``alldefconfig`` mode the options not explicitly specified will be | ||
4453 | assigned their Kconfig default value. In ``allnoconfig`` mode the | ||
4454 | options not explicitly specified will be disabled in the kernel | ||
4455 | config. | ||
4456 | |||
4457 | In case :term:`KCONFIG_MODE` is not set the behaviour will depend on where | ||
4458 | the ``defconfig`` file is coming from. An "in-tree" ``defconfig`` file | ||
4459 | will be handled in ``alldefconfig`` mode, a ``defconfig`` file placed | ||
4460 | in ``${WORKDIR}`` through a meta-layer will be handled in | ||
4461 | ``allnoconfig`` mode. | ||
4462 | |||
4463 | An "in-tree" ``defconfig`` file can be selected via the | ||
4464 | :term:`KBUILD_DEFCONFIG` variable. :term:`KCONFIG_MODE` does not need to | ||
4465 | be explicitly set. | ||
4466 | |||
4467 | A ``defconfig`` file compatible with ``allnoconfig`` mode can be | ||
4468 | generated by copying the ``.config`` file from a working Linux kernel | ||
4469 | build, renaming it to ``defconfig`` and placing it into the Linux | ||
4470 | kernel ``${WORKDIR}`` through your meta-layer. :term:`KCONFIG_MODE` does | ||
4471 | not need to be explicitly set. | ||
4472 | |||
4473 | A ``defconfig`` file compatible with ``alldefconfig`` mode can be | ||
4474 | generated using the | ||
4475 | :ref:`ref-tasks-savedefconfig` | ||
4476 | task and placed into the Linux kernel ``${WORKDIR}`` through your | ||
4477 | meta-layer. Explicitely set :term:`KCONFIG_MODE`:: | ||
4478 | |||
4479 | KCONFIG_MODE = "alldefconfig" | ||
4480 | |||
3813 | :term:`KERNEL_ALT_IMAGETYPE` | 4481 | :term:`KERNEL_ALT_IMAGETYPE` |
3814 | Specifies an alternate kernel image type for creation in addition to | 4482 | Specifies an alternate kernel image type for creation in addition to |
3815 | the kernel image type specified using the | 4483 | the kernel image type specified using the :term:`KERNEL_IMAGETYPE` and |
3816 | :term:`KERNEL_IMAGETYPE` variable. | 4484 | :term:`KERNEL_IMAGETYPES` variables. |
3817 | 4485 | ||
3818 | :term:`KERNEL_ARTIFACT_NAME` | 4486 | :term:`KERNEL_ARTIFACT_NAME` |
3819 | Specifies the name of all of the build artifacts. You can change the | 4487 | Specifies the name of all of the build artifacts. You can change the |
3820 | name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` | 4488 | name of the artifacts by changing the :term:`KERNEL_ARTIFACT_NAME` |
3821 | variable. | 4489 | variable. |
3822 | 4490 | ||
3823 | The value of ``KERNEL_ARTIFACT_NAME``, which is set in the | 4491 | The value of :term:`KERNEL_ARTIFACT_NAME`, which is set in the |
3824 | ``meta/classes/kernel-artifact-names.bbclass`` file, has the | 4492 | ``meta/classes-recipe/kernel-artifact-names.bbclass`` file, has the |
3825 | following default value: | 4493 | following default value:: |
3826 | :: | ||
3827 | 4494 | ||
3828 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | 4495 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}${IMAGE_MACHINE_SUFFIX}${IMAGE_VERSION_SUFFIX}" |
3829 | 4496 | ||
3830 | See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`MACHINE` | 4497 | See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, :term:`IMAGE_MACHINE_SUFFIX` |
3831 | and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. | 4498 | and :term:`IMAGE_VERSION_SUFFIX` variables for additional information. |
3832 | 4499 | ||
3833 | :term:`KERNEL_CLASSES` | 4500 | :term:`KERNEL_CLASSES` |
3834 | A list of classes defining kernel image types that the | 4501 | A list of classes defining kernel image types that the |
3835 | :ref:`kernel <ref-classes-kernel>` class should inherit. You | 4502 | :ref:`ref-classes-kernel` class should inherit. You typically |
3836 | typically append this variable to enable extended image types. An | 4503 | append this variable to enable extended image types. An example is |
3837 | example is the "kernel-fitimage", which enables fitImage support and | 4504 | ":ref:`ref-classes-kernel-fitimage`", which enables |
3838 | resides in ``meta/classes/kernel-fitimage.bbclass``. You can register | 4505 | FIT image support and resides in ``meta/classes-recipe/kernel-fitimage.bbclass``. |
3839 | custom kernel image types with the ``kernel`` class using this | 4506 | You can register custom kernel image types with the |
3840 | variable. | 4507 | :ref:`ref-classes-kernel` class using this variable. |
4508 | |||
4509 | :term:`KERNEL_DANGLING_FEATURES_WARN_ONLY` | ||
4510 | When kernel configuration fragments are missing for some | ||
4511 | :term:`KERNEL_FEATURES` specified by layers or BSPs, | ||
4512 | building and configuring the kernel stops with an error. | ||
4513 | |||
4514 | You can turn these errors into warnings by setting the | ||
4515 | following in ``conf/local.conf``:: | ||
4516 | |||
4517 | KERNEL_DANGLING_FEATURES_WARN_ONLY = "1" | ||
4518 | |||
4519 | You will still be warned that runtime issues may occur, | ||
4520 | but at least the kernel configuration and build process will | ||
4521 | be allowed to continue. | ||
4522 | |||
4523 | :term:`KERNEL_DEBUG_TIMESTAMPS` | ||
4524 | If set to "1", enables timestamping functionality during building | ||
4525 | the kernel. The default is "0" to disable this for reproducibility | ||
4526 | reasons. | ||
4527 | |||
4528 | :term:`KERNEL_DEPLOY_DEPEND` | ||
4529 | Provides a means of controlling the dependency of an image recipe | ||
4530 | on the kernel. The default value is "virtual/kernel:do_deploy", | ||
4531 | however for a small initramfs image or other images that do not | ||
4532 | need the kernel, this can be set to "" in the image recipe. | ||
3841 | 4533 | ||
3842 | :term:`KERNEL_DEVICETREE` | 4534 | :term:`KERNEL_DEVICETREE` |
3843 | Specifies the name of the generated Linux kernel device tree (i.e. | 4535 | Specifies the name of the generated Linux kernel device tree (i.e. |
@@ -3845,25 +4537,32 @@ system and gives an overview of their function and contents. | |||
3845 | 4537 | ||
3846 | .. note:: | 4538 | .. note:: |
3847 | 4539 | ||
3848 | Legacy support exists for specifying the full path to the device | 4540 | There is legacy support for specifying the full path to the device |
3849 | tree. However, providing just the ``.dtb`` file is preferred. | 4541 | tree. However, providing just the ``.dtb`` file is preferred. |
3850 | 4542 | ||
3851 | In order to use this variable, the | 4543 | In order to use this variable, the :ref:`ref-classes-kernel-devicetree` |
3852 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must | 4544 | class must be inherited. |
3853 | be inherited. | 4545 | |
4546 | :term:`KERNEL_DEVICETREE_BUNDLE` | ||
4547 | When set to "1", this variable allows to bundle the Linux kernel | ||
4548 | and the Device Tree Binary together in a single file. | ||
4549 | |||
4550 | This feature is currently only supported on the "arm" (32 bit) | ||
4551 | architecture. | ||
4552 | |||
4553 | This variable is set to "0" by default by the | ||
4554 | :ref:`ref-classes-kernel-devicetree` class. | ||
3854 | 4555 | ||
3855 | :term:`KERNEL_DTB_LINK_NAME` | 4556 | :term:`KERNEL_DTB_LINK_NAME` |
3856 | The link name of the kernel device tree binary (DTB). This variable | 4557 | The link name of the kernel device tree binary (DTB). This variable |
3857 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | 4558 | is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as |
3858 | follows: | 4559 | follows:: |
3859 | :: | ||
3860 | 4560 | ||
3861 | KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | 4561 | KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" |
3862 | 4562 | ||
3863 | The | 4563 | The |
3864 | value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in | 4564 | value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in |
3865 | the same file, has the following value: | 4565 | the same file, has the following value:: |
3866 | :: | ||
3867 | 4566 | ||
3868 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | 4567 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" |
3869 | 4568 | ||
@@ -3872,26 +4571,37 @@ system and gives an overview of their function and contents. | |||
3872 | 4571 | ||
3873 | :term:`KERNEL_DTB_NAME` | 4572 | :term:`KERNEL_DTB_NAME` |
3874 | The base name of the kernel device tree binary (DTB). This variable | 4573 | The base name of the kernel device tree binary (DTB). This variable |
3875 | is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as | 4574 | is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as |
3876 | follows: | 4575 | follows:: |
3877 | :: | ||
3878 | 4576 | ||
3879 | KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" | 4577 | KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" |
3880 | 4578 | ||
3881 | The value of the :term:`KERNEL_ARTIFACT_NAME` | 4579 | See :term:`KERNEL_ARTIFACT_NAME` for additional information. |
3882 | variable, which is set in the same file, has the following value: | 4580 | |
3883 | :: | 4581 | :term:`KERNEL_DTBDEST` |
4582 | This variable, used by the :ref:`ref-classes-kernel-devicetree` | ||
4583 | class, allows to change the installation directory of the DTB | ||
4584 | (Device Tree Binary) files. | ||
4585 | |||
4586 | It is set by default to "${KERNEL_IMAGEDEST}" by the | ||
4587 | :ref:`ref-classes-kernel` class. | ||
4588 | |||
4589 | :term:`KERNEL_DTBVENDORED` | ||
4590 | This variable, used by the :ref:`ref-classes-kernel-devicetree`, | ||
4591 | allows to ignore vendor subdirectories when installing DTB | ||
4592 | (Device Tree Binary) files, when it is set to "false". | ||
3884 | 4593 | ||
3885 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | 4594 | To keep vendor subdirectories, set this variable to "true". |
4595 | |||
4596 | It is set by default to "false" by the :ref:`ref-classes-kernel` class. | ||
3886 | 4597 | ||
3887 | :term:`KERNEL_DTC_FLAGS` | 4598 | :term:`KERNEL_DTC_FLAGS` |
3888 | Specifies the ``dtc`` flags that are passed to the Linux kernel build | 4599 | Specifies the ``dtc`` flags that are passed to the Linux kernel build |
3889 | system when generating the device trees (via ``DTC_FLAGS`` environment | 4600 | system when generating the device trees (via ``DTC_FLAGS`` environment |
3890 | variable). | 4601 | variable). |
3891 | 4602 | ||
3892 | In order to use this variable, the | 4603 | In order to use this variable, the :ref:`ref-classes-kernel-devicetree` |
3893 | :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must | 4604 | class must be inherited. |
3894 | be inherited. | ||
3895 | 4605 | ||
3896 | :term:`KERNEL_EXTRA_ARGS` | 4606 | :term:`KERNEL_EXTRA_ARGS` |
3897 | Specifies additional ``make`` command-line arguments the OpenEmbedded | 4607 | Specifies additional ``make`` command-line arguments the OpenEmbedded |
@@ -3902,40 +4612,37 @@ system and gives an overview of their function and contents. | |||
3902 | system, the default Board Support Packages (BSPs) | 4612 | system, the default Board Support Packages (BSPs) |
3903 | :term:`Metadata` is provided through the | 4613 | :term:`Metadata` is provided through the |
3904 | :term:`KMACHINE` and :term:`KBRANCH` | 4614 | :term:`KMACHINE` and :term:`KBRANCH` |
3905 | variables. You can use the ``KERNEL_FEATURES`` variable from within | 4615 | variables. You can use the :term:`KERNEL_FEATURES` variable from within |
3906 | the kernel recipe or kernel append file to further add metadata for | 4616 | the kernel recipe or kernel append file to further add metadata for |
3907 | all BSPs or specific BSPs. | 4617 | all BSPs or specific BSPs. |
3908 | 4618 | ||
3909 | The metadata you add through this variable includes config fragments | 4619 | The metadata you add through this variable includes config fragments |
3910 | and features descriptions, which usually includes patches as well as | 4620 | and features descriptions, which usually includes patches as well as |
3911 | config fragments. You typically override the ``KERNEL_FEATURES`` | 4621 | config fragments. You typically override the :term:`KERNEL_FEATURES` |
3912 | variable for a specific machine. In this way, you can provide | 4622 | variable for a specific machine. In this way, you can provide |
3913 | validated, but optional, sets of kernel configurations and features. | 4623 | validated, but optional, sets of kernel configurations and features. |
3914 | 4624 | ||
3915 | For example, the following example from the ``linux-yocto-rt_4.12`` | 4625 | For example, the following example from the ``linux-yocto-rt_4.12`` |
3916 | kernel recipe adds "netfilter" and "taskstats" features to all BSPs | 4626 | kernel recipe adds "netfilter" and "taskstats" features to all BSPs |
3917 | as well as "virtio" configurations to all QEMU machines. The last two | 4627 | as well as "virtio" configurations to all QEMU machines. The last two |
3918 | statements add specific configurations to targeted machine types: | 4628 | statements add specific configurations to targeted machine types:: |
3919 | :: | ||
3920 | 4629 | ||
3921 | KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" | 4630 | KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc" |
3922 | KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}" | 4631 | KERNEL_FEATURES:append = " ${KERNEL_EXTRA_FEATURES}" |
3923 | KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc" | 4632 | KERNEL_FEATURES:append:qemuall = " cfg/virtio.scc" |
3924 | KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" | 4633 | KERNEL_FEATURES:append:qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc" |
3925 | KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc" | 4634 | KERNEL_FEATURES:append:qemux86-64 = " cfg/sound.scc" |
3926 | 4635 | ||
3927 | :term:`KERNEL_FIT_LINK_NAME` | 4636 | :term:`KERNEL_FIT_LINK_NAME` |
3928 | The link name of the kernel flattened image tree (FIT) image. This | 4637 | The link name of the kernel flattened image tree (FIT) image. This |
3929 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | 4638 | variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` |
3930 | file as follows: | 4639 | file as follows:: |
3931 | :: | ||
3932 | 4640 | ||
3933 | KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | 4641 | KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" |
3934 | 4642 | ||
3935 | The value of the | 4643 | The value of the |
3936 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | 4644 | ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same |
3937 | file, has the following value: | 4645 | file, has the following value:: |
3938 | :: | ||
3939 | 4646 | ||
3940 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | 4647 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" |
3941 | 4648 | ||
@@ -3944,29 +4651,22 @@ system and gives an overview of their function and contents. | |||
3944 | 4651 | ||
3945 | :term:`KERNEL_FIT_NAME` | 4652 | :term:`KERNEL_FIT_NAME` |
3946 | The base name of the kernel flattened image tree (FIT) image. This | 4653 | The base name of the kernel flattened image tree (FIT) image. This |
3947 | variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` | 4654 | variable is set in the ``meta/classes-recipe/kernel-artifact-names.bbclass`` |
3948 | file as follows: | 4655 | file as follows:: |
3949 | :: | ||
3950 | 4656 | ||
3951 | KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" | 4657 | KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" |
3952 | 4658 | ||
3953 | The value of the :term:`KERNEL_ARTIFACT_NAME` | 4659 | See :term:`KERNEL_ARTIFACT_NAME` for additional information. |
3954 | variable, which is set in the same file, has the following value: | ||
3955 | :: | ||
3956 | |||
3957 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
3958 | 4660 | ||
3959 | :term:`KERNEL_IMAGE_LINK_NAME` | 4661 | :term:`KERNEL_IMAGE_LINK_NAME` |
3960 | The link name for the kernel image. This variable is set in the | 4662 | The link name for the kernel image. This variable is set in the |
3961 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | 4663 | ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: |
3962 | :: | ||
3963 | 4664 | ||
3964 | KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | 4665 | KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" |
3965 | 4666 | ||
3966 | The value of | 4667 | The value of |
3967 | the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same | 4668 | the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same |
3968 | file, has the following value: | 4669 | file, has the following value:: |
3969 | :: | ||
3970 | 4670 | ||
3971 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | 4671 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" |
3972 | 4672 | ||
@@ -3975,12 +4675,12 @@ system and gives an overview of their function and contents. | |||
3975 | 4675 | ||
3976 | :term:`KERNEL_IMAGE_MAXSIZE` | 4676 | :term:`KERNEL_IMAGE_MAXSIZE` |
3977 | Specifies the maximum size of the kernel image file in kilobytes. If | 4677 | Specifies the maximum size of the kernel image file in kilobytes. If |
3978 | ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is | 4678 | :term:`KERNEL_IMAGE_MAXSIZE` is set, the size of the kernel image file is |
3979 | checked against the set value during the | 4679 | checked against the set value during the |
3980 | :ref:`ref-tasks-sizecheck` task. The task fails if | 4680 | :ref:`ref-tasks-sizecheck` task. The task fails if |
3981 | the kernel image file is larger than the setting. | 4681 | the kernel image file is larger than the setting. |
3982 | 4682 | ||
3983 | ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a | 4683 | :term:`KERNEL_IMAGE_MAXSIZE` is useful for target devices that have a |
3984 | limited amount of space in which the kernel image must be stored. | 4684 | limited amount of space in which the kernel image must be stored. |
3985 | 4685 | ||
3986 | By default, this variable is not set, which means the size of the | 4686 | By default, this variable is not set, which means the size of the |
@@ -3988,17 +4688,11 @@ system and gives an overview of their function and contents. | |||
3988 | 4688 | ||
3989 | :term:`KERNEL_IMAGE_NAME` | 4689 | :term:`KERNEL_IMAGE_NAME` |
3990 | The base name of the kernel image. This variable is set in the | 4690 | The base name of the kernel image. This variable is set in the |
3991 | ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | 4691 | ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: |
3992 | :: | ||
3993 | 4692 | ||
3994 | KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" | 4693 | KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" |
3995 | 4694 | ||
3996 | The value of the | 4695 | See :term:`KERNEL_ARTIFACT_NAME` for additional information. |
3997 | :term:`KERNEL_ARTIFACT_NAME` variable, | ||
3998 | which is set in the same file, has the following value: | ||
3999 | :: | ||
4000 | |||
4001 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | ||
4002 | 4696 | ||
4003 | :term:`KERNEL_IMAGETYPE` | 4697 | :term:`KERNEL_IMAGETYPE` |
4004 | The type of kernel to build for a device, usually set by the machine | 4698 | The type of kernel to build for a device, usually set by the machine |
@@ -4006,9 +4700,12 @@ system and gives an overview of their function and contents. | |||
4006 | when building the kernel and is passed to ``make`` as the target to | 4700 | when building the kernel and is passed to ``make`` as the target to |
4007 | build. | 4701 | build. |
4008 | 4702 | ||
4009 | If you want to build an alternate kernel image type in addition to that | 4703 | To build additional kernel image types, use :term:`KERNEL_IMAGETYPES`. |
4010 | specified by ``KERNEL_IMAGETYPE``, use the :term:`KERNEL_ALT_IMAGETYPE` | 4704 | |
4011 | variable. | 4705 | :term:`KERNEL_IMAGETYPES` |
4706 | Lists additional types of kernel images to build for a device in addition | ||
4707 | to image type specified in :term:`KERNEL_IMAGETYPE`. Usually set by the | ||
4708 | machine configuration files. | ||
4012 | 4709 | ||
4013 | :term:`KERNEL_MODULE_AUTOLOAD` | 4710 | :term:`KERNEL_MODULE_AUTOLOAD` |
4014 | Lists kernel modules that need to be auto-loaded during boot. | 4711 | Lists kernel modules that need to be auto-loaded during boot. |
@@ -4018,23 +4715,21 @@ system and gives an overview of their function and contents. | |||
4018 | This variable replaces the deprecated :term:`module_autoload` | 4715 | This variable replaces the deprecated :term:`module_autoload` |
4019 | variable. | 4716 | variable. |
4020 | 4717 | ||
4021 | You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it | 4718 | You can use the :term:`KERNEL_MODULE_AUTOLOAD` variable anywhere that it |
4022 | can be recognized by the kernel recipe or by an out-of-tree kernel | 4719 | can be recognized by the kernel recipe or by an out-of-tree kernel |
4023 | module recipe (e.g. a machine configuration file, a distribution | 4720 | module recipe (e.g. a machine configuration file, a distribution |
4024 | configuration file, an append file for the recipe, or the recipe | 4721 | configuration file, an append file for the recipe, or the recipe |
4025 | itself). | 4722 | itself). |
4026 | 4723 | ||
4027 | Specify it as follows: | 4724 | Specify it as follows:: |
4028 | :: | ||
4029 | 4725 | ||
4030 | KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" | 4726 | KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3" |
4031 | 4727 | ||
4032 | Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build | 4728 | Including :term:`KERNEL_MODULE_AUTOLOAD` causes the OpenEmbedded build |
4033 | system to populate the ``/etc/modules-load.d/modname.conf`` file with | 4729 | system to populate the ``/etc/modules-load.d/modname.conf`` file with |
4034 | the list of modules to be auto-loaded on boot. The modules appear | 4730 | the list of modules to be auto-loaded on boot. The modules appear |
4035 | one-per-line in the file. Here is an example of the most common use | 4731 | one-per-line in the file. Here is an example of the most common use |
4036 | case: | 4732 | case:: |
4037 | :: | ||
4038 | 4733 | ||
4039 | KERNEL_MODULE_AUTOLOAD += "module_name" | 4734 | KERNEL_MODULE_AUTOLOAD += "module_name" |
4040 | 4735 | ||
@@ -4048,56 +4743,65 @@ system and gives an overview of their function and contents. | |||
4048 | provide those module configurations, see the | 4743 | provide those module configurations, see the |
4049 | :term:`module_conf_* <module_conf>` variable. | 4744 | :term:`module_conf_* <module_conf>` variable. |
4050 | 4745 | ||
4746 | :term:`KERNEL_PACKAGE_NAME` | ||
4747 | Specifies the base name of the kernel packages, such as "kernel" | ||
4748 | in the kernel packages such as "kernel-modules", "kernel-image" and | ||
4749 | "kernel-dbg". | ||
4750 | |||
4751 | The default value for this variable is set to "kernel" by the | ||
4752 | :ref:`ref-classes-kernel` class. | ||
4753 | |||
4051 | :term:`KERNEL_PATH` | 4754 | :term:`KERNEL_PATH` |
4052 | The location of the kernel sources. This variable is set to the value | 4755 | The location of the kernel sources. This variable is set to the value |
4053 | of the :term:`STAGING_KERNEL_DIR` within | 4756 | of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` |
4054 | the :ref:`module <ref-classes-module>` class. For information on | 4757 | class. For information on how this variable is used, see the |
4055 | how this variable is used, see the | ||
4056 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" | 4758 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" |
4057 | section in the Yocto Project Linux Kernel Development Manual. | 4759 | section in the Yocto Project Linux Kernel Development Manual. |
4058 | 4760 | ||
4059 | To help maximize compatibility with out-of-tree drivers used to build | 4761 | To help maximize compatibility with out-of-tree drivers used to build |
4060 | modules, the OpenEmbedded build system also recognizes and uses the | 4762 | modules, the OpenEmbedded build system also recognizes and uses the |
4061 | :term:`KERNEL_SRC` variable, which is identical to | 4763 | :term:`KERNEL_SRC` variable, which is identical to |
4062 | the ``KERNEL_PATH`` variable. Both variables are common variables | 4764 | the :term:`KERNEL_PATH` variable. Both variables are common variables |
4063 | used by external Makefiles to point to the kernel source directory. | 4765 | used by external Makefiles to point to the kernel source directory. |
4064 | 4766 | ||
4065 | :term:`KERNEL_SRC` | 4767 | :term:`KERNEL_SRC` |
4066 | The location of the kernel sources. This variable is set to the value | 4768 | The location of the kernel sources. This variable is set to the value |
4067 | of the :term:`STAGING_KERNEL_DIR` within | 4769 | of the :term:`STAGING_KERNEL_DIR` within the :ref:`ref-classes-module` |
4068 | the :ref:`module <ref-classes-module>` class. For information on | 4770 | class. For information on how this variable is used, see the |
4069 | how this variable is used, see the | ||
4070 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" | 4771 | ":ref:`kernel-dev/common:incorporating out-of-tree modules`" |
4071 | section in the Yocto Project Linux Kernel Development Manual. | 4772 | section in the Yocto Project Linux Kernel Development Manual. |
4072 | 4773 | ||
4073 | To help maximize compatibility with out-of-tree drivers used to build | 4774 | To help maximize compatibility with out-of-tree drivers used to build |
4074 | modules, the OpenEmbedded build system also recognizes and uses the | 4775 | modules, the OpenEmbedded build system also recognizes and uses the |
4075 | :term:`KERNEL_PATH` variable, which is identical | 4776 | :term:`KERNEL_PATH` variable, which is identical |
4076 | to the ``KERNEL_SRC`` variable. Both variables are common variables | 4777 | to the :term:`KERNEL_SRC` variable. Both variables are common variables |
4077 | used by external Makefiles to point to the kernel source directory. | 4778 | used by external Makefiles to point to the kernel source directory. |
4078 | 4779 | ||
4780 | :term:`KERNEL_STRIP` | ||
4781 | Allows to specific which ``strip`` command to use to strip the kernel | ||
4782 | binary, typically either GNU binutils ``strip`` or ``llvm-strip``. | ||
4783 | |||
4079 | :term:`KERNEL_VERSION` | 4784 | :term:`KERNEL_VERSION` |
4080 | Specifies the version of the kernel as extracted from ``version.h`` | 4785 | Specifies the version of the kernel as extracted from ``version.h`` |
4081 | or ``utsrelease.h`` within the kernel sources. Effects of setting | 4786 | or ``utsrelease.h`` within the kernel sources. Effects of setting |
4082 | this variable do not take affect until the kernel has been | 4787 | this variable do not take effect until the kernel has been |
4083 | configured. Consequently, attempting to refer to this variable in | 4788 | configured. Consequently, attempting to refer to this variable in |
4084 | contexts prior to configuration will not work. | 4789 | contexts prior to configuration will not work. |
4085 | 4790 | ||
4086 | :term:`KERNELDEPMODDEPEND` | 4791 | :term:`KERNELDEPMODDEPEND` |
4087 | Specifies whether the data referenced through | 4792 | Specifies whether the data referenced through |
4088 | :term:`PKGDATA_DIR` is needed or not. The | 4793 | :term:`PKGDATA_DIR` is needed or not. |
4089 | ``KERNELDEPMODDEPEND`` does not control whether or not that data | 4794 | :term:`KERNELDEPMODDEPEND` does not control whether or not that data |
4090 | exists, but simply whether or not it is used. If you do not need to | 4795 | exists, but simply whether or not it is used. If you do not need to |
4091 | use the data, set the ``KERNELDEPMODDEPEND`` variable in your | 4796 | use the data, set the :term:`KERNELDEPMODDEPEND` variable in your |
4092 | ``initramfs`` recipe. Setting the variable there when the data is not | 4797 | :term:`Initramfs` recipe. Setting the variable there when the data is not |
4093 | needed avoids a potential dependency loop. | 4798 | needed avoids a potential dependency loop. |
4094 | 4799 | ||
4095 | :term:`KFEATURE_DESCRIPTION` | 4800 | :term:`KFEATURE_DESCRIPTION` |
4096 | Provides a short description of a configuration fragment. You use | 4801 | Provides a short description of a configuration fragment. You use |
4097 | this variable in the ``.scc`` file that describes a configuration | 4802 | this variable in the ``.scc`` file that describes a configuration |
4098 | fragment file. Here is the variable used in a file named ``smp.scc`` | 4803 | fragment file. Here is the variable used in a file named ``smp.scc`` |
4099 | to describe SMP being enabled: | 4804 | to describe SMP being enabled:: |
4100 | :: | ||
4101 | 4805 | ||
4102 | define KFEATURE_DESCRIPTION "Enable SMP" | 4806 | define KFEATURE_DESCRIPTION "Enable SMP" |
4103 | 4807 | ||
@@ -4108,23 +4812,22 @@ system and gives an overview of their function and contents. | |||
4108 | OpenEmbedded build system understands as ``core2-32-intel-common`` | 4812 | OpenEmbedded build system understands as ``core2-32-intel-common`` |
4109 | goes by a different name in the Linux Yocto kernel. The kernel | 4813 | goes by a different name in the Linux Yocto kernel. The kernel |
4110 | understands that machine as ``intel-core2-32``. For cases like these, | 4814 | understands that machine as ``intel-core2-32``. For cases like these, |
4111 | the ``KMACHINE`` variable maps the kernel machine name to the | 4815 | the :term:`KMACHINE` variable maps the kernel machine name to the |
4112 | OpenEmbedded build system machine name. | 4816 | OpenEmbedded build system machine name. |
4113 | 4817 | ||
4114 | These mappings between different names occur in the Yocto Linux | 4818 | These mappings between different names occur in the Yocto Linux |
4115 | Kernel's ``meta`` branch. As an example take a look in the | 4819 | Kernel's ``meta`` branch. As an example take a look in the |
4116 | ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: | 4820 | ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:: |
4117 | :: | 4821 | |
4118 | 4822 | LINUX_VERSION:core2-32-intel-common = "3.19.0" | |
4119 | LINUX_VERSION_core2-32-intel-common = "3.19.0" | 4823 | COMPATIBLE_MACHINE:core2-32-intel-common = "${MACHINE}" |
4120 | COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" | 4824 | SRCREV_meta:core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" |
4121 | SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974" | 4825 | SRCREV_machine:core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" |
4122 | SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711" | 4826 | KMACHINE:core2-32-intel-common = "intel-core2-32" |
4123 | KMACHINE_core2-32-intel-common = "intel-core2-32" | 4827 | KBRANCH:core2-32-intel-common = "standard/base" |
4124 | KBRANCH_core2-32-intel-common = "standard/base" | 4828 | KERNEL_FEATURES:append:core2-32-intel-common = " ${KERNEL_FEATURES_INTEL_COMMON}" |
4125 | KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}" | 4829 | |
4126 | 4830 | The :term:`KMACHINE` statement says | |
4127 | The ``KMACHINE`` statement says | ||
4128 | that the kernel understands the machine name as "intel-core2-32". | 4831 | that the kernel understands the machine name as "intel-core2-32". |
4129 | However, the OpenEmbedded build system understands the machine as | 4832 | However, the OpenEmbedded build system understands the machine as |
4130 | "core2-32-intel-common". | 4833 | "core2-32-intel-common". |
@@ -4137,7 +4840,7 @@ system and gives an overview of their function and contents. | |||
4137 | Yocto Project Linux Kernel Development Manual for more information on | 4840 | Yocto Project Linux Kernel Development Manual for more information on |
4138 | kernel types. | 4841 | kernel types. |
4139 | 4842 | ||
4140 | You define the ``KTYPE`` variable in the | 4843 | You define the :term:`KTYPE` variable in the |
4141 | :ref:`kernel-dev/advanced:bsp descriptions`. The | 4844 | :ref:`kernel-dev/advanced:bsp descriptions`. The |
4142 | value you use must match the value used for the | 4845 | value you use must match the value used for the |
4143 | :term:`LINUX_KERNEL_TYPE` value used by the | 4846 | :term:`LINUX_KERNEL_TYPE` value used by the |
@@ -4146,14 +4849,13 @@ system and gives an overview of their function and contents. | |||
4146 | :term:`LABELS` | 4849 | :term:`LABELS` |
4147 | Provides a list of targets for automatic configuration. | 4850 | Provides a list of targets for automatic configuration. |
4148 | 4851 | ||
4149 | See the :ref:`grub-efi <ref-classes-grub-efi>` class for more | 4852 | See the :ref:`ref-classes-grub-efi` class for more |
4150 | information on how this variable is used. | 4853 | information on how this variable is used. |
4151 | 4854 | ||
4152 | :term:`LAYERDEPENDS` | 4855 | :term:`LAYERDEPENDS` |
4153 | Lists the layers, separated by spaces, on which this recipe depends. | 4856 | Lists the layers, separated by spaces, on which this recipe depends. |
4154 | Optionally, you can specify a specific layer version for a dependency | 4857 | Optionally, you can specify a specific layer version for a dependency |
4155 | by adding it to the end of the layer name. Here is an example: | 4858 | by adding it to the end of the layer name. Here is an example:: |
4156 | :: | ||
4157 | 4859 | ||
4158 | LAYERDEPENDS_mylayer = "anotherlayer (=3)" | 4860 | LAYERDEPENDS_mylayer = "anotherlayer (=3)" |
4159 | 4861 | ||
@@ -4172,14 +4874,16 @@ system and gives an overview of their function and contents. | |||
4172 | available outside of ``layer.conf`` and references are expanded | 4874 | available outside of ``layer.conf`` and references are expanded |
4173 | immediately when parsing of the file completes. | 4875 | immediately when parsing of the file completes. |
4174 | 4876 | ||
4877 | :term:`LAYERDIR_RE` | ||
4878 | See :term:`bitbake:LAYERDIR_RE` in the BitBake manual. | ||
4879 | |||
4175 | :term:`LAYERRECOMMENDS` | 4880 | :term:`LAYERRECOMMENDS` |
4176 | Lists the layers, separated by spaces, recommended for use with this | 4881 | Lists the layers, separated by spaces, recommended for use with this |
4177 | layer. | 4882 | layer. |
4178 | 4883 | ||
4179 | Optionally, you can specify a specific layer version for a | 4884 | Optionally, you can specify a specific layer version for a |
4180 | recommendation by adding the version to the end of the layer name. | 4885 | recommendation by adding the version to the end of the layer name. |
4181 | Here is an example: | 4886 | Here is an example:: |
4182 | :: | ||
4183 | 4887 | ||
4184 | LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" | 4888 | LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" |
4185 | 4889 | ||
@@ -4191,32 +4895,7 @@ system and gives an overview of their function and contents. | |||
4191 | ``LAYERRECOMMENDS_mylayer``). | 4895 | ``LAYERRECOMMENDS_mylayer``). |
4192 | 4896 | ||
4193 | :term:`LAYERSERIES_COMPAT` | 4897 | :term:`LAYERSERIES_COMPAT` |
4194 | Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which | 4898 | See :term:`bitbake:LAYERSERIES_COMPAT` in the BitBake manual. |
4195 | a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable | ||
4196 | allows the layer maintainer to indicate which combinations of the | ||
4197 | layer and OE-Core can be expected to work. The variable gives the | ||
4198 | system a way to detect when a layer has not been tested with new | ||
4199 | releases of OE-Core (e.g. the layer is not maintained). | ||
4200 | |||
4201 | To specify the OE-Core versions for which a layer is compatible, use | ||
4202 | this variable in your layer's ``conf/layer.conf`` configuration file. | ||
4203 | For the list, use the Yocto Project | ||
4204 | :yocto_wiki:`Release Name </Releases>` (e.g. | ||
4205 | &DISTRO_NAME_NO_CAP;). To specify multiple OE-Core versions for the | ||
4206 | layer, use a space-separated list: | ||
4207 | :: | ||
4208 | |||
4209 | LAYERSERIES_COMPAT_layer_root_name = "&DISTRO_NAME_NO_CAP; &DISTRO_NAME_NO_CAP_MINUS_ONE;" | ||
4210 | |||
4211 | .. note:: | ||
4212 | |||
4213 | Setting ``LAYERSERIES_COMPAT`` is required by the Yocto Project | ||
4214 | Compatible version 2 standard. | ||
4215 | The OpenEmbedded build system produces a warning if the variable | ||
4216 | is not set for any given layer. | ||
4217 | |||
4218 | See the ":ref:`dev-manual/common-tasks:creating your own layer`" | ||
4219 | section in the Yocto Project Development Tasks Manual. | ||
4220 | 4899 | ||
4221 | :term:`LAYERVERSION` | 4900 | :term:`LAYERVERSION` |
4222 | Optionally specifies the version of a layer as a single number. You | 4901 | Optionally specifies the version of a layer as a single number. You |
@@ -4234,7 +4913,7 @@ system and gives an overview of their function and contents. | |||
4234 | to an environment variable and thus made visible to the software | 4913 | to an environment variable and thus made visible to the software |
4235 | being built during the compilation step. | 4914 | being built during the compilation step. |
4236 | 4915 | ||
4237 | Default initialization for ``LDFLAGS`` varies depending on what is | 4916 | Default initialization for :term:`LDFLAGS` varies depending on what is |
4238 | being built: | 4917 | being built: |
4239 | 4918 | ||
4240 | - :term:`TARGET_LDFLAGS` when building for the | 4919 | - :term:`TARGET_LDFLAGS` when building for the |
@@ -4248,10 +4927,11 @@ system and gives an overview of their function and contents. | |||
4248 | 4927 | ||
4249 | :term:`LEAD_SONAME` | 4928 | :term:`LEAD_SONAME` |
4250 | Specifies the lead (or primary) compiled library file (i.e. ``.so``) | 4929 | Specifies the lead (or primary) compiled library file (i.e. ``.so``) |
4251 | that the :ref:`debian <ref-classes-debian>` class applies its | 4930 | that the :ref:`ref-classes-debian` class applies its |
4252 | naming policy to given a recipe that packages multiple libraries. | 4931 | naming policy to given a recipe that packages multiple libraries. |
4253 | 4932 | ||
4254 | This variable works in conjunction with the ``debian`` class. | 4933 | This variable works in conjunction with the :ref:`ref-classes-debian` |
4934 | class. | ||
4255 | 4935 | ||
4256 | :term:`LIC_FILES_CHKSUM` | 4936 | :term:`LIC_FILES_CHKSUM` |
4257 | Checksums of the license text in the recipe source code. | 4937 | Checksums of the license text in the recipe source code. |
@@ -4264,7 +4944,7 @@ system and gives an overview of their function and contents. | |||
4264 | This variable must be defined for all recipes (unless | 4944 | This variable must be defined for all recipes (unless |
4265 | :term:`LICENSE` is set to "CLOSED"). | 4945 | :term:`LICENSE` is set to "CLOSED"). |
4266 | 4946 | ||
4267 | For more information, see the ":ref:`dev-manual/common-tasks:tracking license changes`" | 4947 | For more information, see the ":ref:`dev-manual/licenses:tracking license changes`" |
4268 | section in the Yocto Project Development Tasks Manual. | 4948 | section in the Yocto Project Development Tasks Manual. |
4269 | 4949 | ||
4270 | :term:`LICENSE` | 4950 | :term:`LICENSE` |
@@ -4275,8 +4955,8 @@ system and gives an overview of their function and contents. | |||
4275 | - Separate license names using \| (pipe) when there is a choice | 4955 | - Separate license names using \| (pipe) when there is a choice |
4276 | between licenses. | 4956 | between licenses. |
4277 | 4957 | ||
4278 | - Separate license names using & (ampersand) when multiple licenses | 4958 | - Separate license names using & (ampersand) when there are |
4279 | exist that cover different parts of the source. | 4959 | multiple licenses for different parts of the source. |
4280 | 4960 | ||
4281 | - You can use spaces between license names. | 4961 | - You can use spaces between license names. |
4282 | 4962 | ||
@@ -4285,12 +4965,11 @@ system and gives an overview of their function and contents. | |||
4285 | :term:`SPDXLICENSEMAP` flag names defined in | 4965 | :term:`SPDXLICENSEMAP` flag names defined in |
4286 | ``meta/conf/licenses.conf``. | 4966 | ``meta/conf/licenses.conf``. |
4287 | 4967 | ||
4288 | Here are some examples: | 4968 | Here are some examples:: |
4289 | :: | ||
4290 | 4969 | ||
4291 | LICENSE = "LGPLv2.1 | GPLv3" | 4970 | LICENSE = "LGPL-2.1-only | GPL-3.0-only" |
4292 | LICENSE = "MPL-1 & LGPLv2.1" | 4971 | LICENSE = "MPL-1.0 & LGPL-2.1-only" |
4293 | LICENSE = "GPLv2+" | 4972 | LICENSE = "GPL-2.0-or-later" |
4294 | 4973 | ||
4295 | The first example is from the | 4974 | The first example is from the |
4296 | recipes for Qt, which the user may choose to distribute under either | 4975 | recipes for Qt, which the user may choose to distribute under either |
@@ -4303,19 +4982,18 @@ system and gives an overview of their function and contents. | |||
4303 | situations where components of the output have different licenses. | 4982 | situations where components of the output have different licenses. |
4304 | For example, a piece of software whose code is licensed under GPLv2 | 4983 | For example, a piece of software whose code is licensed under GPLv2 |
4305 | but has accompanying documentation licensed under the GNU Free | 4984 | but has accompanying documentation licensed under the GNU Free |
4306 | Documentation License 1.2 could be specified as follows: | 4985 | Documentation License 1.2 could be specified as follows:: |
4307 | :: | ||
4308 | 4986 | ||
4309 | LICENSE = "GFDL-1.2 & GPLv2" | 4987 | LICENSE = "GFDL-1.2 & GPL-2.0-only" |
4310 | LICENSE_${PN} = "GPLv2" | 4988 | LICENSE:${PN} = "GPL-2.0.only" |
4311 | LICENSE_${PN}-doc = "GFDL-1.2" | 4989 | LICENSE:${PN}-doc = "GFDL-1.2" |
4312 | 4990 | ||
4313 | :term:`LICENSE_CREATE_PACKAGE` | 4991 | :term:`LICENSE_CREATE_PACKAGE` |
4314 | Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded | 4992 | Setting :term:`LICENSE_CREATE_PACKAGE` to "1" causes the OpenEmbedded |
4315 | build system to create an extra package (i.e. | 4993 | build system to create an extra package (i.e. |
4316 | ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add | 4994 | ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add |
4317 | those packages to the | 4995 | those packages to the |
4318 | :term:`RRECOMMENDS`\ ``_${PN}``. | 4996 | :term:`RRECOMMENDS`\ ``:${PN}``. |
4319 | 4997 | ||
4320 | The ``${PN}-lic`` package installs a directory in | 4998 | The ``${PN}-lic`` package installs a directory in |
4321 | ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base | 4999 | ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base |
@@ -4330,37 +5008,52 @@ system and gives an overview of their function and contents. | |||
4330 | For related information on providing license text, see the | 5008 | For related information on providing license text, see the |
4331 | :term:`COPY_LIC_DIRS` variable, the | 5009 | :term:`COPY_LIC_DIRS` variable, the |
4332 | :term:`COPY_LIC_MANIFEST` variable, and the | 5010 | :term:`COPY_LIC_MANIFEST` variable, and the |
4333 | ":ref:`dev-manual/common-tasks:providing license text`" | 5011 | ":ref:`dev-manual/licenses:providing license text`" |
4334 | section in the Yocto Project Development Tasks Manual. | 5012 | section in the Yocto Project Development Tasks Manual. |
4335 | 5013 | ||
4336 | :term:`LICENSE_FLAGS` | 5014 | :term:`LICENSE_FLAGS` |
4337 | Specifies additional flags for a recipe you must whitelist through | 5015 | Specifies additional flags for a recipe you must allow through |
4338 | :term:`LICENSE_FLAGS_WHITELIST` in | 5016 | :term:`LICENSE_FLAGS_ACCEPTED` in |
4339 | order to allow the recipe to be built. When providing multiple flags, | 5017 | order for the recipe to be built. When providing multiple flags, |
4340 | separate them with spaces. | 5018 | separate them with spaces. |
4341 | 5019 | ||
4342 | This value is independent of :term:`LICENSE` and is | 5020 | This value is independent of :term:`LICENSE` and is |
4343 | typically used to mark recipes that might require additional licenses | 5021 | typically used to mark recipes that might require additional licenses |
4344 | in order to be used in a commercial product. For more information, | 5022 | in order to be used in a commercial product. For more information, |
4345 | see the | 5023 | see the |
4346 | ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" | 5024 | ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" |
4347 | section in the Yocto Project Development Tasks Manual. | 5025 | section in the Yocto Project Development Tasks Manual. |
4348 | 5026 | ||
4349 | :term:`LICENSE_FLAGS_WHITELIST` | 5027 | :term:`LICENSE_FLAGS_ACCEPTED` |
4350 | Lists license flags that when specified in | 5028 | Lists license flags that when specified in |
4351 | :term:`LICENSE_FLAGS` within a recipe should not | 5029 | :term:`LICENSE_FLAGS` within a recipe should not |
4352 | prevent that recipe from being built. This practice is otherwise | 5030 | prevent that recipe from being built. For more information, see the |
4353 | known as "whitelisting" license flags. For more information, see the | 5031 | ":ref:`dev-manual/licenses:enabling commercially licensed recipes`" |
4354 | ":ref:`dev-manual/common-tasks:enabling commercially licensed recipes`" | ||
4355 | section in the Yocto Project Development Tasks Manual. | 5032 | section in the Yocto Project Development Tasks Manual. |
4356 | 5033 | ||
5034 | :term:`LICENSE_FLAGS_DETAILS` | ||
5035 | Adds details about a flag in :term:`LICENSE_FLAGS`. This way, | ||
5036 | if such a flag is not accepted through :term:`LICENSE_FLAGS_ACCEPTED`, | ||
5037 | the error message will be more informative, containing the specified | ||
5038 | extra details. | ||
5039 | |||
5040 | For example, a recipe with an EULA may set:: | ||
5041 | |||
5042 | LICENSE_FLAGS = "FooBar-EULA" | ||
5043 | LICENSE_FLAGS_DETAILS[FooBar-EULA] = "For further details, see https://example.com/eula." | ||
5044 | |||
5045 | If ``Foobar-EULA`` isn't in :term:`LICENSE_FLAGS_ACCEPTED`, the | ||
5046 | error message is more useful:: | ||
5047 | |||
5048 | Has a restricted license 'FooBar-EULA' which is not listed in your LICENSE_FLAGS_ACCEPTED. | ||
5049 | For further details, see https://example.com/eula. | ||
5050 | |||
4357 | :term:`LICENSE_PATH` | 5051 | :term:`LICENSE_PATH` |
4358 | Path to additional licenses used during the build. By default, the | 5052 | Path to additional licenses used during the build. By default, the |
4359 | OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the | 5053 | OpenEmbedded build system uses :term:`COMMON_LICENSE_DIR` to define the |
4360 | directory that holds common license text used during the build. The | 5054 | directory that holds common license text used during the build. The |
4361 | ``LICENSE_PATH`` variable allows you to extend that location to other | 5055 | :term:`LICENSE_PATH` variable allows you to extend that location to other |
4362 | areas that have additional licenses: | 5056 | areas that have additional licenses:: |
4363 | :: | ||
4364 | 5057 | ||
4365 | LICENSE_PATH += "path-to-additional-common-licenses" | 5058 | LICENSE_PATH += "path-to-additional-common-licenses" |
4366 | 5059 | ||
@@ -4372,9 +5065,9 @@ system and gives an overview of their function and contents. | |||
4372 | Yocto Project Linux Kernel Development Manual for more information on | 5065 | Yocto Project Linux Kernel Development Manual for more information on |
4373 | kernel types. | 5066 | kernel types. |
4374 | 5067 | ||
4375 | If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to | 5068 | If you do not specify a :term:`LINUX_KERNEL_TYPE`, it defaults to |
4376 | "standard". Together with :term:`KMACHINE`, the | 5069 | "standard". Together with :term:`KMACHINE`, the |
4377 | ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by | 5070 | :term:`LINUX_KERNEL_TYPE` variable defines the search arguments used by |
4378 | the kernel tools to find the appropriate description within the | 5071 | the kernel tools to find the appropriate description within the |
4379 | kernel :term:`Metadata` with which to build out the sources | 5072 | kernel :term:`Metadata` with which to build out the sources |
4380 | and configuration. | 5073 | and configuration. |
@@ -4384,14 +5077,12 @@ system and gives an overview of their function and contents. | |||
4384 | being built using the OpenEmbedded build system is based. You define | 5077 | being built using the OpenEmbedded build system is based. You define |
4385 | this variable in the kernel recipe. For example, the | 5078 | this variable in the kernel recipe. For example, the |
4386 | ``linux-yocto-3.4.bb`` kernel recipe found in | 5079 | ``linux-yocto-3.4.bb`` kernel recipe found in |
4387 | ``meta/recipes-kernel/linux`` defines the variables as follows: | 5080 | ``meta/recipes-kernel/linux`` defines the variables as follows:: |
4388 | :: | ||
4389 | 5081 | ||
4390 | LINUX_VERSION ?= "3.4.24" | 5082 | LINUX_VERSION ?= "3.4.24" |
4391 | 5083 | ||
4392 | The ``LINUX_VERSION`` variable is used to define :term:`PV` | 5084 | The :term:`LINUX_VERSION` variable is used to define :term:`PV` |
4393 | for the recipe: | 5085 | for the recipe:: |
4394 | :: | ||
4395 | 5086 | ||
4396 | PV = "${LINUX_VERSION}+git${SRCPV}" | 5087 | PV = "${LINUX_VERSION}+git${SRCPV}" |
4397 | 5088 | ||
@@ -4399,16 +5090,14 @@ system and gives an overview of their function and contents. | |||
4399 | A string extension compiled into the version string of the Linux | 5090 | A string extension compiled into the version string of the Linux |
4400 | kernel built with the OpenEmbedded build system. You define this | 5091 | kernel built with the OpenEmbedded build system. You define this |
4401 | variable in the kernel recipe. For example, the linux-yocto kernel | 5092 | variable in the kernel recipe. For example, the linux-yocto kernel |
4402 | recipes all define the variable as follows: | 5093 | recipes all define the variable as follows:: |
4403 | :: | ||
4404 | 5094 | ||
4405 | LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" | 5095 | LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}" |
4406 | 5096 | ||
4407 | Defining this variable essentially sets the Linux kernel | 5097 | Defining this variable essentially sets the Linux kernel |
4408 | configuration item ``CONFIG_LOCALVERSION``, which is visible through | 5098 | configuration item ``CONFIG_LOCALVERSION``, which is visible through |
4409 | the ``uname`` command. Here is an example that shows the extension | 5099 | the ``uname`` command. Here is an example that shows the extension |
4410 | assuming it was set as previously shown: | 5100 | assuming it was set as previously shown:: |
4411 | :: | ||
4412 | 5101 | ||
4413 | $ uname -r | 5102 | $ uname -r |
4414 | 3.7.0-rc8-custom | 5103 | 3.7.0-rc8-custom |
@@ -4422,24 +5111,22 @@ system and gives an overview of their function and contents. | |||
4422 | 5111 | ||
4423 | :term:`MACHINE` | 5112 | :term:`MACHINE` |
4424 | Specifies the target device for which the image is built. You define | 5113 | Specifies the target device for which the image is built. You define |
4425 | ``MACHINE`` in the ``local.conf`` file found in the | 5114 | :term:`MACHINE` in the ``local.conf`` file found in the |
4426 | :term:`Build Directory`. By default, ``MACHINE`` is set to | 5115 | :term:`Build Directory`. By default, :term:`MACHINE` is set to |
4427 | "qemux86", which is an x86-based architecture machine to be emulated | 5116 | "qemux86", which is an x86-based architecture machine to be emulated |
4428 | using QEMU: | 5117 | using QEMU:: |
4429 | :: | ||
4430 | 5118 | ||
4431 | MACHINE ?= "qemux86" | 5119 | MACHINE ?= "qemux86" |
4432 | 5120 | ||
4433 | The variable corresponds to a machine configuration file of the same | 5121 | The variable corresponds to a machine configuration file of the same |
4434 | name, through which machine-specific configurations are set. Thus, | 5122 | name, through which machine-specific configurations are set. Thus, |
4435 | when ``MACHINE`` is set to "qemux86" there exists the corresponding | 5123 | when :term:`MACHINE` is set to "qemux86", the corresponding |
4436 | ``qemux86.conf`` machine configuration file, which can be found in | 5124 | ``qemux86.conf`` machine configuration file can be found in |
4437 | the :term:`Source Directory` in | 5125 | the :term:`Source Directory` in |
4438 | ``meta/conf/machine``. | 5126 | ``meta/conf/machine``. |
4439 | 5127 | ||
4440 | The list of machines supported by the Yocto Project as shipped | 5128 | The list of machines supported by the Yocto Project as shipped |
4441 | include the following: | 5129 | include the following:: |
4442 | :: | ||
4443 | 5130 | ||
4444 | MACHINE ?= "qemuarm" | 5131 | MACHINE ?= "qemuarm" |
4445 | MACHINE ?= "qemuarm64" | 5132 | MACHINE ?= "qemuarm64" |
@@ -4451,7 +5138,6 @@ system and gives an overview of their function and contents. | |||
4451 | MACHINE ?= "genericx86" | 5138 | MACHINE ?= "genericx86" |
4452 | MACHINE ?= "genericx86-64" | 5139 | MACHINE ?= "genericx86-64" |
4453 | MACHINE ?= "beaglebone" | 5140 | MACHINE ?= "beaglebone" |
4454 | MACHINE ?= "edgerouter" | ||
4455 | 5141 | ||
4456 | The last five are Yocto Project reference hardware | 5142 | The last five are Yocto Project reference hardware |
4457 | boards, which are provided in the ``meta-yocto-bsp`` layer. | 5143 | boards, which are provided in the ``meta-yocto-bsp`` layer. |
@@ -4459,13 +5145,13 @@ system and gives an overview of their function and contents. | |||
4459 | .. note:: | 5145 | .. note:: |
4460 | 5146 | ||
4461 | Adding additional Board Support Package (BSP) layers to your | 5147 | Adding additional Board Support Package (BSP) layers to your |
4462 | configuration adds new possible settings for ``MACHINE``. | 5148 | configuration adds new possible settings for :term:`MACHINE`. |
4463 | 5149 | ||
4464 | :term:`MACHINE_ARCH` | 5150 | :term:`MACHINE_ARCH` |
4465 | Specifies the name of the machine-specific architecture. This | 5151 | Specifies the name of the machine-specific architecture. This |
4466 | variable is set automatically from :term:`MACHINE` or | 5152 | variable is set automatically from :term:`MACHINE` or |
4467 | :term:`TUNE_PKGARCH`. You should not hand-edit | 5153 | :term:`TUNE_PKGARCH`. You should not hand-edit |
4468 | the ``MACHINE_ARCH`` variable. | 5154 | the :term:`MACHINE_ARCH` variable. |
4469 | 5155 | ||
4470 | :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` | 5156 | :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` |
4471 | A list of required machine-specific packages to install as part of | 5157 | A list of required machine-specific packages to install as part of |
@@ -4477,7 +5163,7 @@ system and gives an overview of their function and contents. | |||
4477 | image. | 5163 | image. |
4478 | 5164 | ||
4479 | This variable is similar to the | 5165 | This variable is similar to the |
4480 | ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception | 5166 | :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS` variable with the exception |
4481 | that the image being built has a build dependency on the variable's | 5167 | that the image being built has a build dependency on the variable's |
4482 | list of packages. In other words, the image will not build if a file | 5168 | list of packages. In other words, the image will not build if a file |
4483 | in this list is not found. | 5169 | in this list is not found. |
@@ -4485,8 +5171,7 @@ system and gives an overview of their function and contents. | |||
4485 | As an example, suppose the machine for which you are building | 5171 | As an example, suppose the machine for which you are building |
4486 | requires ``example-init`` to be run during boot to initialize the | 5172 | requires ``example-init`` to be run during boot to initialize the |
4487 | hardware. In this case, you would use the following in the machine's | 5173 | hardware. In this case, you would use the following in the machine's |
4488 | ``.conf`` configuration file: | 5174 | ``.conf`` configuration file:: |
4489 | :: | ||
4490 | 5175 | ||
4491 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" | 5176 | MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init" |
4492 | 5177 | ||
@@ -4499,7 +5184,7 @@ system and gives an overview of their function and contents. | |||
4499 | on ``packagegroup-core-boot``, including the ``core-image-minimal`` | 5184 | on ``packagegroup-core-boot``, including the ``core-image-minimal`` |
4500 | image. | 5185 | image. |
4501 | 5186 | ||
4502 | This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` | 5187 | This variable is similar to the :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS` |
4503 | variable with the exception that the image being built does not have | 5188 | variable with the exception that the image being built does not have |
4504 | a build dependency on the variable's list of packages. In other | 5189 | a build dependency on the variable's list of packages. In other |
4505 | words, the image will still build if a package in this list is not | 5190 | words, the image will still build if a package in this list is not |
@@ -4517,8 +5202,7 @@ system and gives an overview of their function and contents. | |||
4517 | "recommends" relationship so that in the latter case, the build will | 5202 | "recommends" relationship so that in the latter case, the build will |
4518 | not fail due to the missing package. To accomplish this, assuming the | 5203 | not fail due to the missing package. To accomplish this, assuming the |
4519 | package for the module was called ``kernel-module-ab123``, you would | 5204 | package for the module was called ``kernel-module-ab123``, you would |
4520 | use the following in the machine's ``.conf`` configuration file: | 5205 | use the following in the machine's ``.conf`` configuration file:: |
4521 | :: | ||
4522 | 5206 | ||
4523 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" | 5207 | MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" |
4524 | 5208 | ||
@@ -4542,7 +5226,7 @@ system and gives an overview of their function and contents. | |||
4542 | which does not include the ``core-image-minimal`` or | 5226 | which does not include the ``core-image-minimal`` or |
4543 | ``core-image-full-cmdline`` images. | 5227 | ``core-image-full-cmdline`` images. |
4544 | 5228 | ||
4545 | The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable | 5229 | The variable is similar to the :term:`MACHINE_EXTRA_RRECOMMENDS` variable |
4546 | with the exception that the image being built has a build dependency | 5230 | with the exception that the image being built has a build dependency |
4547 | on the variable's list of packages. In other words, the image will | 5231 | on the variable's list of packages. In other words, the image will |
4548 | not build if a file in this list is not found. | 5232 | not build if a file in this list is not found. |
@@ -4554,8 +5238,7 @@ system and gives an overview of their function and contents. | |||
4554 | exist, so it is acceptable for the build process to depend upon | 5238 | exist, so it is acceptable for the build process to depend upon |
4555 | finding the package. In this case, assuming the package for the | 5239 | finding the package. In this case, assuming the package for the |
4556 | firmware was called ``wifidriver-firmware``, you would use the | 5240 | firmware was called ``wifidriver-firmware``, you would use the |
4557 | following in the ``.conf`` file for the machine: | 5241 | following in the ``.conf`` file for the machine:: |
4558 | :: | ||
4559 | 5242 | ||
4560 | MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" | 5243 | MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" |
4561 | 5244 | ||
@@ -4568,7 +5251,7 @@ system and gives an overview of their function and contents. | |||
4568 | which does not include the ``core-image-minimal`` or | 5251 | which does not include the ``core-image-minimal`` or |
4569 | ``core-image-full-cmdline`` images. | 5252 | ``core-image-full-cmdline`` images. |
4570 | 5253 | ||
4571 | This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable | 5254 | This variable is similar to the :term:`MACHINE_EXTRA_RDEPENDS` variable |
4572 | with the exception that the image being built does not have a build | 5255 | with the exception that the image being built does not have a build |
4573 | dependency on the variable's list of packages. In other words, the | 5256 | dependency on the variable's list of packages. In other words, the |
4574 | image will build if a file in this list is not found. | 5257 | image will build if a file in this list is not found. |
@@ -4581,8 +5264,7 @@ system and gives an overview of their function and contents. | |||
4581 | the build to succeed instead of failing as a result of the package | 5264 | the build to succeed instead of failing as a result of the package |
4582 | not being found. To accomplish this, assuming the package for the | 5265 | not being found. To accomplish this, assuming the package for the |
4583 | module was called ``kernel-module-examplewifi``, you would use the | 5266 | module was called ``kernel-module-examplewifi``, you would use the |
4584 | following in the ``.conf`` file for the machine: | 5267 | following in the ``.conf`` file for the machine:: |
4585 | :: | ||
4586 | 5268 | ||
4587 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" | 5269 | MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" |
4588 | 5270 | ||
@@ -4598,112 +5280,144 @@ system and gives an overview of their function and contents. | |||
4598 | shipped, see the ":ref:`ref-features-machine`" section. | 5280 | shipped, see the ":ref:`ref-features-machine`" section. |
4599 | 5281 | ||
4600 | :term:`MACHINE_FEATURES_BACKFILL` | 5282 | :term:`MACHINE_FEATURES_BACKFILL` |
4601 | Features to be added to ``MACHINE_FEATURES`` if not also present in | 5283 | A list of space-separated features to be added to |
4602 | ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. | 5284 | :term:`MACHINE_FEATURES` if not also present in |
5285 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED`. | ||
4603 | 5286 | ||
4604 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is | 5287 | This variable is set in the ``meta/conf/bitbake.conf`` file. It is not |
4605 | not intended to be user-configurable. It is best to just reference | 5288 | intended to be user-configurable. It is best to just reference the |
4606 | the variable to see which machine features are being backfilled for | 5289 | variable to see which machine features are being |
4607 | all machine configurations. See the ":ref:`ref-features-backfill`" | 5290 | :ref:`backfilled <ref-features-backfill>` for all machine configurations. |
4608 | section for more information. | ||
4609 | 5291 | ||
4610 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` | 5292 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` |
4611 | Features from ``MACHINE_FEATURES_BACKFILL`` that should not be | 5293 | A list of space-separated features from :term:`MACHINE_FEATURES_BACKFILL` |
4612 | backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See | 5294 | that should not be :ref:`backfilled <ref-features-backfill>` (i.e. added |
4613 | the ":ref:`ref-features-backfill`" section for more information. | 5295 | to :term:`MACHINE_FEATURES`) during the build. |
5296 | |||
5297 | This corresponds to an opt-out mechanism. When new default machine | ||
5298 | features are introduced, machine definition maintainers can review | ||
5299 | (`consider`) them and decide to exclude them from the | ||
5300 | :ref:`backfilled <ref-features-backfill>` features. Therefore, the | ||
5301 | combination of :term:`MACHINE_FEATURES_BACKFILL` and | ||
5302 | :term:`MACHINE_FEATURES_BACKFILL_CONSIDERED` makes it possible to | ||
5303 | add new default features without breaking existing machine definitions. | ||
4614 | 5304 | ||
4615 | :term:`MACHINEOVERRIDES` | 5305 | :term:`MACHINEOVERRIDES` |
4616 | A colon-separated list of overrides that apply to the current | 5306 | A colon-separated list of overrides that apply to the current |
4617 | machine. By default, this list includes the value of | 5307 | machine. By default, this list includes the value of |
4618 | :term:`MACHINE`. | 5308 | :term:`MACHINE`. |
4619 | 5309 | ||
4620 | You can extend ``MACHINEOVERRIDES`` to add extra overrides that | 5310 | You can extend :term:`MACHINEOVERRIDES` to add extra overrides that |
4621 | should apply to a machine. For example, all machines emulated in QEMU | 5311 | should apply to a machine. For example, all machines emulated in QEMU |
4622 | (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named | 5312 | (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named |
4623 | ``meta/conf/machine/include/qemu.inc`` that prepends the following | 5313 | ``meta/conf/machine/include/qemu.inc`` that prepends the following |
4624 | override to ``MACHINEOVERRIDES``: | 5314 | override to :term:`MACHINEOVERRIDES`:: |
4625 | :: | ||
4626 | 5315 | ||
4627 | MACHINEOVERRIDES =. "qemuall:" | 5316 | MACHINEOVERRIDES =. "qemuall:" |
4628 | 5317 | ||
4629 | This | 5318 | This |
4630 | override allows variables to be overridden for all machines emulated | 5319 | override allows variables to be overridden for all machines emulated |
4631 | in QEMU, like in the following example from the ``connman-conf`` | 5320 | in QEMU, like in the following example from the ``connman-conf`` |
4632 | recipe: | 5321 | recipe:: |
4633 | :: | ||
4634 | 5322 | ||
4635 | SRC_URI_append_qemuall = " file://wired.config \ | 5323 | SRC_URI:append:qemuall = " file://wired.config \ |
4636 | file://wired-setup \ | 5324 | file://wired-setup \ |
4637 | " | 5325 | " |
4638 | 5326 | ||
4639 | The underlying mechanism behind | 5327 | The underlying mechanism behind |
4640 | ``MACHINEOVERRIDES`` is simply that it is included in the default | 5328 | :term:`MACHINEOVERRIDES` is simply that it is included in the default |
4641 | value of :term:`OVERRIDES`. | 5329 | value of :term:`OVERRIDES`. |
4642 | 5330 | ||
4643 | :term:`MAINTAINER` | 5331 | :term:`MAINTAINER` |
4644 | The email address of the distribution maintainer. | 5332 | The email address of the distribution maintainer. |
4645 | 5333 | ||
5334 | :term:`MESON_BUILDTYPE` | ||
5335 | Value of the Meson ``--buildtype`` argument used by the | ||
5336 | :ref:`ref-classes-meson` class. It defaults to ``debug`` if | ||
5337 | :term:`DEBUG_BUILD` is set to "1", and ``plain`` otherwise. | ||
5338 | |||
5339 | See `Meson build options <https://mesonbuild.com/Builtin-options.html>`__ | ||
5340 | for the values you could set in a recipe. Values such as ``plain``, | ||
5341 | ``debug``, ``debugoptimized``, ``release`` and ``minsize`` allow | ||
5342 | you to specify the inclusion of debugging symbols and the compiler | ||
5343 | optimizations (none, performance or size). | ||
5344 | |||
5345 | :term:`MESON_TARGET` | ||
5346 | A variable for the :ref:`ref-classes-meson` class, allowing to choose | ||
5347 | a Meson target to build in :ref:`ref-tasks-compile`. Otherwise, the | ||
5348 | default targets are built. | ||
5349 | |||
5350 | :term:`METADATA_BRANCH` | ||
5351 | The branch currently checked out for the OpenEmbedded-Core layer (path | ||
5352 | determined by :term:`COREBASE`). | ||
5353 | |||
5354 | :term:`METADATA_REVISION` | ||
5355 | The revision currently checked out for the OpenEmbedded-Core layer (path | ||
5356 | determined by :term:`COREBASE`). | ||
5357 | |||
5358 | :term:`MIME_XDG_PACKAGES` | ||
5359 | The current implementation of the :ref:`ref-classes-mime-xdg` | ||
5360 | class cannot detect ``.desktop`` files installed through absolute | ||
5361 | symbolic links. Use this setting to make the class create post-install | ||
5362 | and post-remove scripts for these packages anyway, to invoke the | ||
5363 | ``update-destop-database`` command. | ||
5364 | |||
4646 | :term:`MIRRORS` | 5365 | :term:`MIRRORS` |
4647 | Specifies additional paths from which the OpenEmbedded build system | 5366 | Specifies additional paths from which the OpenEmbedded build system |
4648 | gets source code. When the build system searches for source code, it | 5367 | gets source code. When the build system searches for source code, it |
4649 | first tries the local download directory. If that location fails, the | 5368 | first tries the local download directory. If that location fails, the |
4650 | build system tries locations defined by | 5369 | build system tries locations defined by |
4651 | :term:`PREMIRRORS`, the upstream source, and then | 5370 | :term:`PREMIRRORS`, the upstream source, and then |
4652 | locations specified by ``MIRRORS`` in that order. | 5371 | locations specified by :term:`MIRRORS` in that order. |
4653 | 5372 | ||
4654 | Assuming your distribution (:term:`DISTRO`) is "poky", | 5373 | The default value for :term:`MIRRORS` is defined in the |
4655 | the default value for ``MIRRORS`` is defined in the | 5374 | ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. |
4656 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
4657 | 5375 | ||
4658 | :term:`MLPREFIX` | 5376 | :term:`MLPREFIX` |
4659 | Specifies a prefix has been added to :term:`PN` to create a | 5377 | Specifies a prefix has been added to :term:`PN` to create a |
4660 | special version of a recipe or package (i.e. a Multilib version). The | 5378 | special version of a recipe or package (i.e. a Multilib version). The |
4661 | variable is used in places where the prefix needs to be added to or | 5379 | variable is used in places where the prefix needs to be added to or |
4662 | removed from a the name (e.g. the :term:`BPN` variable). | 5380 | removed from a name (e.g. the :term:`BPN` variable). |
4663 | ``MLPREFIX`` gets set when a prefix has been added to ``PN``. | 5381 | :term:`MLPREFIX` gets set when a prefix has been added to :term:`PN`. |
4664 | 5382 | ||
4665 | .. note:: | 5383 | .. note:: |
4666 | 5384 | ||
4667 | The "ML" in ``MLPREFIX`` stands for "MultiLib". This representation is | 5385 | The "ML" in :term:`MLPREFIX` stands for "MultiLib". This representation |
4668 | historical and comes from a time when ``nativesdk`` was a suffix | 5386 | is historical and comes from a time when ":ref:`ref-classes-nativesdk`" |
4669 | rather than a prefix on the recipe name. When ``nativesdk`` was turned | 5387 | was a suffix rather than a prefix on the recipe name. When |
4670 | into a prefix, it made sense to set ``MLPREFIX`` for it as well. | 5388 | ":ref:`ref-classes-nativesdk`" was turned into a prefix, it made sense |
4671 | 5389 | to set :term:`MLPREFIX` for it as well. | |
4672 | To help understand when ``MLPREFIX`` might be needed, consider when | 5390 | |
4673 | :term:`BBCLASSEXTEND` is used to provide a | 5391 | To help understand when :term:`MLPREFIX` might be needed, consider when |
4674 | ``nativesdk`` version of a recipe in addition to the target version. | 5392 | :term:`BBCLASSEXTEND` is used to provide a :ref:`ref-classes-nativesdk` |
4675 | If that recipe declares build-time dependencies on tasks in other | 5393 | version of a recipe in addition to the target version. If that recipe |
4676 | recipes by using :term:`DEPENDS`, then a dependency on | 5394 | declares build-time dependencies on tasks in other recipes by using |
4677 | "foo" will automatically get rewritten to a dependency on | 5395 | :term:`DEPENDS`, then a dependency on "foo" will automatically get |
4678 | "nativesdk-foo". However, dependencies like the following will not | 5396 | rewritten to a dependency on "nativesdk-foo". However, dependencies like |
4679 | get rewritten automatically: | 5397 | the following will not get rewritten automatically:: |
4680 | :: | ||
4681 | 5398 | ||
4682 | do_foo[depends] += "recipe:do_foo" | 5399 | do_foo[depends] += "recipe:do_foo" |
4683 | 5400 | ||
4684 | If you want such a dependency to also get transformed, you can do the | 5401 | If you want such a dependency to also get transformed, you can do the |
4685 | following: | 5402 | following:: |
4686 | :: | ||
4687 | 5403 | ||
4688 | do_foo[depends] += "${MLPREFIX}recipe:do_foo" | 5404 | do_foo[depends] += "${MLPREFIX}recipe:do_foo" |
4689 | 5405 | ||
4690 | module_autoload | 5406 | :term:`module_autoload` |
4691 | This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` | 5407 | This variable has been replaced by the :term:`KERNEL_MODULE_AUTOLOAD` |
4692 | variable. You should replace all occurrences of ``module_autoload`` | 5408 | variable. You should replace all occurrences of :term:`module_autoload` |
4693 | with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: | 5409 | with additions to :term:`KERNEL_MODULE_AUTOLOAD`, for example:: |
4694 | :: | ||
4695 | 5410 | ||
4696 | module_autoload_rfcomm = "rfcomm" | 5411 | module_autoload_rfcomm = "rfcomm" |
4697 | 5412 | ||
4698 | should now be replaced with: | 5413 | should now be replaced with:: |
4699 | :: | ||
4700 | 5414 | ||
4701 | KERNEL_MODULE_AUTOLOAD += "rfcomm" | 5415 | KERNEL_MODULE_AUTOLOAD += "rfcomm" |
4702 | 5416 | ||
4703 | See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. | 5417 | See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information. |
4704 | 5418 | ||
4705 | module_conf | 5419 | :term:`module_conf` |
4706 | Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`_ | 5420 | Specifies `modprobe.d <https://linux.die.net/man/5/modprobe.d>`__ |
4707 | syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` | 5421 | syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` |
4708 | file. | 5422 | file. |
4709 | 5423 | ||
@@ -4712,24 +5426,22 @@ system and gives an overview of their function and contents. | |||
4712 | configuration file, a distribution configuration file, an append file | 5426 | configuration file, a distribution configuration file, an append file |
4713 | for the recipe, or the recipe itself). If you use this variable, you | 5427 | for the recipe, or the recipe itself). If you use this variable, you |
4714 | must also be sure to list the module name in the | 5428 | must also be sure to list the module name in the |
4715 | :term:`KERNEL_MODULE_AUTOLOAD` | 5429 | :term:`KERNEL_MODULE_PROBECONF` |
4716 | variable. | 5430 | variable. |
4717 | 5431 | ||
4718 | Here is the general syntax: | 5432 | Here is the general syntax:: |
4719 | :: | ||
4720 | 5433 | ||
4721 | module_conf_module_name = "modprobe.d-syntax" | 5434 | module_conf_module_name = "modprobe.d-syntax" |
4722 | 5435 | ||
4723 | You must use the kernel module name override. | 5436 | You must use the kernel module name override. |
4724 | 5437 | ||
4725 | Run ``man modprobe.d`` in the shell to find out more information on | 5438 | Run ``man modprobe.d`` in the shell to find out more information on |
4726 | the exact syntax you want to provide with ``module_conf``. | 5439 | the exact syntax you want to provide with :term:`module_conf`. |
4727 | 5440 | ||
4728 | Including ``module_conf`` causes the OpenEmbedded build system to | 5441 | Including :term:`module_conf` causes the OpenEmbedded build system to |
4729 | populate the ``/etc/modprobe.d/modname.conf`` file with | 5442 | populate the ``/etc/modprobe.d/modname.conf`` file with |
4730 | ``modprobe.d`` syntax lines. Here is an example that adds the options | 5443 | ``modprobe.d`` syntax lines. Here is an example that adds the options |
4731 | ``arg1`` and ``arg2`` to a module named ``mymodule``: | 5444 | ``arg1`` and ``arg2`` to a module named ``mymodule``:: |
4732 | :: | ||
4733 | 5445 | ||
4734 | module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" | 5446 | module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" |
4735 | 5447 | ||
@@ -4743,15 +5455,13 @@ system and gives an overview of their function and contents. | |||
4743 | 5455 | ||
4744 | :term:`MODULE_TARBALL_LINK_NAME` | 5456 | :term:`MODULE_TARBALL_LINK_NAME` |
4745 | The link name of the kernel module tarball. This variable is set in | 5457 | The link name of the kernel module tarball. This variable is set in |
4746 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | 5458 | the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: |
4747 | :: | ||
4748 | 5459 | ||
4749 | MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" | 5460 | MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" |
4750 | 5461 | ||
4751 | The value | 5462 | The value |
4752 | of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the | 5463 | of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the |
4753 | same file, has the following value: | 5464 | same file, has the following value:: |
4754 | :: | ||
4755 | 5465 | ||
4756 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" | 5466 | KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}" |
4757 | 5467 | ||
@@ -4759,16 +5469,16 @@ system and gives an overview of their function and contents. | |||
4759 | 5469 | ||
4760 | :term:`MODULE_TARBALL_NAME` | 5470 | :term:`MODULE_TARBALL_NAME` |
4761 | The base name of the kernel module tarball. This variable is set in | 5471 | The base name of the kernel module tarball. This variable is set in |
4762 | the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: | 5472 | the ``meta/classes-recipe/kernel-artifact-names.bbclass`` file as follows:: |
4763 | :: | ||
4764 | 5473 | ||
4765 | MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" | 5474 | MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" |
4766 | 5475 | ||
4767 | The value of the :term:`KERNEL_ARTIFACT_NAME` variable, | 5476 | See :term:`KERNEL_ARTIFACT_NAME` for additional information. |
4768 | which is set in the same file, has the following value: | ||
4769 | :: | ||
4770 | 5477 | ||
4771 | KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" | 5478 | :term:`MOUNT_BASE` |
5479 | On non-systemd systems (where ``udev-extraconf`` is being used), | ||
5480 | specifies the base directory for auto-mounting filesystems. The | ||
5481 | default value is "/run/media". | ||
4772 | 5482 | ||
4773 | :term:`MULTIMACH_TARGET_SYS` | 5483 | :term:`MULTIMACH_TARGET_SYS` |
4774 | Uniquely identifies the type of the target system for which packages | 5484 | Uniquely identifies the type of the target system for which packages |
@@ -4776,14 +5486,12 @@ system and gives an overview of their function and contents. | |||
4776 | target systems to be put into different subdirectories of the same | 5486 | target systems to be put into different subdirectories of the same |
4777 | output directory. | 5487 | output directory. |
4778 | 5488 | ||
4779 | The default value of this variable is: | 5489 | The default value of this variable is:: |
4780 | :: | ||
4781 | 5490 | ||
4782 | ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} | 5491 | ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} |
4783 | 5492 | ||
4784 | Some classes (e.g. | 5493 | Some classes (e.g. :ref:`ref-classes-cross-canadian`) modify the |
4785 | :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the | 5494 | :term:`MULTIMACH_TARGET_SYS` value. |
4786 | ``MULTIMACH_TARGET_SYS`` value. | ||
4787 | 5495 | ||
4788 | See the :term:`STAMP` variable for an example. See the | 5496 | See the :term:`STAMP` variable for an example. See the |
4789 | :term:`STAGING_DIR_TARGET` variable for more information. | 5497 | :term:`STAGING_DIR_TARGET` variable for more information. |
@@ -4808,23 +5516,21 @@ system and gives an overview of their function and contents. | |||
4808 | 5516 | ||
4809 | :term:`NO_GENERIC_LICENSE` | 5517 | :term:`NO_GENERIC_LICENSE` |
4810 | Avoids QA errors when you use a non-common, non-CLOSED license in a | 5518 | Avoids QA errors when you use a non-common, non-CLOSED license in a |
4811 | recipe. Packages exist, such as the linux-firmware package, with many | 5519 | recipe. There are packages, such as the linux-firmware package, with many |
4812 | licenses that are not in any way common. Also, new licenses are added | 5520 | licenses that are not in any way common. Also, new licenses are added |
4813 | occasionally to avoid introducing a lot of common license files, | 5521 | occasionally to avoid introducing a lot of common license files, |
4814 | which are only applicable to a specific package. | 5522 | which are only applicable to a specific package. |
4815 | ``NO_GENERIC_LICENSE`` is used to allow copying a license that does | 5523 | :term:`NO_GENERIC_LICENSE` is used to allow copying a license that does |
4816 | not exist in common licenses. | 5524 | not exist in common licenses. |
4817 | 5525 | ||
4818 | The following example shows how to add ``NO_GENERIC_LICENSE`` to a | 5526 | The following example shows how to add :term:`NO_GENERIC_LICENSE` to a |
4819 | recipe: | 5527 | recipe:: |
4820 | :: | ||
4821 | 5528 | ||
4822 | NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" | 5529 | NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source" |
4823 | 5530 | ||
4824 | The following is an example that | 5531 | Here is an example that |
4825 | uses the ``LICENSE.Abilis.txt`` file as the license from the fetched | 5532 | uses the ``LICENSE.Abilis.txt`` file as the license from the fetched |
4826 | source: | 5533 | source:: |
4827 | :: | ||
4828 | 5534 | ||
4829 | NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" | 5535 | NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" |
4830 | 5536 | ||
@@ -4832,15 +5538,15 @@ system and gives an overview of their function and contents. | |||
4832 | Prevents installation of all "recommended-only" packages. | 5538 | Prevents installation of all "recommended-only" packages. |
4833 | Recommended-only packages are packages installed only through the | 5539 | Recommended-only packages are packages installed only through the |
4834 | :term:`RRECOMMENDS` variable). Setting the | 5540 | :term:`RRECOMMENDS` variable). Setting the |
4835 | ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: :: | 5541 | :term:`NO_RECOMMENDATIONS` variable to "1" turns this feature on:: |
4836 | 5542 | ||
4837 | NO_RECOMMENDATIONS = "1" | 5543 | NO_RECOMMENDATIONS = "1" |
4838 | 5544 | ||
4839 | You can set this variable globally in your ``local.conf`` file or you | 5545 | You can set this variable globally in your ``local.conf`` file or you |
4840 | can attach it to a specific image recipe by using the recipe name | 5546 | can attach it to a specific image recipe by using the recipe name |
4841 | override: :: | 5547 | override:: |
4842 | 5548 | ||
4843 | NO_RECOMMENDATIONS_pn-target_image = "1" | 5549 | NO_RECOMMENDATIONS:pn-target_image = "1" |
4844 | 5550 | ||
4845 | It is important to realize that if you choose to not install packages | 5551 | It is important to realize that if you choose to not install packages |
4846 | using this variable and some other packages are dependent on them | 5552 | using this variable and some other packages are dependent on them |
@@ -4854,8 +5560,8 @@ system and gives an overview of their function and contents. | |||
4854 | functionality, such as kernel modules. It is up to you to add | 5560 | functionality, such as kernel modules. It is up to you to add |
4855 | packages with the :term:`IMAGE_INSTALL` variable. | 5561 | packages with the :term:`IMAGE_INSTALL` variable. |
4856 | 5562 | ||
4857 | Support for this variable exists only when using the IPK and RPM | 5563 | This variable is only supported when using the IPK and RPM |
4858 | packaging backend. Support does not exist for DEB. | 5564 | packaging backends. DEB is not supported. |
4859 | 5565 | ||
4860 | See the :term:`BAD_RECOMMENDATIONS` and | 5566 | See the :term:`BAD_RECOMMENDATIONS` and |
4861 | the :term:`PACKAGE_EXCLUDE` variables for | 5567 | the :term:`PACKAGE_EXCLUDE` variables for |
@@ -4863,15 +5569,21 @@ system and gives an overview of their function and contents. | |||
4863 | 5569 | ||
4864 | :term:`NOAUTOPACKAGEDEBUG` | 5570 | :term:`NOAUTOPACKAGEDEBUG` |
4865 | Disables auto package from splitting ``.debug`` files. If a recipe | 5571 | Disables auto package from splitting ``.debug`` files. If a recipe |
4866 | requires ``FILES_${PN}-dbg`` to be set manually, the | 5572 | requires ``FILES:${PN}-dbg`` to be set manually, the |
4867 | ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the | 5573 | :term:`NOAUTOPACKAGEDEBUG` can be defined allowing you to define the |
4868 | content of the debug package. For example: | 5574 | content of the debug package. For example:: |
4869 | :: | ||
4870 | 5575 | ||
4871 | NOAUTOPACKAGEDEBUG = "1" | 5576 | NOAUTOPACKAGEDEBUG = "1" |
4872 | FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" | 5577 | FILES:${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" |
4873 | FILES_${PN}-dbg = "/usr/src/debug/" | 5578 | FILES:${PN}-dbg = "/usr/src/debug/" |
4874 | FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" | 5579 | FILES:${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch" |
5580 | |||
5581 | :term:`NON_MULTILIB_RECIPES` | ||
5582 | A list of recipes that should not be built for multilib. OE-Core's | ||
5583 | ``multilib.conf`` file defines a reasonable starting point for this | ||
5584 | list with:: | ||
5585 | |||
5586 | NON_MULTILIB_RECIPES = "grub grub-efi make-mod-scripts ovmf u-boot" | ||
4875 | 5587 | ||
4876 | :term:`OBJCOPY` | 5588 | :term:`OBJCOPY` |
4877 | The minimal command and arguments to run ``objcopy``. | 5589 | The minimal command and arguments to run ``objcopy``. |
@@ -4880,7 +5592,7 @@ system and gives an overview of their function and contents. | |||
4880 | The minimal command and arguments to run ``objdump``. | 5592 | The minimal command and arguments to run ``objdump``. |
4881 | 5593 | ||
4882 | :term:`OE_BINCONFIG_EXTRA_MANGLE` | 5594 | :term:`OE_BINCONFIG_EXTRA_MANGLE` |
4883 | When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, | 5595 | When inheriting the :ref:`ref-classes-binconfig` class, |
4884 | this variable specifies additional arguments passed to the "sed" | 5596 | this variable specifies additional arguments passed to the "sed" |
4885 | command. The sed command alters any paths in configuration scripts | 5597 | command. The sed command alters any paths in configuration scripts |
4886 | that have been set up during compilation. Inheriting this class | 5598 | that have been set up during compilation. Inheriting this class |
@@ -4888,11 +5600,19 @@ system and gives an overview of their function and contents. | |||
4888 | ``sysroots/`` directory so that all builds that use the script will | 5600 | ``sysroots/`` directory so that all builds that use the script will |
4889 | use the correct directories for the cross compiling layout. | 5601 | use the correct directories for the cross compiling layout. |
4890 | 5602 | ||
4891 | See the ``meta/classes/binconfig.bbclass`` in the | 5603 | See the ``meta/classes-recipe/binconfig.bbclass`` in the |
4892 | :term:`Source Directory` for details on how this class | 5604 | :term:`Source Directory` for details on how this class |
4893 | applies these additional sed command arguments. For general | 5605 | applies these additional sed command arguments. |
4894 | information on the ``binconfig`` class, see the | 5606 | |
4895 | ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. | 5607 | :term:`OECMAKE_GENERATOR` |
5608 | A variable for the :ref:`ref-classes-cmake` class, allowing to choose | ||
5609 | which back-end will be generated by CMake to build an application. | ||
5610 | |||
5611 | By default, this variable is set to ``Ninja``, which is faster than GNU | ||
5612 | make, but if building is broken with Ninja, a recipe can use this | ||
5613 | variable to use GNU make instead:: | ||
5614 | |||
5615 | OECMAKE_GENERATOR = "Unix Makefiles" | ||
4896 | 5616 | ||
4897 | :term:`OE_IMPORTS` | 5617 | :term:`OE_IMPORTS` |
4898 | An internal variable used to tell the OpenEmbedded build system what | 5618 | An internal variable used to tell the OpenEmbedded build system what |
@@ -4908,16 +5628,16 @@ system and gives an overview of their function and contents. | |||
4908 | value is "oe-init-build-env". | 5628 | value is "oe-init-build-env". |
4909 | 5629 | ||
4910 | If you use a custom script to set up your build environment, set the | 5630 | If you use a custom script to set up your build environment, set the |
4911 | ``OE_INIT_ENV_SCRIPT`` variable to its name. | 5631 | :term:`OE_INIT_ENV_SCRIPT` variable to its name. |
4912 | 5632 | ||
4913 | :term:`OE_TERMINAL` | 5633 | :term:`OE_TERMINAL` |
4914 | Controls how the OpenEmbedded build system spawns interactive | 5634 | Controls how the OpenEmbedded build system spawns interactive |
4915 | terminals on the host development system (e.g. using the BitBake | 5635 | terminals on the host development system (e.g. using the BitBake |
4916 | command with the ``-c devshell`` command-line option). For more | 5636 | command with the ``-c devshell`` command-line option). For more |
4917 | information, see the ":ref:`dev-manual/common-tasks:using a development shell`" section in | 5637 | information, see the ":ref:`dev-manual/development-shell:using a development shell`" section in |
4918 | the Yocto Project Development Tasks Manual. | 5638 | the Yocto Project Development Tasks Manual. |
4919 | 5639 | ||
4920 | You can use the following values for the ``OE_TERMINAL`` variable: | 5640 | You can use the following values for the :term:`OE_TERMINAL` variable: |
4921 | 5641 | ||
4922 | - auto | 5642 | - auto |
4923 | - gnome | 5643 | - gnome |
@@ -4931,12 +5651,26 @@ system and gives an overview of their function and contents. | |||
4931 | The directory from which the top-level build environment setup script | 5651 | The directory from which the top-level build environment setup script |
4932 | is sourced. The Yocto Project provides a top-level build environment | 5652 | is sourced. The Yocto Project provides a top-level build environment |
4933 | setup script: :ref:`structure-core-script`. When you run this | 5653 | setup script: :ref:`structure-core-script`. When you run this |
4934 | script, the ``OEROOT`` variable resolves to the directory that | 5654 | script, the :term:`OEROOT` variable resolves to the directory that |
4935 | contains the script. | 5655 | contains the script. |
4936 | 5656 | ||
4937 | For additional information on how this variable is used, see the | 5657 | For additional information on how this variable is used, see the |
4938 | initialization script. | 5658 | initialization script. |
4939 | 5659 | ||
5660 | :term:`OEQA_REPRODUCIBLE_TEST_PACKAGE` | ||
5661 | Set the package manager(s) for build reproducibility testing. | ||
5662 | See :yocto_git:`reproducible.py </poky/tree/meta/lib/oeqa/selftest/cases/reproducible.py>` | ||
5663 | and :doc:`/test-manual/reproducible-builds`. | ||
5664 | |||
5665 | :term:`OEQA_REPRODUCIBLE_TEST_TARGET` | ||
5666 | Set build target for build reproducibility testing. By default | ||
5667 | all available recipes are compiled with "bitbake world", see also :term:`EXCLUDE_FROM_WORLD` | ||
5668 | and :doc:`/test-manual/reproducible-builds`. | ||
5669 | |||
5670 | :term:`OEQA_REPRODUCIBLE_TEST_SSTATE_TARGETS` | ||
5671 | Set build targets which can be rebuilt using :ref:`shared state <overview-manual/concepts:shared state cache>` | ||
5672 | when running build reproducibility tests. See :doc:`/test-manual/reproducible-builds`. | ||
5673 | |||
4940 | :term:`OLDEST_KERNEL` | 5674 | :term:`OLDEST_KERNEL` |
4941 | Declares the oldest version of the Linux kernel that the produced | 5675 | Declares the oldest version of the Linux kernel that the produced |
4942 | binaries must support. This variable is passed into the build of the | 5676 | binaries must support. This variable is passed into the build of the |
@@ -4947,53 +5681,136 @@ system and gives an overview of their function and contents. | |||
4947 | default by setting the variable in a custom distribution | 5681 | default by setting the variable in a custom distribution |
4948 | configuration file. | 5682 | configuration file. |
4949 | 5683 | ||
5684 | :term:`OPKG_MAKE_INDEX_EXTRA_PARAMS` | ||
5685 | Specifies extra parameters for the ``opkg-make-index`` command. | ||
5686 | |||
5687 | :term:`OVERLAYFS_ETC_DEVICE` | ||
5688 | When the :ref:`ref-classes-overlayfs-etc` class is | ||
5689 | inherited, specifies the device to be mounted for the read/write | ||
5690 | layer of ``/etc``. There is no default, so you must set this if you | ||
5691 | wish to enable :ref:`ref-classes-overlayfs-etc`, for | ||
5692 | example, assuming ``/dev/mmcblk0p2`` was the desired device:: | ||
5693 | |||
5694 | OVERLAYFS_ETC_DEVICE = "/dev/mmcblk0p2" | ||
5695 | |||
5696 | :term:`OVERLAYFS_ETC_EXPOSE_LOWER` | ||
5697 | When the :ref:`ref-classes-overlayfs-etc` class is | ||
5698 | inherited, if set to "1" then a read-only access to the original | ||
5699 | ``/etc`` content will be provided as a ``lower/`` subdirectory of | ||
5700 | :term:`OVERLAYFS_ETC_MOUNT_POINT`. The default value is "0". | ||
5701 | |||
5702 | :term:`OVERLAYFS_ETC_FSTYPE` | ||
5703 | When the :ref:`ref-classes-overlayfs-etc` class is | ||
5704 | inherited, specifies the file system type for the read/write | ||
5705 | layer of ``/etc``. There is no default, so you must set this if you | ||
5706 | wish to enable :ref:`ref-classes-overlayfs-etc`, | ||
5707 | for example, assuming the file system is ext4:: | ||
5708 | |||
5709 | OVERLAYFS_ETC_FSTYPE = "ext4" | ||
5710 | |||
5711 | :term:`OVERLAYFS_ETC_MOUNT_OPTIONS` | ||
5712 | When the :ref:`ref-classes-overlayfs-etc` class is | ||
5713 | inherited, specifies the mount options for the read-write layer. | ||
5714 | The default value is "defaults". | ||
5715 | |||
5716 | :term:`OVERLAYFS_ETC_MOUNT_POINT` | ||
5717 | When the :ref:`ref-classes-overlayfs-etc` class is | ||
5718 | inherited, specifies the parent mount path for the filesystem layers. | ||
5719 | There is no default, so you must set this if you wish to enable | ||
5720 | :ref:`ref-classes-overlayfs-etc`, for example if the desired path is | ||
5721 | "/data":: | ||
5722 | |||
5723 | OVERLAYFS_ETC_MOUNT_POINT = "/data" | ||
5724 | |||
5725 | :term:`OVERLAYFS_ETC_USE_ORIG_INIT_NAME` | ||
5726 | When the :ref:`ref-classes-overlayfs-etc` class is inherited, controls | ||
5727 | how the generated init will be named. For more information, see the | ||
5728 | :ref:`ref-classes-overlayfs-etc` class documentation. The default value | ||
5729 | is "1". | ||
5730 | |||
5731 | :term:`OVERLAYFS_MOUNT_POINT` | ||
5732 | When inheriting the :ref:`ref-classes-overlayfs` class, | ||
5733 | specifies mount point(s) to be used. For example:: | ||
5734 | |||
5735 | OVERLAYFS_MOUNT_POINT[data] = "/data" | ||
5736 | |||
5737 | The assumes you have a ``data.mount`` systemd unit defined elsewhere in | ||
5738 | your BSP (e.g. in ``systemd-machine-units`` recipe) and it is installed | ||
5739 | into the image. For more information see :ref:`ref-classes-overlayfs`. | ||
5740 | |||
5741 | .. note:: | ||
5742 | |||
5743 | Although the :ref:`ref-classes-overlayfs` class is | ||
5744 | inherited by individual recipes, :term:`OVERLAYFS_MOUNT_POINT` | ||
5745 | should be set in your machine configuration. | ||
5746 | |||
5747 | :term:`OVERLAYFS_QA_SKIP` | ||
5748 | When inheriting the :ref:`ref-classes-overlayfs` class, | ||
5749 | provides the ability to disable QA checks for particular overlayfs | ||
5750 | mounts. For example:: | ||
5751 | |||
5752 | OVERLAYFS_QA_SKIP[data] = "mount-configured" | ||
5753 | |||
5754 | .. note:: | ||
5755 | |||
5756 | Although the :ref:`ref-classes-overlayfs` class is | ||
5757 | inherited by individual recipes, :term:`OVERLAYFS_QA_SKIP` | ||
5758 | should be set in your machine configuration. | ||
5759 | |||
5760 | :term:`OVERLAYFS_WRITABLE_PATHS` | ||
5761 | When inheriting the :ref:`ref-classes-overlayfs` class, | ||
5762 | specifies writable paths used at runtime for the recipe. For | ||
5763 | example:: | ||
5764 | |||
5765 | OVERLAYFS_WRITABLE_PATHS[data] = "/usr/share/my-custom-application" | ||
5766 | |||
4950 | :term:`OVERRIDES` | 5767 | :term:`OVERRIDES` |
4951 | A colon-separated list of overrides that currently apply. Overrides | 5768 | A colon-separated list of overrides that currently apply. Overrides |
4952 | are a BitBake mechanism that allows variables to be selectively | 5769 | are a BitBake mechanism that allows variables to be selectively |
4953 | overridden at the end of parsing. The set of overrides in | 5770 | overridden at the end of parsing. The set of overrides in |
4954 | ``OVERRIDES`` represents the "state" during building, which includes | 5771 | :term:`OVERRIDES` represents the "state" during building, which includes |
4955 | the current recipe being built, the machine for which it is being | 5772 | the current recipe being built, the machine for which it is being |
4956 | built, and so forth. | 5773 | built, and so forth. |
4957 | 5774 | ||
4958 | As an example, if the string "an-override" appears as an element in | 5775 | As an example, if the string "an-override" appears as an element in |
4959 | the colon-separated list in ``OVERRIDES``, then the following | 5776 | the colon-separated list in :term:`OVERRIDES`, then the following |
4960 | assignment will override ``FOO`` with the value "overridden" at the | 5777 | assignment will override ``FOO`` with the value "overridden" at the |
4961 | end of parsing: | 5778 | end of parsing:: |
4962 | :: | ||
4963 | 5779 | ||
4964 | FOO_an-override = "overridden" | 5780 | FOO:an-override = "overridden" |
4965 | 5781 | ||
4966 | See the | 5782 | See the |
4967 | ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" | 5783 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" |
4968 | section in the BitBake User Manual for more information on the | 5784 | section in the BitBake User Manual for more information on the |
4969 | overrides mechanism. | 5785 | overrides mechanism. |
4970 | 5786 | ||
4971 | The default value of ``OVERRIDES`` includes the values of the | 5787 | The default value of :term:`OVERRIDES` includes the values of the |
4972 | :term:`CLASSOVERRIDE`, | 5788 | :term:`CLASSOVERRIDE`, |
4973 | :term:`MACHINEOVERRIDES`, and | 5789 | :term:`MACHINEOVERRIDES`, and |
4974 | :term:`DISTROOVERRIDES` variables. Another | 5790 | :term:`DISTROOVERRIDES` variables. Another |
4975 | important override included by default is ``pn-${PN}``. This override | 5791 | important override included by default is ``pn-${PN}``. This override |
4976 | allows variables to be set for a single recipe within configuration | 5792 | allows variables to be set for a single recipe within configuration |
4977 | (``.conf``) files. Here is an example: | 5793 | (``.conf``) files. Here is an example:: |
4978 | :: | ||
4979 | 5794 | ||
4980 | FOO_pn-myrecipe = "myrecipe-specific value" | 5795 | FOO:pn-myrecipe = "myrecipe-specific value" |
4981 | 5796 | ||
4982 | .. note:: | 5797 | .. note:: |
4983 | 5798 | ||
4984 | An easy way to see what overrides apply is to search for ``OVERRIDES`` | 5799 | An easy way to see what overrides apply is to search for :term:`OVERRIDES` |
4985 | in the output of the ``bitbake -e`` command. See the | 5800 | in the output of the ``bitbake -e`` command. See the |
4986 | ":ref:`dev-manual/common-tasks:viewing variable values`" section in the Yocto | 5801 | ":ref:`dev-manual/debugging:viewing variable values`" section in the Yocto |
4987 | Project Development Tasks Manual for more information. | 5802 | Project Development Tasks Manual for more information. |
4988 | 5803 | ||
4989 | :term:`P` | 5804 | :term:`P` |
4990 | The recipe name and version. ``P`` is comprised of the following: | 5805 | The recipe name and version. :term:`P` is comprised of the following:: |
4991 | :: | ||
4992 | 5806 | ||
4993 | ${PN}-${PV} | 5807 | ${PN}-${PV} |
4994 | 5808 | ||
5809 | :term:`P4DIR` | ||
5810 | See :term:`bitbake:P4DIR` in the BitBake manual. | ||
5811 | |||
4995 | :term:`PACKAGE_ADD_METADATA` | 5812 | :term:`PACKAGE_ADD_METADATA` |
4996 | This variable defines additional metdata to add to packages. | 5813 | This variable defines additional metadata to add to packages. |
4997 | 5814 | ||
4998 | You may find you need to inject additional metadata into packages. | 5815 | You may find you need to inject additional metadata into packages. |
4999 | This variable allows you to do that by setting the injected data as | 5816 | This variable allows you to do that by setting the injected data as |
@@ -5005,7 +5822,7 @@ system and gives an overview of their function and contents. | |||
5005 | specific by using the package name as a suffix. | 5822 | specific by using the package name as a suffix. |
5006 | 5823 | ||
5007 | You can find out more about applying this variable in the | 5824 | You can find out more about applying this variable in the |
5008 | ":ref:`dev-manual/common-tasks:adding custom metadata to packages`" | 5825 | ":ref:`dev-manual/packages:adding custom metadata to packages`" |
5009 | section in the Yocto Project Development Tasks Manual. | 5826 | section in the Yocto Project Development Tasks Manual. |
5010 | 5827 | ||
5011 | :term:`PACKAGE_ARCH` | 5828 | :term:`PACKAGE_ARCH` |
@@ -5023,9 +5840,8 @@ system and gives an overview of their function and contents. | |||
5023 | 5840 | ||
5024 | However, if your recipe's output packages are built specific to the | 5841 | However, if your recipe's output packages are built specific to the |
5025 | target machine rather than generally for the architecture of the | 5842 | target machine rather than generally for the architecture of the |
5026 | machine, you should set ``PACKAGE_ARCH`` to the value of | 5843 | machine, you should set :term:`PACKAGE_ARCH` to the value of |
5027 | :term:`MACHINE_ARCH` in the recipe as follows: | 5844 | :term:`MACHINE_ARCH` in the recipe as follows:: |
5028 | :: | ||
5029 | 5845 | ||
5030 | PACKAGE_ARCH = "${MACHINE_ARCH}" | 5846 | PACKAGE_ARCH = "${MACHINE_ARCH}" |
5031 | 5847 | ||
@@ -5033,11 +5849,11 @@ system and gives an overview of their function and contents. | |||
5033 | Specifies a list of architectures compatible with the target machine. | 5849 | Specifies a list of architectures compatible with the target machine. |
5034 | This variable is set automatically and should not normally be | 5850 | This variable is set automatically and should not normally be |
5035 | hand-edited. Entries are separated using spaces and listed in order | 5851 | hand-edited. Entries are separated using spaces and listed in order |
5036 | of priority. The default value for ``PACKAGE_ARCHS`` is "all any | 5852 | of priority. The default value for :term:`PACKAGE_ARCHS` is "all any |
5037 | noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". | 5853 | noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". |
5038 | 5854 | ||
5039 | :term:`PACKAGE_BEFORE_PN` | 5855 | :term:`PACKAGE_BEFORE_PN` |
5040 | Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so | 5856 | Enables easily adding packages to :term:`PACKAGES` before ``${PN}`` so |
5041 | that those added packages can pick up files that would normally be | 5857 | that those added packages can pick up files that would normally be |
5042 | included in the default package. | 5858 | included in the default package. |
5043 | 5859 | ||
@@ -5048,21 +5864,14 @@ system and gives an overview of their function and contents. | |||
5048 | OpenEmbedded build system uses when packaging data. | 5864 | OpenEmbedded build system uses when packaging data. |
5049 | 5865 | ||
5050 | You can provide one or more of the following arguments for the | 5866 | You can provide one or more of the following arguments for the |
5051 | variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk | 5867 | variable:: |
5052 | package_tar" | ||
5053 | 5868 | ||
5054 | .. note:: | 5869 | PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk" |
5055 | |||
5056 | While it is a legal option, the ``package_tar`` | ||
5057 | class has limited functionality due to no support for package | ||
5058 | dependencies by that backend. Therefore, it is recommended that | ||
5059 | you do not use it. | ||
5060 | 5870 | ||
5061 | The build system uses only the first argument in the list as the | 5871 | The build system uses only the first argument in the list as the |
5062 | package manager when creating your image or SDK. However, packages | 5872 | package manager when creating your image or SDK. However, packages |
5063 | will be created using any additional packaging classes you specify. | 5873 | will be created using any additional packaging classes you specify. |
5064 | For example, if you use the following in your ``local.conf`` file: | 5874 | For example, if you use the following in your ``local.conf`` file:: |
5065 | :: | ||
5066 | 5875 | ||
5067 | PACKAGE_CLASSES ?= "package_ipk" | 5876 | PACKAGE_CLASSES ?= "package_ipk" |
5068 | 5877 | ||
@@ -5071,66 +5880,63 @@ system and gives an overview of their function and contents. | |||
5071 | 5880 | ||
5072 | For information on packaging and build performance effects as a | 5881 | For information on packaging and build performance effects as a |
5073 | result of the package manager in use, see the | 5882 | result of the package manager in use, see the |
5074 | ":ref:`package.bbclass <ref-classes-package>`" section. | 5883 | ":ref:`ref-classes-package`" section. |
5075 | 5884 | ||
5076 | :term:`PACKAGE_DEBUG_SPLIT_STYLE` | 5885 | :term:`PACKAGE_DEBUG_SPLIT_STYLE` |
5077 | Determines how to split up the binary and debug information when | 5886 | Determines how to split up and package debug and source information |
5078 | creating ``*-dbg`` packages to be used with the GNU Project Debugger | 5887 | when creating debugging packages to be used with the GNU Project |
5079 | (GDB). | 5888 | Debugger (GDB). In general, based on the value of this variable, |
5080 | 5889 | you can combine the source and debug info in a single package, | |
5081 | With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control | 5890 | you can break out the source into a separate package that can be |
5082 | where debug information, which can include or exclude source files, | 5891 | installed independently, or you can choose to not have the source |
5083 | is stored: | 5892 | packaged at all. |
5084 | 5893 | ||
5085 | - ".debug": Debug symbol files are placed next to the binary in a | 5894 | The possible values of :term:`PACKAGE_DEBUG_SPLIT_STYLE` variable: |
5086 | ``.debug`` directory on the target. For example, if a binary is | 5895 | |
5087 | installed into ``/bin``, the corresponding debug symbol files are | 5896 | - "``.debug``": All debugging and source info is placed in a single |
5088 | installed in ``/bin/.debug``. Source files are placed in | 5897 | ``*-dbg`` package; debug symbol files are placed next to the |
5089 | ``/usr/src/debug``. | 5898 | binary in a ``.debug`` directory so that, if a binary is installed |
5090 | 5899 | into ``/bin``, the corresponding debug symbol file is installed | |
5091 | - "debug-file-directory": Debug symbol files are placed under | 5900 | in ``/bin/.debug``. Source files are installed in the same ``*-dbg`` |
5092 | ``/usr/lib/debug`` on the target, and separated by the path from | 5901 | package under ``/usr/src/debug``. |
5093 | where the binary is installed. For example, if a binary is | 5902 | |
5094 | installed in ``/bin``, the corresponding debug symbols are | 5903 | - "``debug-file-directory``": As above, all debugging and source info |
5095 | installed in ``/usr/lib/debug/bin``. Source files are placed in | 5904 | is placed in a single ``*-dbg`` package; debug symbol files are |
5096 | ``/usr/src/debug``. | 5905 | placed entirely under the directory ``/usr/lib/debug`` and separated |
5097 | 5906 | by the path from where the binary is installed, so that if a binary | |
5098 | - "debug-without-src": The same behavior as ".debug" previously | 5907 | is installed in ``/bin``, the corresponding debug symbols are installed |
5099 | described with the exception that no source files are installed. | 5908 | in ``/usr/lib/debug/bin``, and so on. As above, source is installed |
5100 | 5909 | in the same package under ``/usr/src/debug``. | |
5101 | - "debug-with-srcpkg": The same behavior as ".debug" previously | 5910 | |
5102 | described with the exception that all source files are placed in a | 5911 | - "``debug-with-srcpkg``": Debugging info is placed in the standard |
5103 | separate ``*-src`` pkg. This is the default behavior. | 5912 | ``*-dbg`` package as with the ``.debug`` value, while source is |
5913 | placed in a separate ``*-src`` package, which can be installed | ||
5914 | independently. This is the default setting for this variable, | ||
5915 | as defined in Poky's ``bitbake.conf`` file. | ||
5916 | |||
5917 | - "``debug-without-src``": The same behavior as with the ``.debug`` | ||
5918 | setting, but no source is packaged at all. | ||
5104 | 5919 | ||
5105 | You can find out more about debugging using GDB by reading the | 5920 | .. note:: |
5106 | ":ref:`dev-manual/common-tasks:debugging with the gnu project debugger (gdb) remotely`" section | ||
5107 | in the Yocto Project Development Tasks Manual. | ||
5108 | 5921 | ||
5109 | :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` | 5922 | Much of the above package splitting can be overridden via |
5110 | Prevents specific packages from being installed when you are | 5923 | use of the :term:`INHIBIT_PACKAGE_DEBUG_SPLIT` variable. |
5111 | installing complementary packages. | ||
5112 | 5924 | ||
5113 | You might find that you want to prevent installing certain packages | 5925 | You can find out more about debugging using GDB by reading the |
5114 | when you are installing complementary packages. For example, if you | 5926 | ":ref:`dev-manual/debugging:debugging with the gnu project debugger (gdb) remotely`" section |
5115 | are using :term:`IMAGE_FEATURES` to install | 5927 | in the Yocto Project Development Tasks Manual. |
5116 | ``dev-pkgs``, you might not want to install all packages from a | ||
5117 | particular multilib. If you find yourself in this situation, you can | ||
5118 | use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular | ||
5119 | expressions to match the packages you want to exclude. | ||
5120 | 5928 | ||
5121 | :term:`PACKAGE_EXCLUDE` | 5929 | :term:`PACKAGE_EXCLUDE` |
5122 | Lists packages that should not be installed into an image. For | 5930 | Lists packages that should not be installed into an image. For |
5123 | example: | 5931 | example:: |
5124 | :: | ||
5125 | 5932 | ||
5126 | PACKAGE_EXCLUDE = "package_name package_name package_name ..." | 5933 | PACKAGE_EXCLUDE = "package_name package_name package_name ..." |
5127 | 5934 | ||
5128 | You can set this variable globally in your ``local.conf`` file or you | 5935 | You can set this variable globally in your ``local.conf`` file or you |
5129 | can attach it to a specific image recipe by using the recipe name | 5936 | can attach it to a specific image recipe by using the recipe name |
5130 | override: | 5937 | override:: |
5131 | :: | ||
5132 | 5938 | ||
5133 | PACKAGE_EXCLUDE_pn-target_image = "package_name" | 5939 | PACKAGE_EXCLUDE:pn-target_image = "package_name" |
5134 | 5940 | ||
5135 | If you choose to not install a package using this variable and some | 5941 | If you choose to not install a package using this variable and some |
5136 | other package is dependent on it (i.e. listed in a recipe's | 5942 | other package is dependent on it (i.e. listed in a recipe's |
@@ -5140,13 +5946,25 @@ system and gives an overview of their function and contents. | |||
5140 | an iterative development process to remove specific components from a | 5946 | an iterative development process to remove specific components from a |
5141 | system. | 5947 | system. |
5142 | 5948 | ||
5143 | Support for this variable exists only when using the IPK and RPM | 5949 | This variable is supported only when using the IPK and RPM |
5144 | packaging backend. Support does not exist for DEB. | 5950 | packaging backends. DEB is not supported. |
5145 | 5951 | ||
5146 | See the :term:`NO_RECOMMENDATIONS` and the | 5952 | See the :term:`NO_RECOMMENDATIONS` and the |
5147 | :term:`BAD_RECOMMENDATIONS` variables for | 5953 | :term:`BAD_RECOMMENDATIONS` variables for |
5148 | related information. | 5954 | related information. |
5149 | 5955 | ||
5956 | :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` | ||
5957 | Prevents specific packages from being installed when you are | ||
5958 | installing complementary packages. | ||
5959 | |||
5960 | You might find that you want to prevent installing certain packages | ||
5961 | when you are installing complementary packages. For example, if you | ||
5962 | are using :term:`IMAGE_FEATURES` to install | ||
5963 | ``dev-pkgs``, you might not want to install all packages from a | ||
5964 | particular multilib. If you find yourself in this situation, you can | ||
5965 | use the :term:`PACKAGE_EXCLUDE_COMPLEMENTARY` variable to specify regular | ||
5966 | expressions to match the packages you want to exclude. | ||
5967 | |||
5150 | :term:`PACKAGE_EXTRA_ARCHS` | 5968 | :term:`PACKAGE_EXTRA_ARCHS` |
5151 | Specifies the list of architectures compatible with the device CPU. | 5969 | Specifies the list of architectures compatible with the device CPU. |
5152 | This variable is useful when you build for several different devices | 5970 | This variable is useful when you build for several different devices |
@@ -5155,7 +5973,7 @@ system and gives an overview of their function and contents. | |||
5155 | :term:`PACKAGE_FEED_ARCHS` | 5973 | :term:`PACKAGE_FEED_ARCHS` |
5156 | Optionally specifies the package architectures used as part of the | 5974 | Optionally specifies the package architectures used as part of the |
5157 | package feed URIs during the build. When used, the | 5975 | package feed URIs during the build. When used, the |
5158 | ``PACKAGE_FEED_ARCHS`` variable is appended to the final package feed | 5976 | :term:`PACKAGE_FEED_ARCHS` variable is appended to the final package feed |
5159 | URI, which is constructed using the | 5977 | URI, which is constructed using the |
5160 | :term:`PACKAGE_FEED_URIS` and | 5978 | :term:`PACKAGE_FEED_URIS` and |
5161 | :term:`PACKAGE_FEED_BASE_PATHS` | 5979 | :term:`PACKAGE_FEED_BASE_PATHS` |
@@ -5163,17 +5981,16 @@ system and gives an overview of their function and contents. | |||
5163 | 5981 | ||
5164 | .. note:: | 5982 | .. note:: |
5165 | 5983 | ||
5166 | You can use the ``PACKAGE_FEED_ARCHS`` | 5984 | You can use the :term:`PACKAGE_FEED_ARCHS` |
5167 | variable to whitelist specific package architectures. If you do | 5985 | variable to allow specific package architectures. If you do |
5168 | not need to whitelist specific architectures, which is a common | 5986 | not need to allow specific architectures, which is a common |
5169 | case, you can omit this variable. Omitting the variable results in | 5987 | case, you can omit this variable. Omitting the variable results in |
5170 | all available architectures for the current machine being included | 5988 | all available architectures for the current machine being included |
5171 | into remote package feeds. | 5989 | into remote package feeds. |
5172 | 5990 | ||
5173 | Consider the following example where the ``PACKAGE_FEED_URIS``, | 5991 | Consider the following example where the :term:`PACKAGE_FEED_URIS`, |
5174 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | 5992 | :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are |
5175 | defined in your ``local.conf`` file: | 5993 | defined in your ``local.conf`` file:: |
5176 | :: | ||
5177 | 5994 | ||
5178 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | 5995 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ |
5179 | https://example.com/packagerepos/updates" | 5996 | https://example.com/packagerepos/updates" |
@@ -5195,15 +6012,14 @@ system and gives an overview of their function and contents. | |||
5195 | 6012 | ||
5196 | :term:`PACKAGE_FEED_BASE_PATHS` | 6013 | :term:`PACKAGE_FEED_BASE_PATHS` |
5197 | Specifies the base path used when constructing package feed URIs. The | 6014 | Specifies the base path used when constructing package feed URIs. The |
5198 | ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a | 6015 | :term:`PACKAGE_FEED_BASE_PATHS` variable makes up the middle portion of a |
5199 | package feed URI used by the OpenEmbedded build system. The base path | 6016 | package feed URI used by the OpenEmbedded build system. The base path |
5200 | lies between the :term:`PACKAGE_FEED_URIS` | 6017 | lies between the :term:`PACKAGE_FEED_URIS` |
5201 | and :term:`PACKAGE_FEED_ARCHS` variables. | 6018 | and :term:`PACKAGE_FEED_ARCHS` variables. |
5202 | 6019 | ||
5203 | Consider the following example where the ``PACKAGE_FEED_URIS``, | 6020 | Consider the following example where the :term:`PACKAGE_FEED_URIS`, |
5204 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | 6021 | :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are |
5205 | defined in your ``local.conf`` file: | 6022 | defined in your ``local.conf`` file:: |
5206 | :: | ||
5207 | 6023 | ||
5208 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | 6024 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ |
5209 | https://example.com/packagerepos/updates" | 6025 | https://example.com/packagerepos/updates" |
@@ -5226,14 +6042,13 @@ system and gives an overview of their function and contents. | |||
5226 | :term:`PACKAGE_FEED_URIS` | 6042 | :term:`PACKAGE_FEED_URIS` |
5227 | Specifies the front portion of the package feed URI used by the | 6043 | Specifies the front portion of the package feed URI used by the |
5228 | OpenEmbedded build system. Each final package feed URI is comprised | 6044 | OpenEmbedded build system. Each final package feed URI is comprised |
5229 | of ``PACKAGE_FEED_URIS``, | 6045 | of :term:`PACKAGE_FEED_URIS`, |
5230 | :term:`PACKAGE_FEED_BASE_PATHS`, and | 6046 | :term:`PACKAGE_FEED_BASE_PATHS`, and |
5231 | :term:`PACKAGE_FEED_ARCHS` variables. | 6047 | :term:`PACKAGE_FEED_ARCHS` variables. |
5232 | 6048 | ||
5233 | Consider the following example where the ``PACKAGE_FEED_URIS``, | 6049 | Consider the following example where the :term:`PACKAGE_FEED_URIS`, |
5234 | ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are | 6050 | :term:`PACKAGE_FEED_BASE_PATHS`, and :term:`PACKAGE_FEED_ARCHS` variables are |
5235 | defined in your ``local.conf`` file: | 6051 | defined in your ``local.conf`` file:: |
5236 | :: | ||
5237 | 6052 | ||
5238 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ | 6053 | PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \ |
5239 | https://example.com/packagerepos/updates" | 6054 | https://example.com/packagerepos/updates" |
@@ -5258,16 +6073,16 @@ system and gives an overview of their function and contents. | |||
5258 | installation into the image. | 6073 | installation into the image. |
5259 | 6074 | ||
5260 | Because the package manager controls actual installation of all | 6075 | Because the package manager controls actual installation of all |
5261 | packages, the list of packages passed using ``PACKAGE_INSTALL`` is | 6076 | packages, the list of packages passed using :term:`PACKAGE_INSTALL` is |
5262 | not the final list of packages that are actually installed. This | 6077 | not the final list of packages that are actually installed. This |
5263 | variable is internal to the image construction code. Consequently, in | 6078 | variable is internal to the image construction code. Consequently, in |
5264 | general, you should use the | 6079 | general, you should use the |
5265 | :term:`IMAGE_INSTALL` variable to specify | 6080 | :term:`IMAGE_INSTALL` variable to specify |
5266 | packages for installation. The exception to this is when working with | 6081 | packages for installation. The exception to this is when working with |
5267 | the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` | 6082 | the :ref:`core-image-minimal-initramfs <ref-manual/images:images>` |
5268 | image. When working with an initial RAM filesystem (initramfs) image, | 6083 | image. When working with an initial RAM filesystem (:term:`Initramfs`) image, |
5269 | use the ``PACKAGE_INSTALL`` variable. For information on creating an | 6084 | use the :term:`PACKAGE_INSTALL` variable. For information on creating an |
5270 | initramfs, see the ":ref:`dev-manual/common-tasks:building an initial ram filesystem (initramfs) image`" section | 6085 | :term:`Initramfs`, see the ":ref:`dev-manual/building:building an initial ram filesystem (Initramfs) image`" section |
5271 | in the Yocto Project Development Tasks Manual. | 6086 | in the Yocto Project Development Tasks Manual. |
5272 | 6087 | ||
5273 | :term:`PACKAGE_INSTALL_ATTEMPTONLY` | 6088 | :term:`PACKAGE_INSTALL_ATTEMPTONLY` |
@@ -5284,22 +6099,21 @@ system and gives an overview of their function and contents. | |||
5284 | :term:`PACKAGE_WRITE_DEPS` | 6099 | :term:`PACKAGE_WRITE_DEPS` |
5285 | Specifies a list of dependencies for post-installation and | 6100 | Specifies a list of dependencies for post-installation and |
5286 | pre-installation scripts on native/cross tools. If your | 6101 | pre-installation scripts on native/cross tools. If your |
5287 | post-installation or pre-installation script can execute at rootfs | 6102 | post-installation or pre-installation script can execute at root filesystem |
5288 | creation time rather than on the target but depends on a native tool | 6103 | creation time rather than on the target but depends on a native tool |
5289 | in order to execute, you need to list the tools in | 6104 | in order to execute, you need to list the tools in |
5290 | ``PACKAGE_WRITE_DEPS``. | 6105 | :term:`PACKAGE_WRITE_DEPS`. |
5291 | 6106 | ||
5292 | For information on running post-installation scripts, see the | 6107 | For information on running post-installation scripts, see the |
5293 | ":ref:`dev-manual/common-tasks:post-installation scripts`" | 6108 | ":ref:`dev-manual/new-recipe:post-installation scripts`" |
5294 | section in the Yocto Project Development Tasks Manual. | 6109 | section in the Yocto Project Development Tasks Manual. |
5295 | 6110 | ||
5296 | :term:`PACKAGECONFIG` | 6111 | :term:`PACKAGECONFIG` |
5297 | This variable provides a means of enabling or disabling features of a | 6112 | This variable provides a means of enabling or disabling features of a |
5298 | recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in | 6113 | recipe on a per-recipe basis. :term:`PACKAGECONFIG` blocks are defined in |
5299 | recipes when you specify features and then arguments that define | 6114 | recipes when you specify features and then arguments that define |
5300 | feature behaviors. Here is the basic block structure (broken over | 6115 | feature behaviors. Here is the basic block structure (broken over |
5301 | multiple lines for readability): | 6116 | multiple lines for readability):: |
5302 | :: | ||
5303 | 6117 | ||
5304 | PACKAGECONFIG ??= "f1 f2 f3 ..." | 6118 | PACKAGECONFIG ??= "f1 f2 f3 ..." |
5305 | PACKAGECONFIG[f1] = "\ | 6119 | PACKAGECONFIG[f1] = "\ |
@@ -5312,117 +6126,140 @@ system and gives an overview of their function and contents. | |||
5312 | PACKAGECONFIG[f2] = "\ | 6126 | PACKAGECONFIG[f2] = "\ |
5313 | ... and so on and so on ... | 6127 | ... and so on and so on ... |
5314 | 6128 | ||
5315 | The ``PACKAGECONFIG`` variable itself specifies a space-separated | 6129 | The :term:`PACKAGECONFIG` variable itself specifies a space-separated |
5316 | list of the features to enable. Following the features, you can | 6130 | list of the features to enable. Following the features, you can |
5317 | determine the behavior of each feature by providing up to six | 6131 | determine the behavior of each feature by providing up to six |
5318 | order-dependent arguments, which are separated by commas. You can | 6132 | order-dependent arguments, which are separated by commas. You can |
5319 | omit any argument you like but must retain the separating commas. The | 6133 | omit any argument you like but must retain the separating commas. The |
5320 | order is important and specifies the following: | 6134 | order is important and specifies the following: |
5321 | 6135 | ||
5322 | 1. Extra arguments that should be added to the configure script | 6136 | #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` |
5323 | argument list (:term:`EXTRA_OECONF` or | 6137 | if the feature is enabled. |
5324 | :term:`PACKAGECONFIG_CONFARGS`) if | ||
5325 | the feature is enabled. | ||
5326 | 6138 | ||
5327 | 2. Extra arguments that should be added to ``EXTRA_OECONF`` or | 6139 | #. Extra arguments that should be added to :term:`PACKAGECONFIG_CONFARGS` |
5328 | ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. | 6140 | if the feature is disabled. |
5329 | 6141 | ||
5330 | 3. Additional build dependencies (:term:`DEPENDS`) | 6142 | #. Additional build dependencies (:term:`DEPENDS`) |
5331 | that should be added if the feature is enabled. | 6143 | that should be added if the feature is enabled. |
5332 | 6144 | ||
5333 | 4. Additional runtime dependencies (:term:`RDEPENDS`) | 6145 | #. Additional runtime dependencies (:term:`RDEPENDS`) |
5334 | that should be added if the feature is enabled. | 6146 | that should be added if the feature is enabled. |
5335 | 6147 | ||
5336 | 5. Additional runtime recommendations | 6148 | #. Additional runtime recommendations |
5337 | (:term:`RRECOMMENDS`) that should be added if | 6149 | (:term:`RRECOMMENDS`) that should be added if |
5338 | the feature is enabled. | 6150 | the feature is enabled. |
5339 | 6151 | ||
5340 | 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` | 6152 | #. Any conflicting (that is, mutually exclusive) :term:`PACKAGECONFIG` |
5341 | settings for this feature. | 6153 | settings for this feature. |
5342 | 6154 | ||
5343 | Consider the following ``PACKAGECONFIG`` block taken from the | 6155 | Consider the following :term:`PACKAGECONFIG` block taken from the |
5344 | ``librsvg`` recipe. In this example the feature is ``gtk``, which has | 6156 | ``librsvg`` recipe. In this example the feature is ``gtk``, which has |
5345 | three arguments that determine the feature's behavior. | 6157 | three arguments that determine the feature's behavior:: |
5346 | :: | ||
5347 | 6158 | ||
5348 | PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" | 6159 | PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" |
5349 | 6160 | ||
5350 | The | 6161 | The |
5351 | ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is | 6162 | ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is |
5352 | enabled. In this case, ``--with-gtk3`` is added to the configure | 6163 | enabled. In this case, ``--with-gtk3`` is added to the configure |
5353 | script argument list and ``gtk+3`` is added to ``DEPENDS``. On the | 6164 | script argument list and ``gtk+3`` is added to :term:`DEPENDS`. On the |
5354 | other hand, if the feature is disabled say through a ``.bbappend`` | 6165 | other hand, if the feature is disabled say through a ``.bbappend`` |
5355 | file in another layer, then the second argument ``--without-gtk3`` is | 6166 | file in another layer, then the second argument ``--without-gtk3`` is |
5356 | added to the configure script instead. | 6167 | added to the configure script instead. |
5357 | 6168 | ||
5358 | The basic ``PACKAGECONFIG`` structure previously described holds true | 6169 | The basic :term:`PACKAGECONFIG` structure previously described holds true |
5359 | regardless of whether you are creating a block or changing a block. | 6170 | regardless of whether you are creating a block or changing a block. |
5360 | When creating a block, use the structure inside your recipe. | 6171 | When creating a block, use the structure inside your recipe. |
5361 | 6172 | ||
5362 | If you want to change an existing ``PACKAGECONFIG`` block, you can do | 6173 | If you want to change an existing :term:`PACKAGECONFIG` block, you can do |
5363 | so one of two ways: | 6174 | so one of two ways: |
5364 | 6175 | ||
5365 | - *Append file:* Create an append file named | 6176 | - *Append file:* Create an append file named |
5366 | recipename\ ``.bbappend`` in your layer and override the value of | 6177 | ``recipename.bbappend`` in your layer and override the value of |
5367 | ``PACKAGECONFIG``. You can either completely override the | 6178 | :term:`PACKAGECONFIG`. You can either completely override the |
5368 | variable: | 6179 | variable:: |
5369 | :: | ||
5370 | 6180 | ||
5371 | PACKAGECONFIG = "f4 f5" | 6181 | PACKAGECONFIG = "f4 f5" |
5372 | 6182 | ||
5373 | Or, you can just append the variable: | 6183 | Or, you can just append the variable:: |
5374 | :: | ||
5375 | 6184 | ||
5376 | PACKAGECONFIG_append = " f4" | 6185 | PACKAGECONFIG:append = " f4" |
5377 | 6186 | ||
5378 | - *Configuration file:* This method is identical to changing the | 6187 | - *Configuration file:* This method is identical to changing the |
5379 | block through an append file except you edit your ``local.conf`` | 6188 | block through an append file except you edit your ``local.conf`` |
5380 | or ``mydistro.conf`` file. As with append files previously | 6189 | or ``mydistro.conf`` file. As with append files previously |
5381 | described, you can either completely override the variable: | 6190 | described, you can either completely override the variable:: |
5382 | :: | 6191 | |
6192 | PACKAGECONFIG:pn-recipename = "f4 f5" | ||
6193 | |||
6194 | Or, you can just amend the variable:: | ||
6195 | |||
6196 | PACKAGECONFIG:append:pn-recipename = " f4" | ||
6197 | |||
6198 | Consider the following example of a :ref:`ref-classes-cmake` recipe with a systemd service | ||
6199 | in which :term:`PACKAGECONFIG` is used to transform the systemd service | ||
6200 | into a feature that can be easily enabled or disabled via :term:`PACKAGECONFIG`:: | ||
6201 | |||
6202 | example.c | ||
6203 | example.service | ||
6204 | CMakeLists.txt | ||
5383 | 6205 | ||
5384 | PACKAGECONFIG_pn-recipename = "f4 f5" | 6206 | The ``CMakeLists.txt`` file contains:: |
5385 | 6207 | ||
5386 | Or, you can just amend the variable: | 6208 | if(WITH_SYSTEMD) |
5387 | :: | 6209 | install(FILES ${PROJECT_SOURCE_DIR}/example.service DESTINATION /etc/systemd/systemd) |
6210 | endif(WITH_SYSTEMD) | ||
5388 | 6211 | ||
5389 | PACKAGECONFIG_append_pn-recipename = " f4" | 6212 | In order to enable the installation of ``example.service`` we need to |
6213 | ensure that ``-DWITH_SYSTEMD=ON`` is passed to the ``cmake`` command | ||
6214 | execution. Recipes that have ``CMakeLists.txt`` generally inherit the | ||
6215 | :ref:`ref-classes-cmake` class, that runs ``cmake`` with | ||
6216 | :term:`EXTRA_OECMAKE`, which :term:`PACKAGECONFIG_CONFARGS` will be | ||
6217 | appended to. Now, knowing that :term:`PACKAGECONFIG_CONFARGS` is | ||
6218 | automatically filled with either the first or second element of | ||
6219 | :term:`PACKAGECONFIG` flag value, the recipe would be like:: | ||
6220 | |||
6221 | inherit cmake | ||
6222 | PACKAGECONFIG = "systemd" | ||
6223 | PACKAGECONFIG[systemd] = "-DWITH_SYSTEMD=ON,-DWITH_SYSTEMD=OFF" | ||
6224 | |||
6225 | A side note to this recipe is to check if ``systemd`` is in fact the used :term:`INIT_MANAGER` | ||
6226 | or not:: | ||
6227 | |||
6228 | PACKAGECONFIG = "${@'systemd' if d.getVar('INIT_MANAGER') == 'systemd' else ''}" | ||
5390 | 6229 | ||
5391 | :term:`PACKAGECONFIG_CONFARGS` | 6230 | :term:`PACKAGECONFIG_CONFARGS` |
5392 | A space-separated list of configuration options generated from the | 6231 | A space-separated list of configuration options generated from the |
5393 | :term:`PACKAGECONFIG` setting. | 6232 | :term:`PACKAGECONFIG` setting. |
5394 | 6233 | ||
5395 | Classes such as :ref:`autotools <ref-classes-autotools>` and | 6234 | Classes such as :ref:`ref-classes-autotools` and :ref:`ref-classes-cmake` |
5396 | :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to | 6235 | use :term:`PACKAGECONFIG_CONFARGS` to pass :term:`PACKAGECONFIG` options |
5397 | pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, | 6236 | to ``configure`` and ``cmake``, respectively. If you are using |
5398 | respectively. If you are using ``PACKAGECONFIG`` but not a class that | 6237 | :term:`PACKAGECONFIG` but not a class that handles the |
5399 | handles the ``do_configure`` task, then you need to use | 6238 | :ref:`ref-tasks-configure` task, then you need to use |
5400 | ``PACKAGECONFIG_CONFARGS`` appropriately. | 6239 | :term:`PACKAGECONFIG_CONFARGS` appropriately. |
5401 | 6240 | ||
5402 | :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` | 6241 | :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` |
5403 | For recipes inheriting the | 6242 | For recipes inheriting the :ref:`ref-classes-packagegroup` class, setting |
5404 | :ref:`packagegroup <ref-classes-packagegroup>` class, setting | 6243 | :term:`PACKAGEGROUP_DISABLE_COMPLEMENTARY` to "1" specifies that the |
5405 | ``PACKAGEGROUP_DISABLE_COMPLEMENTARY`` to "1" specifies that the | ||
5406 | normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) | 6244 | normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) |
5407 | should not be automatically created by the ``packagegroup`` recipe, | 6245 | should not be automatically created by the ``packagegroup`` recipe, |
5408 | which is the default behavior. | 6246 | which is the default behavior. |
5409 | 6247 | ||
5410 | :term:`PACKAGES` | 6248 | :term:`PACKAGES` |
5411 | The list of packages the recipe creates. The default value is the | 6249 | The list of packages the recipe creates. The default value is the |
5412 | following: | 6250 | following:: |
5413 | :: | ||
5414 | 6251 | ||
5415 | ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} | 6252 | ${PN}-src ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN} |
5416 | 6253 | ||
5417 | During packaging, the :ref:`ref-tasks-package` task | 6254 | During packaging, the :ref:`ref-tasks-package` task |
5418 | goes through ``PACKAGES`` and uses the :term:`FILES` | 6255 | goes through :term:`PACKAGES` and uses the :term:`FILES` |
5419 | variable corresponding to each package to assign files to the | 6256 | variable corresponding to each package to assign files to the |
5420 | package. If a file matches the ``FILES`` variable for more than one | 6257 | package. If a file matches the :term:`FILES` variable for more than one |
5421 | package in ``PACKAGES``, it will be assigned to the earliest | 6258 | package in :term:`PACKAGES`, it will be assigned to the earliest |
5422 | (leftmost) package. | 6259 | (leftmost) package. |
5423 | 6260 | ||
5424 | Packages in the variable's list that are empty (i.e. where none of | 6261 | Packages in the variable's list that are empty (i.e. where none of |
5425 | the patterns in ``FILES_``\ pkg match any files installed by the | 6262 | the patterns in ``FILES:``\ pkg match any files installed by the |
5426 | :ref:`ref-tasks-install` task) are not generated, | 6263 | :ref:`ref-tasks-install` task) are not generated, |
5427 | unless generation is forced through the | 6264 | unless generation is forced through the |
5428 | :term:`ALLOW_EMPTY` variable. | 6265 | :term:`ALLOW_EMPTY` variable. |
@@ -5430,10 +6267,10 @@ system and gives an overview of their function and contents. | |||
5430 | :term:`PACKAGES_DYNAMIC` | 6267 | :term:`PACKAGES_DYNAMIC` |
5431 | A promise that your recipe satisfies runtime dependencies for | 6268 | A promise that your recipe satisfies runtime dependencies for |
5432 | optional modules that are found in other recipes. | 6269 | optional modules that are found in other recipes. |
5433 | ``PACKAGES_DYNAMIC`` does not actually satisfy the dependencies, it | 6270 | :term:`PACKAGES_DYNAMIC` does not actually satisfy the dependencies, it |
5434 | only states that they should be satisfied. For example, if a hard, | 6271 | only states that they should be satisfied. For example, if a hard, |
5435 | runtime dependency (:term:`RDEPENDS`) of another | 6272 | runtime dependency (:term:`RDEPENDS`) of another |
5436 | package is satisfied at build time through the ``PACKAGES_DYNAMIC`` | 6273 | package is satisfied at build time through the :term:`PACKAGES_DYNAMIC` |
5437 | variable, but a package with the module name is never actually | 6274 | variable, but a package with the module name is never actually |
5438 | produced, then the other package will be broken. Thus, if you attempt | 6275 | produced, then the other package will be broken. Thus, if you attempt |
5439 | to include that package in an image, you will get a dependency | 6276 | to include that package in an image, you will get a dependency |
@@ -5443,11 +6280,11 @@ system and gives an overview of their function and contents. | |||
5443 | Typically, if there is a chance that such a situation can occur and | 6280 | Typically, if there is a chance that such a situation can occur and |
5444 | the package that is not created is valid without the dependency being | 6281 | the package that is not created is valid without the dependency being |
5445 | satisfied, then you should use :term:`RRECOMMENDS` | 6282 | satisfied, then you should use :term:`RRECOMMENDS` |
5446 | (a soft runtime dependency) instead of ``RDEPENDS``. | 6283 | (a soft runtime dependency) instead of :term:`RDEPENDS`. |
5447 | 6284 | ||
5448 | For an example of how to use the ``PACKAGES_DYNAMIC`` variable when | 6285 | For an example of how to use the :term:`PACKAGES_DYNAMIC` variable when |
5449 | you are splitting packages, see the | 6286 | you are splitting packages, see the |
5450 | ":ref:`dev-manual/common-tasks:handling optional module packaging`" | 6287 | ":ref:`dev-manual/packages:handling optional module packaging`" |
5451 | section in the Yocto Project Development Tasks Manual. | 6288 | section in the Yocto Project Development Tasks Manual. |
5452 | 6289 | ||
5453 | :term:`PACKAGESPLITFUNCS` | 6290 | :term:`PACKAGESPLITFUNCS` |
@@ -5461,17 +6298,20 @@ system and gives an overview of their function and contents. | |||
5461 | desired splitting. | 6298 | desired splitting. |
5462 | 6299 | ||
5463 | :term:`PARALLEL_MAKE` | 6300 | :term:`PARALLEL_MAKE` |
5464 | Extra options passed to the ``make`` command during the | 6301 | |
5465 | :ref:`ref-tasks-compile` task in order to specify | 6302 | Extra options passed to the build tool command (``make``, |
5466 | parallel compilation on the local build host. This variable is | 6303 | ``ninja`` or more specific build engines, like the Go language one) |
5467 | usually in the form "-j x", where x represents the maximum number of | 6304 | during the :ref:`ref-tasks-compile` task, to specify parallel compilation |
5468 | parallel threads ``make`` can run. | 6305 | on the local build host. This variable is usually in the form "-j x", |
6306 | where x represents the maximum number of parallel threads such engines | ||
6307 | can run. | ||
5469 | 6308 | ||
5470 | .. note:: | 6309 | .. note:: |
5471 | 6310 | ||
5472 | In order for ``PARALLEL_MAKE`` to be effective, ``make`` must be | 6311 | For software compiled by ``make``, in order for :term:`PARALLEL_MAKE` |
5473 | called with ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy way to ensure | 6312 | to be effective, ``make`` must be called with |
5474 | this is to use the ``oe_runmake`` function. | 6313 | ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy |
6314 | way to ensure this is to use the ``oe_runmake`` function. | ||
5475 | 6315 | ||
5476 | By default, the OpenEmbedded build system automatically sets this | 6316 | By default, the OpenEmbedded build system automatically sets this |
5477 | variable to be equal to the number of cores the build system uses. | 6317 | variable to be equal to the number of cores the build system uses. |
@@ -5479,40 +6319,41 @@ system and gives an overview of their function and contents. | |||
5479 | .. note:: | 6319 | .. note:: |
5480 | 6320 | ||
5481 | If the software being built experiences dependency issues during | 6321 | If the software being built experiences dependency issues during |
5482 | the ``do_compile`` task that result in race conditions, you can clear | 6322 | the :ref:`ref-tasks-compile` task that result in race conditions, you can clear |
5483 | the ``PARALLEL_MAKE`` variable within the recipe as a workaround. For | 6323 | the :term:`PARALLEL_MAKE` variable within the recipe as a workaround. For |
5484 | information on addressing race conditions, see the | 6324 | information on addressing race conditions, see the |
5485 | ":ref:`dev-manual/common-tasks:debugging parallel make races`" | 6325 | ":ref:`dev-manual/debugging:debugging parallel make races`" |
5486 | section in the Yocto Project Development Tasks Manual. | 6326 | section in the Yocto Project Development Tasks Manual. |
5487 | 6327 | ||
5488 | For single socket systems (i.e. one CPU), you should not have to | 6328 | For single socket systems (i.e. one CPU), you should not have to |
5489 | override this variable to gain optimal parallelism during builds. | 6329 | override this variable to gain optimal parallelism during builds. |
5490 | However, if you have very large systems that employ multiple physical | 6330 | However, if you have very large systems that employ multiple physical |
5491 | CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is | 6331 | CPUs, you might want to make sure the :term:`PARALLEL_MAKE` variable is |
5492 | not set higher than "-j 20". | 6332 | not set higher than "-j 20". |
5493 | 6333 | ||
5494 | For more information on speeding up builds, see the | 6334 | For more information on speeding up builds, see the |
5495 | ":ref:`dev-manual/common-tasks:speeding up a build`" | 6335 | ":ref:`dev-manual/speeding-up-build:speeding up a build`" |
5496 | section in the Yocto Project Development Tasks Manual. | 6336 | section in the Yocto Project Development Tasks Manual. |
5497 | 6337 | ||
5498 | :term:`PARALLEL_MAKEINST` | 6338 | :term:`PARALLEL_MAKEINST` |
5499 | Extra options passed to the ``make install`` command during the | 6339 | Extra options passed to the build tool install command |
5500 | :ref:`ref-tasks-install` task in order to specify | 6340 | (``make install``, ``ninja install`` or more specific ones) |
6341 | during the :ref:`ref-tasks-install` task in order to specify | ||
5501 | parallel installation. This variable defaults to the value of | 6342 | parallel installation. This variable defaults to the value of |
5502 | :term:`PARALLEL_MAKE`. | 6343 | :term:`PARALLEL_MAKE`. |
5503 | 6344 | ||
5504 | .. note:: | 6345 | .. note:: |
5505 | 6346 | ||
5506 | In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must | 6347 | For software compiled by ``make``, in order for :term:`PARALLEL_MAKEINST` |
5507 | be called with | 6348 | to be effective, ``make`` must be called with |
5508 | ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy | 6349 | ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy |
5509 | way to ensure this is to use the ``oe_runmake`` function. | 6350 | way to ensure this is to use the ``oe_runmake`` function. |
5510 | 6351 | ||
5511 | If the software being built experiences dependency issues during | 6352 | If the software being built experiences dependency issues during |
5512 | the ``do_install`` task that result in race conditions, you can | 6353 | the :ref:`ref-tasks-install` task that result in race conditions, you can |
5513 | clear the ``PARALLEL_MAKEINST`` variable within the recipe as a | 6354 | clear the :term:`PARALLEL_MAKEINST` variable within the recipe as a |
5514 | workaround. For information on addressing race conditions, see the | 6355 | workaround. For information on addressing race conditions, see the |
5515 | ":ref:`dev-manual/common-tasks:debugging parallel make races`" | 6356 | ":ref:`dev-manual/debugging:debugging parallel make races`" |
5516 | section in the Yocto Project Development Tasks Manual. | 6357 | section in the Yocto Project Development Tasks Manual. |
5517 | 6358 | ||
5518 | :term:`PATCHRESOLVE` | 6359 | :term:`PATCHRESOLVE` |
@@ -5536,8 +6377,7 @@ system and gives an overview of their function and contents. | |||
5536 | patched, it uses "patch". | 6377 | patched, it uses "patch". |
5537 | 6378 | ||
5538 | If you wish to use an alternative patching tool, set the variable in | 6379 | If you wish to use an alternative patching tool, set the variable in |
5539 | the recipe using one of the following: | 6380 | the recipe using one of the following:: |
5540 | :: | ||
5541 | 6381 | ||
5542 | PATCHTOOL = "patch" | 6382 | PATCHTOOL = "patch" |
5543 | PATCHTOOL = "quilt" | 6383 | PATCHTOOL = "quilt" |
@@ -5548,7 +6388,15 @@ system and gives an overview of their function and contents. | |||
5548 | variable is used to make upgrades possible when the versioning scheme | 6388 | variable is used to make upgrades possible when the versioning scheme |
5549 | changes in some backwards incompatible way. | 6389 | changes in some backwards incompatible way. |
5550 | 6390 | ||
5551 | ``PE`` is the default value of the :term:`PKGE` variable. | 6391 | :term:`PE` is the default value of the :term:`PKGE` variable. |
6392 | |||
6393 | :term:`PEP517_WHEEL_PATH` | ||
6394 | When used by recipes that inherit the :ref:`ref-classes-python_pep517` | ||
6395 | class, denotes the path to ``dist/`` (short for distribution) where the | ||
6396 | binary archive ``wheel`` is built. | ||
6397 | |||
6398 | :term:`PERSISTENT_DIR` | ||
6399 | See :term:`bitbake:PERSISTENT_DIR` in the BitBake manual. | ||
5552 | 6400 | ||
5553 | :term:`PF` | 6401 | :term:`PF` |
5554 | Specifies the recipe or package name and includes all version and | 6402 | Specifies the recipe or package name and includes all version and |
@@ -5557,10 +6405,11 @@ system and gives an overview of their function and contents. | |||
5557 | ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} | 6405 | ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} |
5558 | 6406 | ||
5559 | :term:`PIXBUF_PACKAGES` | 6407 | :term:`PIXBUF_PACKAGES` |
5560 | When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` | 6408 | When inheriting the :ref:`ref-classes-pixbufcache` |
5561 | class, this variable identifies packages that contain the pixbuf | 6409 | class, this variable identifies packages that contain the pixbuf |
5562 | loaders used with ``gdk-pixbuf``. By default, the ``pixbufcache`` | 6410 | loaders used with ``gdk-pixbuf``. By default, the |
5563 | class assumes that the loaders are in the recipe's main package (i.e. | 6411 | :ref:`ref-classes-pixbufcache` class assumes that |
6412 | the loaders are in the recipe's main package (i.e. | ||
5564 | ``${``\ :term:`PN`\ ``}``). Use this variable if the | 6413 | ``${``\ :term:`PN`\ ``}``). Use this variable if the |
5565 | loaders you need are in a package other than that main package. | 6414 | loaders you need are in a package other than that main package. |
5566 | 6415 | ||
@@ -5570,11 +6419,10 @@ system and gives an overview of their function and contents. | |||
5570 | 6419 | ||
5571 | .. note:: | 6420 | .. note:: |
5572 | 6421 | ||
5573 | When using the ``PKG`` variable, you must use a package name override. | 6422 | When using the :term:`PKG` variable, you must use a package name override. |
5574 | 6423 | ||
5575 | For example, when the :ref:`debian <ref-classes-debian>` class | 6424 | For example, when the :ref:`ref-classes-debian` class renames the output |
5576 | renames the output package, it does so by setting | 6425 | package, it does so by setting ``PKG:packagename``. |
5577 | ``PKG_packagename``. | ||
5578 | 6426 | ||
5579 | :term:`PKG_CONFIG_PATH` | 6427 | :term:`PKG_CONFIG_PATH` |
5580 | The path to ``pkg-config`` files for the current build context. | 6428 | The path to ``pkg-config`` files for the current build context. |
@@ -5583,8 +6431,7 @@ system and gives an overview of their function and contents. | |||
5583 | :term:`PKGD` | 6431 | :term:`PKGD` |
5584 | Points to the destination directory for files to be packaged before | 6432 | Points to the destination directory for files to be packaged before |
5585 | they are split into individual packages. This directory defaults to | 6433 | they are split into individual packages. This directory defaults to |
5586 | the following: | 6434 | the following:: |
5587 | :: | ||
5588 | 6435 | ||
5589 | ${WORKDIR}/package | 6436 | ${WORKDIR}/package |
5590 | 6437 | ||
@@ -5596,15 +6443,14 @@ system and gives an overview of their function and contents. | |||
5596 | :ref:`ref-tasks-packagedata` task packages data | 6443 | :ref:`ref-tasks-packagedata` task packages data |
5597 | for each recipe and installs it into this temporary, shared area. | 6444 | for each recipe and installs it into this temporary, shared area. |
5598 | This directory defaults to the following, which you should not | 6445 | This directory defaults to the following, which you should not |
5599 | change: | 6446 | change:: |
5600 | :: | ||
5601 | 6447 | ||
5602 | ${STAGING_DIR_HOST}/pkgdata | 6448 | ${STAGING_DIR_HOST}/pkgdata |
5603 | 6449 | ||
5604 | For examples of how this data is used, see the | 6450 | For examples of how this data is used, see the |
5605 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | 6451 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" |
5606 | section in the Yocto Project Overview and Concepts Manual and the | 6452 | section in the Yocto Project Overview and Concepts Manual and the |
5607 | ":ref:`dev-manual/common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``" | 6453 | ":ref:`dev-manual/debugging:viewing package information with \`\`oe-pkgdata-util\`\``" |
5608 | section in the Yocto Project Development Tasks Manual. For more | 6454 | section in the Yocto Project Development Tasks Manual. For more |
5609 | information on the shared, global-state directory, see | 6455 | information on the shared, global-state directory, see |
5610 | :term:`STAGING_DIR_HOST`. | 6456 | :term:`STAGING_DIR_HOST`. |
@@ -5612,8 +6458,7 @@ system and gives an overview of their function and contents. | |||
5612 | :term:`PKGDEST` | 6458 | :term:`PKGDEST` |
5613 | Points to the parent directory for files to be packaged after they | 6459 | Points to the parent directory for files to be packaged after they |
5614 | have been split into individual packages. This directory defaults to | 6460 | have been split into individual packages. This directory defaults to |
5615 | the following: | 6461 | the following:: |
5616 | :: | ||
5617 | 6462 | ||
5618 | ${WORKDIR}/packages-split | 6463 | ${WORKDIR}/packages-split |
5619 | 6464 | ||
@@ -5624,68 +6469,53 @@ system and gives an overview of their function and contents. | |||
5624 | :term:`PKGDESTWORK` | 6469 | :term:`PKGDESTWORK` |
5625 | Points to a temporary work area where the | 6470 | Points to a temporary work area where the |
5626 | :ref:`ref-tasks-package` task saves package metadata. | 6471 | :ref:`ref-tasks-package` task saves package metadata. |
5627 | The ``PKGDESTWORK`` location defaults to the following: | 6472 | The :term:`PKGDESTWORK` location defaults to the following:: |
5628 | :: | ||
5629 | 6473 | ||
5630 | ${WORKDIR}/pkgdata | 6474 | ${WORKDIR}/pkgdata |
5631 | 6475 | ||
5632 | Do not change this default. | 6476 | Do not change this default. |
5633 | 6477 | ||
5634 | The :ref:`ref-tasks-packagedata` task copies the | 6478 | The :ref:`ref-tasks-packagedata` task copies the |
5635 | package metadata from ``PKGDESTWORK`` to | 6479 | package metadata from :term:`PKGDESTWORK` to |
5636 | :term:`PKGDATA_DIR` to make it available globally. | 6480 | :term:`PKGDATA_DIR` to make it available globally. |
5637 | 6481 | ||
5638 | :term:`PKGE` | 6482 | :term:`PKGE` |
5639 | The epoch of the package(s) built by the recipe. By default, ``PKGE`` | 6483 | The epoch of the package(s) built by the recipe. By default, :term:`PKGE` |
5640 | is set to :term:`PE`. | 6484 | is set to :term:`PE`. |
5641 | 6485 | ||
5642 | :term:`PKGR` | 6486 | :term:`PKGR` |
5643 | The revision of the package(s) built by the recipe. By default, | 6487 | The revision of the package(s) built by the recipe. By default, |
5644 | ``PKGR`` is set to :term:`PR`. | 6488 | :term:`PKGR` is set to :term:`PR`. |
5645 | 6489 | ||
5646 | :term:`PKGV` | 6490 | :term:`PKGV` |
5647 | The version of the package(s) built by the recipe. By default, | 6491 | The version of the package(s) built by the recipe. By default, |
5648 | ``PKGV`` is set to :term:`PV`. | 6492 | :term:`PKGV` is set to :term:`PV`. |
5649 | 6493 | ||
5650 | :term:`PN` | 6494 | :term:`PN` |
5651 | This variable can have two separate functions depending on the | 6495 | This variable can have two separate functions depending on the |
5652 | context: a recipe name or a resulting package name. | 6496 | context: a recipe name or a resulting package name. |
5653 | 6497 | ||
5654 | ``PN`` refers to a recipe name in the context of a file used by the | 6498 | :term:`PN` refers to a recipe name in the context of a file used by the |
5655 | OpenEmbedded build system as input to create a package. The name is | 6499 | OpenEmbedded build system as input to create a package. The name is |
5656 | normally extracted from the recipe file name. For example, if the | 6500 | normally extracted from the recipe file name. For example, if the |
5657 | recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` | 6501 | recipe is named ``expat_2.0.1.bb``, then the default value of :term:`PN` |
5658 | will be "expat". | 6502 | will be "expat". |
5659 | 6503 | ||
5660 | The variable refers to a package name in the context of a file | 6504 | The variable refers to a package name in the context of a file |
5661 | created or produced by the OpenEmbedded build system. | 6505 | created or produced by the OpenEmbedded build system. |
5662 | 6506 | ||
5663 | If applicable, the ``PN`` variable also contains any special suffix | 6507 | If applicable, the :term:`PN` variable also contains any special suffix |
5664 | or prefix. For example, using ``bash`` to build packages for the | 6508 | or prefix. For example, using ``bash`` to build packages for the |
5665 | native machine, ``PN`` is ``bash-native``. Using ``bash`` to build | 6509 | native machine, :term:`PN` is ``bash-native``. Using ``bash`` to build |
5666 | packages for the target and for Multilib, ``PN`` would be ``bash`` | 6510 | packages for the target and for Multilib, :term:`PN` would be ``bash`` |
5667 | and ``lib64-bash``, respectively. | 6511 | and ``lib64-bash``, respectively. |
5668 | 6512 | ||
5669 | :term:`PNBLACKLIST` | ||
5670 | Lists recipes you do not want the OpenEmbedded build system to build. | ||
5671 | This variable works in conjunction with the | ||
5672 | :ref:`blacklist <ref-classes-blacklist>` class, which is inherited | ||
5673 | globally. | ||
5674 | |||
5675 | To prevent a recipe from being built, use the ``PNBLACKLIST`` | ||
5676 | variable in your ``local.conf`` file. Here is an example that | ||
5677 | prevents ``myrecipe`` from being built: | ||
5678 | :: | ||
5679 | |||
5680 | PNBLACKLIST[myrecipe] = "Not supported by our organization." | ||
5681 | |||
5682 | :term:`POPULATE_SDK_POST_HOST_COMMAND` | 6513 | :term:`POPULATE_SDK_POST_HOST_COMMAND` |
5683 | Specifies a list of functions to call once the OpenEmbedded build | 6514 | Specifies a list of functions to call once the OpenEmbedded build |
5684 | system has created the host part of the SDK. You can specify | 6515 | system has created the host part of the SDK. You can specify |
5685 | functions separated by semicolons: | 6516 | functions separated by spaces:: |
5686 | :: | ||
5687 | 6517 | ||
5688 | POPULATE_SDK_POST_HOST_COMMAND += "function; ... " | 6518 | POPULATE_SDK_POST_HOST_COMMAND += "function" |
5689 | 6519 | ||
5690 | If you need to pass the SDK path to a command within a function, you | 6520 | If you need to pass the SDK path to a command within a function, you |
5691 | can use ``${SDK_DIR}``, which points to the parent directory used by | 6521 | can use ``${SDK_DIR}``, which points to the parent directory used by |
@@ -5695,10 +6525,9 @@ system and gives an overview of their function and contents. | |||
5695 | :term:`POPULATE_SDK_POST_TARGET_COMMAND` | 6525 | :term:`POPULATE_SDK_POST_TARGET_COMMAND` |
5696 | Specifies a list of functions to call once the OpenEmbedded build | 6526 | Specifies a list of functions to call once the OpenEmbedded build |
5697 | system has created the target part of the SDK. You can specify | 6527 | system has created the target part of the SDK. You can specify |
5698 | functions separated by semicolons: | 6528 | functions separated by spaces:: |
5699 | :: | ||
5700 | 6529 | ||
5701 | POPULATE_SDK_POST_TARGET_COMMAND += "function; ... " | 6530 | POPULATE_SDK_POST_TARGET_COMMAND += "function" |
5702 | 6531 | ||
5703 | If you need to pass the SDK path to a command within a function, you | 6532 | If you need to pass the SDK path to a command within a function, you |
5704 | can use ``${SDK_DIR}``, which points to the parent directory used by | 6533 | can use ``${SDK_DIR}``, which points to the parent directory used by |
@@ -5709,35 +6538,35 @@ system and gives an overview of their function and contents. | |||
5709 | The revision of the recipe. The default value for this variable is | 6538 | The revision of the recipe. The default value for this variable is |
5710 | "r0". Subsequent revisions of the recipe conventionally have the | 6539 | "r0". Subsequent revisions of the recipe conventionally have the |
5711 | values "r1", "r2", and so forth. When :term:`PV` increases, | 6540 | values "r1", "r2", and so forth. When :term:`PV` increases, |
5712 | ``PR`` is conventionally reset to "r0". | 6541 | :term:`PR` is conventionally reset to "r0". |
5713 | 6542 | ||
5714 | .. note:: | 6543 | .. note:: |
5715 | 6544 | ||
5716 | The OpenEmbedded build system does not need the aid of ``PR`` | 6545 | The OpenEmbedded build system does not need the aid of :term:`PR` |
5717 | to know when to rebuild a recipe. The build system uses the task | 6546 | to know when to rebuild a recipe. The build system uses the task |
5718 | :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the | 6547 | :ref:`input checksums <overview-manual/concepts:checksums (signatures)>` along with the |
5719 | :ref:`stamp <structure-build-tmp-stamps>` and | 6548 | :ref:`stamp <structure-build-tmp-stamps>` and |
5720 | :ref:`overview-manual/concepts:shared state cache` | 6549 | :ref:`overview-manual/concepts:shared state cache` |
5721 | mechanisms. | 6550 | mechanisms. |
5722 | 6551 | ||
5723 | The ``PR`` variable primarily becomes significant when a package | 6552 | The :term:`PR` variable primarily becomes significant when a package |
5724 | manager dynamically installs packages on an already built image. In | 6553 | manager dynamically installs packages on an already built image. In |
5725 | this case, ``PR``, which is the default value of | 6554 | this case, :term:`PR`, which is the default value of |
5726 | :term:`PKGR`, helps the package manager distinguish which | 6555 | :term:`PKGR`, helps the package manager distinguish which |
5727 | package is the most recent one in cases where many packages have the | 6556 | package is the most recent one in cases where many packages have the |
5728 | same ``PV`` (i.e. ``PKGV``). A component having many packages with | 6557 | same :term:`PV` (i.e. :term:`PKGV`). A component having many packages with |
5729 | the same ``PV`` usually means that the packages all install the same | 6558 | the same :term:`PV` usually means that the packages all install the same |
5730 | upstream version, but with later (``PR``) version packages including | 6559 | upstream version, but with later (:term:`PR`) version packages including |
5731 | packaging fixes. | 6560 | packaging fixes. |
5732 | 6561 | ||
5733 | .. note:: | 6562 | .. note:: |
5734 | 6563 | ||
5735 | ``PR`` does not need to be increased for changes that do not change the | 6564 | :term:`PR` does not need to be increased for changes that do not change the |
5736 | package contents or metadata. | 6565 | package contents or metadata. |
5737 | 6566 | ||
5738 | Because manually managing ``PR`` can be cumbersome and error-prone, | 6567 | Because manually managing :term:`PR` can be cumbersome and error-prone, |
5739 | an automated solution exists. See the | 6568 | an automated solution exists. See the |
5740 | ":ref:`dev-manual/common-tasks:working with a pr service`" section | 6569 | ":ref:`dev-manual/packages:working with a pr service`" section |
5741 | in the Yocto Project Development Tasks Manual for more information. | 6570 | in the Yocto Project Development Tasks Manual for more information. |
5742 | 6571 | ||
5743 | :term:`PREFERRED_PROVIDER` | 6572 | :term:`PREFERRED_PROVIDER` |
@@ -5746,45 +6575,46 @@ system and gives an overview of their function and contents. | |||
5746 | preferred provider). You should always suffix this variable with the | 6575 | preferred provider). You should always suffix this variable with the |
5747 | name of the provided item. And, you should define the variable using | 6576 | name of the provided item. And, you should define the variable using |
5748 | the preferred recipe's name (:term:`PN`). Here is a common | 6577 | the preferred recipe's name (:term:`PN`). Here is a common |
5749 | example: | 6578 | example:: |
5750 | :: | ||
5751 | 6579 | ||
5752 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" | 6580 | PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
5753 | 6581 | ||
5754 | In the previous example, multiple recipes are providing "virtual/kernel". | 6582 | In the previous example, multiple recipes are providing "virtual/kernel". |
5755 | The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of | 6583 | The :term:`PREFERRED_PROVIDER` variable is set with the name (:term:`PN`) of |
5756 | the recipe you prefer to provide "virtual/kernel". | 6584 | the recipe you prefer to provide "virtual/kernel". |
5757 | 6585 | ||
5758 | Following are more examples: | 6586 | Here are more examples:: |
5759 | :: | ||
5760 | 6587 | ||
5761 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" | 6588 | PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86" |
5762 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" | 6589 | PREFERRED_PROVIDER_virtual/libgl ?= "mesa" |
5763 | 6590 | ||
5764 | For more | 6591 | For more |
5765 | information, see the ":ref:`dev-manual/common-tasks:using virtual providers`" | 6592 | information, see the ":ref:`dev-manual/new-recipe:using virtual providers`" |
5766 | section in the Yocto Project Development Tasks Manual. | 6593 | section in the Yocto Project Development Tasks Manual. |
5767 | 6594 | ||
5768 | .. note:: | 6595 | .. note:: |
5769 | 6596 | ||
5770 | If you use a ``virtual/\*`` item with ``PREFERRED_PROVIDER``, then any | 6597 | If you use a ``virtual/\*`` item with :term:`PREFERRED_PROVIDER`, then any |
5771 | recipe that :term:`PROVIDES` that item but is not selected (defined) | 6598 | recipe that :term:`PROVIDES` that item but is not selected (defined) |
5772 | by ``PREFERRED_PROVIDER`` is prevented from building, which is usually | 6599 | by :term:`PREFERRED_PROVIDER` is prevented from building, which is usually |
5773 | desirable since this mechanism is designed to select between mutually | 6600 | desirable since this mechanism is designed to select between mutually |
5774 | exclusive alternative providers. | 6601 | exclusive alternative providers. |
5775 | 6602 | ||
6603 | :term:`PREFERRED_PROVIDERS` | ||
6604 | See :term:`bitbake:PREFERRED_PROVIDERS` in the BitBake manual. | ||
6605 | |||
5776 | :term:`PREFERRED_VERSION` | 6606 | :term:`PREFERRED_VERSION` |
5777 | If multiple versions of recipes exist, this variable determines which | 6607 | If there are multiple versions of a recipe available, this variable |
5778 | version is given preference. You must always suffix the variable with | 6608 | determines which version should be given preference. You must always |
5779 | the :term:`PN` you want to select, and you should set the | 6609 | suffix the variable with the :term:`PN` you want to select (`python` in |
5780 | :term:`PV` accordingly for precedence. | 6610 | the first example below), and you should specify the :term:`PV` |
6611 | accordingly (`3.4.0` in the example). | ||
5781 | 6612 | ||
5782 | The ``PREFERRED_VERSION`` variable supports limited wildcard use | 6613 | The :term:`PREFERRED_VERSION` variable supports limited wildcard use |
5783 | through the "``%``" character. You can use the character to match any | 6614 | through the "``%``" character. You can use the character to match any |
5784 | number of characters, which can be useful when specifying versions | 6615 | number of characters, which can be useful when specifying versions |
5785 | that contain long revision numbers that potentially change. Here are | 6616 | that contain long revision numbers that potentially change. Here are |
5786 | two examples: | 6617 | two examples:: |
5787 | :: | ||
5788 | 6618 | ||
5789 | PREFERRED_VERSION_python = "3.4.0" | 6619 | PREFERRED_VERSION_python = "3.4.0" |
5790 | PREFERRED_VERSION_linux-yocto = "5.0%" | 6620 | PREFERRED_VERSION_linux-yocto = "5.0%" |
@@ -5798,66 +6628,63 @@ system and gives an overview of their function and contents. | |||
5798 | The specified version is matched against :term:`PV`, which | 6628 | The specified version is matched against :term:`PV`, which |
5799 | does not necessarily match the version part of the recipe's filename. | 6629 | does not necessarily match the version part of the recipe's filename. |
5800 | For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` | 6630 | For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` |
5801 | where ``foo_git.bb`` contains the following assignment: | 6631 | where ``foo_git.bb`` contains the following assignment:: |
5802 | :: | ||
5803 | 6632 | ||
5804 | PV = "1.1+git${SRCPV}" | 6633 | PV = "1.1+git${SRCPV}" |
5805 | 6634 | ||
5806 | In this case, the correct way to select | 6635 | In this case, the correct way to select |
5807 | ``foo_git.bb`` is by using an assignment such as the following: | 6636 | ``foo_git.bb`` is by using an assignment such as the following:: |
5808 | :: | ||
5809 | 6637 | ||
5810 | PREFERRED_VERSION_foo = "1.1+git%" | 6638 | PREFERRED_VERSION_foo = "1.1+git%" |
5811 | 6639 | ||
5812 | Compare that previous example | 6640 | Compare that previous example |
5813 | against the following incorrect example, which does not work: | 6641 | against the following incorrect example, which does not work:: |
5814 | :: | ||
5815 | 6642 | ||
5816 | PREFERRED_VERSION_foo = "git" | 6643 | PREFERRED_VERSION_foo = "git" |
5817 | 6644 | ||
5818 | Sometimes the ``PREFERRED_VERSION`` variable can be set by | 6645 | Sometimes the :term:`PREFERRED_VERSION` variable can be set by |
5819 | configuration files in a way that is hard to change. You can use | 6646 | configuration files in a way that is hard to change. You can use |
5820 | :term:`OVERRIDES` to set a machine-specific | 6647 | :term:`OVERRIDES` to set a machine-specific |
5821 | override. Here is an example: | 6648 | override. Here is an example:: |
5822 | :: | ||
5823 | 6649 | ||
5824 | PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%" | 6650 | PREFERRED_VERSION_linux-yocto:qemux86 = "5.0%" |
5825 | 6651 | ||
5826 | Although not recommended, worst case, you can also use the | 6652 | Although not recommended, worst case, you can also use the |
5827 | "forcevariable" override, which is the strongest override possible. | 6653 | "forcevariable" override, which is the strongest override possible. |
5828 | Here is an example: | 6654 | Here is an example:: |
5829 | :: | ||
5830 | 6655 | ||
5831 | PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%" | 6656 | PREFERRED_VERSION_linux-yocto:forcevariable = "5.0%" |
5832 | 6657 | ||
5833 | .. note:: | 6658 | .. note:: |
5834 | 6659 | ||
5835 | The ``\_forcevariable`` override is not handled specially. This override | 6660 | The ``:forcevariable`` override is not handled specially. This override |
5836 | only works because the default value of ``OVERRIDES`` includes "forcevariable". | 6661 | only works because the default value of :term:`OVERRIDES` includes "forcevariable". |
6662 | |||
6663 | If a recipe with the specified version is not available, a warning | ||
6664 | message will be shown. See :term:`REQUIRED_VERSION` if you want this | ||
6665 | to be an error instead. | ||
5837 | 6666 | ||
5838 | :term:`PREMIRRORS` | 6667 | :term:`PREMIRRORS` |
5839 | Specifies additional paths from which the OpenEmbedded build system | 6668 | Specifies additional paths from which the OpenEmbedded build system |
5840 | gets source code. When the build system searches for source code, it | 6669 | gets source code. When the build system searches for source code, it |
5841 | first tries the local download directory. If that location fails, the | 6670 | first tries the local download directory. If that location fails, the |
5842 | build system tries locations defined by ``PREMIRRORS``, the upstream | 6671 | build system tries locations defined by :term:`PREMIRRORS`, the upstream |
5843 | source, and then locations specified by | 6672 | source, and then locations specified by |
5844 | :term:`MIRRORS` in that order. | 6673 | :term:`MIRRORS` in that order. |
5845 | 6674 | ||
5846 | Assuming your distribution (:term:`DISTRO`) is "poky", | 6675 | The default value for :term:`PREMIRRORS` is defined in the |
5847 | the default value for ``PREMIRRORS`` is defined in the | 6676 | ``meta/classes-global/mirrors.bbclass`` file in the core metadata layer. |
5848 | ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. | ||
5849 | 6677 | ||
5850 | Typically, you could add a specific server for the build system to | 6678 | Typically, you could add a specific server for the build system to |
5851 | attempt before any others by adding something like the following to | 6679 | attempt before any others by adding something like the following to |
5852 | the ``local.conf`` configuration file in the | 6680 | the ``local.conf`` configuration file in the |
5853 | :term:`Build Directory`: | 6681 | :term:`Build Directory`:: |
5854 | :: | ||
5855 | 6682 | ||
5856 | PREMIRRORS_prepend = "\ | 6683 | PREMIRRORS:prepend = "\ |
5857 | git://.*/.* http://www.yoctoproject.org/sources/ \n \ | 6684 | git://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
5858 | ftp://.*/.* http://www.yoctoproject.org/sources/ \n \ | 6685 | ftp://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
5859 | http://.*/.* http://www.yoctoproject.org/sources/ \n \ | 6686 | http://.*/.* &YOCTO_DL_URL;/mirror/sources/ \ |
5860 | https://.*/.* http://www.yoctoproject.org/sources/ \n" | 6687 | https://.*/.* &YOCTO_DL_URL;/mirror/sources/" |
5861 | 6688 | ||
5862 | These changes cause the | 6689 | These changes cause the |
5863 | build system to intercept Git, FTP, HTTP, and HTTPS requests and | 6690 | build system to intercept Git, FTP, HTTP, and HTTPS requests and |
@@ -5868,12 +6695,12 @@ system and gives an overview of their function and contents. | |||
5868 | :term:`PRIORITY` | 6695 | :term:`PRIORITY` |
5869 | Indicates the importance of a package. | 6696 | Indicates the importance of a package. |
5870 | 6697 | ||
5871 | ``PRIORITY`` is considered to be part of the distribution policy | 6698 | :term:`PRIORITY` is considered to be part of the distribution policy |
5872 | because the importance of any given recipe depends on the purpose for | 6699 | because the importance of any given recipe depends on the purpose for |
5873 | which the distribution is being produced. Thus, ``PRIORITY`` is not | 6700 | which the distribution is being produced. Thus, :term:`PRIORITY` is not |
5874 | normally set within recipes. | 6701 | normally set within recipes. |
5875 | 6702 | ||
5876 | You can set ``PRIORITY`` to "required", "standard", "extra", and | 6703 | You can set :term:`PRIORITY` to "required", "standard", "extra", and |
5877 | "optional", which is the default. | 6704 | "optional", which is the default. |
5878 | 6705 | ||
5879 | :term:`PRIVATE_LIBS` | 6706 | :term:`PRIVATE_LIBS` |
@@ -5887,8 +6714,7 @@ system and gives an overview of their function and contents. | |||
5887 | standard version of the library. | 6714 | standard version of the library. |
5888 | 6715 | ||
5889 | Libraries specified in this variable should be specified by their | 6716 | Libraries specified in this variable should be specified by their |
5890 | file name. For example, from the Firefox recipe in meta-browser: | 6717 | file name. For example, from the Firefox recipe in meta-browser:: |
5891 | :: | ||
5892 | 6718 | ||
5893 | PRIVATE_LIBS = "libmozjs.so \ | 6719 | PRIVATE_LIBS = "libmozjs.so \ |
5894 | libxpcom.so \ | 6720 | libxpcom.so \ |
@@ -5904,35 +6730,34 @@ system and gives an overview of their function and contents. | |||
5904 | 6730 | ||
5905 | :term:`PROVIDES` | 6731 | :term:`PROVIDES` |
5906 | A list of aliases by which a particular recipe can be known. By | 6732 | A list of aliases by which a particular recipe can be known. By |
5907 | default, a recipe's own ``PN`` is implicitly already in its | 6733 | default, a recipe's own :term:`PN` is implicitly already in its |
5908 | ``PROVIDES`` list and therefore does not need to mention that it | 6734 | :term:`PROVIDES` list and therefore does not need to mention that it |
5909 | provides itself. If a recipe uses ``PROVIDES``, the additional | 6735 | provides itself. If a recipe uses :term:`PROVIDES`, the additional |
5910 | aliases are synonyms for the recipe and can be useful for satisfying | 6736 | aliases are synonyms for the recipe and can be useful for satisfying |
5911 | dependencies of other recipes during the build as specified by | 6737 | dependencies of other recipes during the build as specified by |
5912 | ``DEPENDS``. | 6738 | :term:`DEPENDS`. |
5913 | 6739 | ||
5914 | Consider the following example ``PROVIDES`` statement from the recipe | 6740 | Consider the following example :term:`PROVIDES` statement from the recipe |
5915 | file ``eudev_3.2.9.bb``: | 6741 | file ``eudev_3.2.9.bb``:: |
5916 | :: | ||
5917 | 6742 | ||
5918 | PROVIDES += "udev" | 6743 | PROVIDES += "udev" |
5919 | 6744 | ||
5920 | The ``PROVIDES`` statement | 6745 | The :term:`PROVIDES` statement |
5921 | results in the "eudev" recipe also being available as simply "udev". | 6746 | results in the "eudev" recipe also being available as simply "udev". |
5922 | 6747 | ||
5923 | .. note:: | 6748 | .. note:: |
5924 | 6749 | ||
5925 | A recipe's own recipe name (:term:`PN`) is always implicitly prepended | 6750 | A recipe's own recipe name (:term:`PN`) is always implicitly prepended |
5926 | to `PROVIDES`, so while using "+=" in the above example may not be | 6751 | to :term:`PROVIDES`, so while using "+=" in the above example may not be |
5927 | strictly necessary it is recommended to avoid confusion. | 6752 | strictly necessary it is recommended to avoid confusion. |
5928 | 6753 | ||
5929 | In addition to providing recipes under alternate names, the | 6754 | In addition to providing recipes under alternate names, the |
5930 | ``PROVIDES`` mechanism is also used to implement virtual targets. A | 6755 | :term:`PROVIDES` mechanism is also used to implement virtual targets. A |
5931 | virtual target is a name that corresponds to some particular | 6756 | virtual target is a name that corresponds to some particular |
5932 | functionality (e.g. a Linux kernel). Recipes that provide the | 6757 | functionality (e.g. a Linux kernel). Recipes that provide the |
5933 | functionality in question list the virtual target in ``PROVIDES``. | 6758 | functionality in question list the virtual target in :term:`PROVIDES`. |
5934 | Recipes that depend on the functionality in question can include the | 6759 | Recipes that depend on the functionality in question can include the |
5935 | virtual target in ``DEPENDS`` to leave the choice of provider open. | 6760 | virtual target in :term:`DEPENDS` to leave the choice of provider open. |
5936 | 6761 | ||
5937 | Conventionally, virtual targets have names on the form | 6762 | Conventionally, virtual targets have names on the form |
5938 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part | 6763 | "virtual/function" (e.g. "virtual/kernel"). The slash is simply part |
@@ -5943,15 +6768,14 @@ system and gives an overview of their function and contents. | |||
5943 | 6768 | ||
5944 | .. note:: | 6769 | .. note:: |
5945 | 6770 | ||
5946 | A corresponding mechanism for virtual runtime dependencies | 6771 | A corresponding mechanism for virtual runtime dependencies (packages) |
5947 | (packages) exists. However, the mechanism does not depend on any | 6772 | exists. However, the mechanism does not depend on any special |
5948 | special functionality beyond ordinary variable assignments. For | 6773 | functionality beyond ordinary variable assignments. For example, |
5949 | example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of | 6774 | :term:`VIRTUAL-RUNTIME_dev_manager <VIRTUAL-RUNTIME>` refers to the |
5950 | the component that manages the ``/dev`` directory. | 6775 | package of the component that manages the ``/dev`` directory. |
5951 | 6776 | ||
5952 | Setting the "preferred provider" for runtime dependencies is as | 6777 | Setting the "preferred provider" for runtime dependencies is as |
5953 | simple as using the following assignment in a configuration file: | 6778 | simple as using the following assignment in a configuration file:: |
5954 | :: | ||
5955 | 6779 | ||
5956 | VIRTUAL-RUNTIME_dev_manager = "udev" | 6780 | VIRTUAL-RUNTIME_dev_manager = "udev" |
5957 | 6781 | ||
@@ -5959,17 +6783,16 @@ system and gives an overview of their function and contents. | |||
5959 | :term:`PRSERV_HOST` | 6783 | :term:`PRSERV_HOST` |
5960 | The network based :term:`PR` service host and port. | 6784 | The network based :term:`PR` service host and port. |
5961 | 6785 | ||
5962 | The ``conf/local.conf.sample.extended`` configuration file in the | 6786 | The ``conf/templates/default/local.conf.sample.extended`` configuration |
5963 | :term:`Source Directory` shows how the | 6787 | file in the :term:`Source Directory` shows how the :term:`PRSERV_HOST` |
5964 | ``PRSERV_HOST`` variable is set: | 6788 | variable is set:: |
5965 | :: | ||
5966 | 6789 | ||
5967 | PRSERV_HOST = "localhost:0" | 6790 | PRSERV_HOST = "localhost:0" |
5968 | 6791 | ||
5969 | You must | 6792 | You must |
5970 | set the variable if you want to automatically start a local :ref:`PR | 6793 | set the variable if you want to automatically start a local :ref:`PR |
5971 | service <dev-manual/common-tasks:working with a pr service>`. You can | 6794 | service <dev-manual/packages:working with a pr service>`. You can |
5972 | set ``PRSERV_HOST`` to other values to use a remote PR service. | 6795 | set :term:`PRSERV_HOST` to other values to use a remote PR service. |
5973 | 6796 | ||
5974 | 6797 | ||
5975 | :term:`PSEUDO_IGNORE_PATHS` | 6798 | :term:`PSEUDO_IGNORE_PATHS` |
@@ -5982,7 +6805,7 @@ system and gives an overview of their function and contents. | |||
5982 | 6805 | ||
5983 | :term:`PTEST_ENABLED` | 6806 | :term:`PTEST_ENABLED` |
5984 | Specifies whether or not :ref:`Package | 6807 | Specifies whether or not :ref:`Package |
5985 | Test <dev-manual/common-tasks:testing packages with ptest>` (ptest) | 6808 | Test <dev-manual/packages:testing packages with ptest>` (ptest) |
5986 | functionality is enabled when building a recipe. You should not set | 6809 | functionality is enabled when building a recipe. You should not set |
5987 | this variable directly. Enabling and disabling building Package Tests | 6810 | this variable directly. Enabling and disabling building Package Tests |
5988 | at build time should be done by adding "ptest" to (or removing it | 6811 | at build time should be done by adding "ptest" to (or removing it |
@@ -5991,49 +6814,52 @@ system and gives an overview of their function and contents. | |||
5991 | :term:`PV` | 6814 | :term:`PV` |
5992 | The version of the recipe. The version is normally extracted from the | 6815 | The version of the recipe. The version is normally extracted from the |
5993 | recipe filename. For example, if the recipe is named | 6816 | recipe filename. For example, if the recipe is named |
5994 | ``expat_2.0.1.bb``, then the default value of ``PV`` will be "2.0.1". | 6817 | ``expat_2.0.1.bb``, then the default value of :term:`PV` will be "2.0.1". |
5995 | ``PV`` is generally not overridden within a recipe unless it is | 6818 | :term:`PV` is generally not overridden within a recipe unless it is |
5996 | building an unstable (i.e. development) version from a source code | 6819 | building an unstable (i.e. development) version from a source code |
5997 | repository (e.g. Git or Subversion). | 6820 | repository (e.g. Git or Subversion). |
5998 | 6821 | ||
5999 | ``PV`` is the default value of the :term:`PKGV` variable. | 6822 | :term:`PV` is the default value of the :term:`PKGV` variable. |
6823 | |||
6824 | :term:`PYPI_PACKAGE` | ||
6825 | When inheriting the :ref:`ref-classes-pypi` class, specifies the | ||
6826 | `PyPI <https://pypi.org/>`__ package name to be built. The default value | ||
6827 | is set based upon :term:`BPN` (stripping any "python-" or "python3-" | ||
6828 | prefix off if present), however for some packages it will need to be set | ||
6829 | explicitly if that will not match the package name (e.g. where the | ||
6830 | package name has a prefix, underscores, uppercase letters etc.) | ||
6000 | 6831 | ||
6001 | :term:`PYTHON_ABI` | 6832 | :term:`PYTHON_ABI` |
6002 | When used by recipes that inherit the | 6833 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` |
6003 | :ref:`distutils3 <ref-classes-distutils3>`, | 6834 | class, denotes the Application Binary Interface (ABI) currently in use |
6004 | :ref:`setuptools3 <ref-classes-setuptools3>`, | 6835 | for Python. By default, the ABI is "m". You do not have to set this |
6005 | :ref:`distutils <ref-classes-distutils>`, or | 6836 | variable as the OpenEmbedded build system sets it for you. |
6006 | :ref:`setuptools <ref-classes-setuptools>` classes, denotes the | ||
6007 | Application Binary Interface (ABI) currently in use for Python. By | ||
6008 | default, the ABI is "m". You do not have to set this variable as the | ||
6009 | OpenEmbedded build system sets it for you. | ||
6010 | 6837 | ||
6011 | The OpenEmbedded build system uses the ABI to construct directory | 6838 | The OpenEmbedded build system uses the ABI to construct directory |
6012 | names used when installing the Python headers and libraries in | 6839 | names used when installing the Python headers and libraries in |
6013 | sysroot (e.g. ``.../python3.3m/...``). | 6840 | sysroot (e.g. ``.../python3.3m/...``). |
6014 | 6841 | ||
6015 | Recipes that inherit the ``distutils`` class during cross-builds also | 6842 | :term:`QA_EMPTY_DIRS` |
6016 | use this variable to locate the headers and libraries of the | 6843 | Specifies a list of directories that are expected to be empty when |
6017 | appropriate Python that the extension is targeting. | 6844 | packaging; if ``empty-dirs`` appears in :term:`ERROR_QA` or |
6845 | :term:`WARN_QA` these will be checked and an error or warning | ||
6846 | (respectively) will be produced. | ||
6018 | 6847 | ||
6019 | :term:`PYTHON_PN` | 6848 | The default :term:`QA_EMPTY_DIRS` value is set in |
6020 | When used by recipes that inherit the | 6849 | :ref:`insane.bbclass <ref-classes-insane>`. |
6021 | `distutils3 <ref-classes-distutils3>`, | ||
6022 | :ref:`setuptools3 <ref-classes-setuptools3>`, | ||
6023 | :ref:`distutils <ref-classes-distutils>`, or | ||
6024 | :ref:`setuptools <ref-classes-setuptools>` classes, specifies the | ||
6025 | major Python version being built. For Python 3.x, ``PYTHON_PN`` would | ||
6026 | be "python3". You do not have to set this variable as the | ||
6027 | OpenEmbedded build system automatically sets it for you. | ||
6028 | 6850 | ||
6029 | The variable allows recipes to use common infrastructure such as the | 6851 | :term:`QA_EMPTY_DIRS_RECOMMENDATION` |
6030 | following: | 6852 | Specifies a recommendation for why a directory must be empty, |
6031 | :: | 6853 | which will be included in the error message if a specific directory |
6854 | is found to contain files. Must be overridden with the directory | ||
6855 | path to match on. | ||
6032 | 6856 | ||
6033 | DEPENDS += "${PYTHON_PN}-native" | 6857 | If no recommendation is specified for a directory, then the default |
6858 | "but it is expected to be empty" will be used. | ||
6034 | 6859 | ||
6035 | In the previous example, | 6860 | An example message shows if files were present in '/dev':: |
6036 | the version of the dependency is ``PYTHON_PN``. | 6861 | |
6862 | QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime" | ||
6037 | 6863 | ||
6038 | :term:`RANLIB` | 6864 | :term:`RANLIB` |
6039 | The minimal command and arguments to run ``ranlib``. | 6865 | The minimal command and arguments to run ``ranlib``. |
@@ -6043,19 +6869,17 @@ system and gives an overview of their function and contents. | |||
6043 | will not be installed if conflicting packages are not first removed. | 6869 | will not be installed if conflicting packages are not first removed. |
6044 | 6870 | ||
6045 | Like all package-controlling variables, you must always use them in | 6871 | Like all package-controlling variables, you must always use them in |
6046 | conjunction with a package name override. Here is an example: | 6872 | conjunction with a package name override. Here is an example:: |
6047 | :: | ||
6048 | 6873 | ||
6049 | RCONFLICTS_${PN} = "another_conflicting_package_name" | 6874 | RCONFLICTS:${PN} = "another_conflicting_package_name" |
6050 | 6875 | ||
6051 | BitBake, which the OpenEmbedded build system uses, supports | 6876 | BitBake, which the OpenEmbedded build system uses, supports |
6052 | specifying versioned dependencies. Although the syntax varies | 6877 | specifying versioned dependencies. Although the syntax varies |
6053 | depending on the packaging format, BitBake hides these differences | 6878 | depending on the packaging format, BitBake hides these differences |
6054 | from you. Here is the general syntax to specify versions with the | 6879 | from you. Here is the general syntax to specify versions with the |
6055 | ``RCONFLICTS`` variable: | 6880 | :term:`RCONFLICTS` variable:: |
6056 | :: | ||
6057 | 6881 | ||
6058 | RCONFLICTS_${PN} = "package (operator version)" | 6882 | RCONFLICTS:${PN} = "package (operator version)" |
6059 | 6883 | ||
6060 | For ``operator``, you can specify the following: | 6884 | For ``operator``, you can specify the following: |
6061 | 6885 | ||
@@ -6066,32 +6890,30 @@ system and gives an overview of their function and contents. | |||
6066 | - >= | 6890 | - >= |
6067 | 6891 | ||
6068 | For example, the following sets up a dependency on version 1.2 or | 6892 | For example, the following sets up a dependency on version 1.2 or |
6069 | greater of the package ``foo``: | 6893 | greater of the package ``foo``:: |
6070 | :: | ||
6071 | 6894 | ||
6072 | RCONFLICTS_${PN} = "foo (>= 1.2)" | 6895 | RCONFLICTS:${PN} = "foo (>= 1.2)" |
6073 | 6896 | ||
6074 | :term:`RDEPENDS` | 6897 | :term:`RDEPENDS` |
6075 | Lists runtime dependencies of a package. These dependencies are other | 6898 | Lists runtime dependencies of a package. These dependencies are other |
6076 | packages that must be installed in order for the package to function | 6899 | packages that must be installed in order for the package to function |
6077 | correctly. As an example, the following assignment declares that the | 6900 | correctly. As an example, the following assignment declares that the |
6078 | package ``foo`` needs the packages ``bar`` and ``baz`` to be | 6901 | package ``foo`` needs the packages ``bar`` and ``baz`` to be |
6079 | installed: | 6902 | installed:: |
6080 | :: | ||
6081 | 6903 | ||
6082 | RDEPENDS_foo = "bar baz" | 6904 | RDEPENDS:foo = "bar baz" |
6083 | 6905 | ||
6084 | The most common types of package | 6906 | The most common types of package |
6085 | runtime dependencies are automatically detected and added. Therefore, | 6907 | runtime dependencies are automatically detected and added. Therefore, |
6086 | most recipes do not need to set ``RDEPENDS``. For more information, | 6908 | most recipes do not need to set :term:`RDEPENDS`. For more information, |
6087 | see the | 6909 | see the |
6088 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" | 6910 | ":ref:`overview-manual/concepts:automatically added runtime dependencies`" |
6089 | section in the Yocto Project Overview and Concepts Manual. | 6911 | section in the Yocto Project Overview and Concepts Manual. |
6090 | 6912 | ||
6091 | The practical effect of the above ``RDEPENDS`` assignment is that | 6913 | The practical effect of the above :term:`RDEPENDS` assignment is that |
6092 | ``bar`` and ``baz`` will be declared as dependencies inside the | 6914 | ``bar`` and ``baz`` will be declared as dependencies inside the |
6093 | package ``foo`` when it is written out by one of the | 6915 | package ``foo`` when it is written out by one of the |
6094 | :ref:`do_package_write_\* <ref-tasks-package_write_deb>` tasks. | 6916 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` tasks. |
6095 | Exactly how this is done depends on which package format is used, | 6917 | Exactly how this is done depends on which package format is used, |
6096 | which is determined by | 6918 | which is determined by |
6097 | :term:`PACKAGE_CLASSES`. When the | 6919 | :term:`PACKAGE_CLASSES`. When the |
@@ -6099,59 +6921,57 @@ system and gives an overview of their function and contents. | |||
6099 | also install the packages on which it depends. | 6921 | also install the packages on which it depends. |
6100 | 6922 | ||
6101 | To ensure that the packages ``bar`` and ``baz`` get built, the | 6923 | To ensure that the packages ``bar`` and ``baz`` get built, the |
6102 | previous ``RDEPENDS`` assignment also causes a task dependency to be | 6924 | previous :term:`RDEPENDS` assignment also causes a task dependency to be |
6103 | added. This dependency is from the recipe's | 6925 | added. This dependency is from the recipe's |
6104 | :ref:`ref-tasks-build` (not to be confused with | 6926 | :ref:`ref-tasks-build` (not to be confused with |
6105 | :ref:`ref-tasks-compile`) task to the | 6927 | :ref:`ref-tasks-compile`) task to the |
6106 | ``do_package_write_*`` task of the recipes that build ``bar`` and | 6928 | :ref:`do_package_write_* <ref-tasks-package_write_deb>` task of the recipes that build ``bar`` and |
6107 | ``baz``. | 6929 | ``baz``. |
6108 | 6930 | ||
6109 | The names of the packages you list within ``RDEPENDS`` must be the | 6931 | The names of the packages you list within :term:`RDEPENDS` must be the |
6110 | names of other packages - they cannot be recipe names. Although | 6932 | names of other packages --- they cannot be recipe names. Although |
6111 | package names and recipe names usually match, the important point | 6933 | package names and recipe names usually match, the important point |
6112 | here is that you are providing package names within the ``RDEPENDS`` | 6934 | here is that you are providing package names within the :term:`RDEPENDS` |
6113 | variable. For an example of the default list of packages created from | 6935 | variable. For an example of the default list of packages created from |
6114 | a recipe, see the :term:`PACKAGES` variable. | 6936 | a recipe, see the :term:`PACKAGES` variable. |
6115 | 6937 | ||
6116 | Because the ``RDEPENDS`` variable applies to packages being built, | 6938 | Because the :term:`RDEPENDS` variable applies to packages being built, |
6117 | you should always use the variable in a form with an attached package | 6939 | you should always use the variable in a form with an attached package |
6118 | name (remember that a single recipe can build multiple packages). For | 6940 | name (remember that a single recipe can build multiple packages). For |
6119 | example, suppose you are building a development package that depends | 6941 | example, suppose you are building a development package that depends |
6120 | on the ``perl`` package. In this case, you would use the following | 6942 | on the ``perl`` package. In this case, you would use the following |
6121 | ``RDEPENDS`` statement: | 6943 | :term:`RDEPENDS` statement:: |
6122 | :: | ||
6123 | 6944 | ||
6124 | RDEPENDS_${PN}-dev += "perl" | 6945 | RDEPENDS:${PN}-dev += "perl" |
6125 | 6946 | ||
6126 | In the example, | 6947 | In the example, |
6127 | the development package depends on the ``perl`` package. Thus, the | 6948 | the development package depends on the ``perl`` package. Thus, the |
6128 | ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of | 6949 | :term:`RDEPENDS` variable has the ``${PN}-dev`` package name as part of |
6129 | the variable. | 6950 | the variable. |
6130 | 6951 | ||
6131 | .. note:: | 6952 | .. note:: |
6132 | 6953 | ||
6133 | ``RDEPENDS_${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` | 6954 | ``RDEPENDS:${PN}-dev`` includes ``${``\ :term:`PN`\ ``}`` |
6134 | by default. This default is set in the BitBake configuration file | 6955 | by default. This default is set in the BitBake configuration file |
6135 | (``meta/conf/bitbake.conf``). Be careful not to accidentally remove | 6956 | (``meta/conf/bitbake.conf``). Be careful not to accidentally remove |
6136 | ``${PN}`` when modifying ``RDEPENDS_${PN}-dev``. Use the "+=" operator | 6957 | ``${PN}`` when modifying ``RDEPENDS:${PN}-dev``. Use the "+=" operator |
6137 | rather than the "=" operator. | 6958 | rather than the "=" operator. |
6138 | 6959 | ||
6139 | The package names you use with ``RDEPENDS`` must appear as they would | 6960 | The package names you use with :term:`RDEPENDS` must appear as they would |
6140 | in the ``PACKAGES`` variable. The :term:`PKG` variable | 6961 | in the :term:`PACKAGES` variable. The :term:`PKG` variable |
6141 | allows a different name to be used for the final package (e.g. the | 6962 | allows a different name to be used for the final package (e.g. the |
6142 | :ref:`debian <ref-classes-debian>` class uses this to rename | 6963 | :ref:`ref-classes-debian` class uses this to rename |
6143 | packages), but this final package name cannot be used with | 6964 | packages), but this final package name cannot be used with |
6144 | ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be | 6965 | :term:`RDEPENDS`, which makes sense as :term:`RDEPENDS` is meant to be |
6145 | independent of the package format used. | 6966 | independent of the package format used. |
6146 | 6967 | ||
6147 | BitBake, which the OpenEmbedded build system uses, supports | 6968 | BitBake, which the OpenEmbedded build system uses, supports |
6148 | specifying versioned dependencies. Although the syntax varies | 6969 | specifying versioned dependencies. Although the syntax varies |
6149 | depending on the packaging format, BitBake hides these differences | 6970 | depending on the packaging format, BitBake hides these differences |
6150 | from you. Here is the general syntax to specify versions with the | 6971 | from you. Here is the general syntax to specify versions with the |
6151 | ``RDEPENDS`` variable: | 6972 | :term:`RDEPENDS` variable:: |
6152 | :: | ||
6153 | 6973 | ||
6154 | RDEPENDS_${PN} = "package (operator version)" | 6974 | RDEPENDS:${PN} = "package (operator version)" |
6155 | 6975 | ||
6156 | For ``operator``, you can specify the following: | 6976 | For ``operator``, you can specify the following: |
6157 | 6977 | ||
@@ -6165,43 +6985,105 @@ system and gives an overview of their function and contents. | |||
6165 | 6985 | ||
6166 | .. note:: | 6986 | .. note:: |
6167 | 6987 | ||
6168 | You can use ``EXTENDPKGV`` to provide a full package version | 6988 | You can use :term:`EXTENDPKGV` to provide a full package version |
6169 | specification. | 6989 | specification. |
6170 | 6990 | ||
6171 | For example, the following sets up a dependency on version 1.2 or | 6991 | For example, the following sets up a dependency on version 1.2 or |
6172 | greater of the package ``foo``: | 6992 | greater of the package ``foo``:: |
6173 | :: | 6993 | |
6994 | RDEPENDS:${PN} = "foo (>= 1.2)" | ||
6995 | |||
6996 | For information on build-time dependencies, see the :term:`DEPENDS` | ||
6997 | variable. You can also see the | ||
6998 | ":ref:`bitbake-user-manual/bitbake-user-manual-metadata:tasks`" and | ||
6999 | ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the | ||
7000 | BitBake User Manual for additional information on tasks and dependencies. | ||
6174 | 7001 | ||
6175 | RDEPENDS_${PN} = "foo (>= 1.2)" | 7002 | :term:`RECIPE_MAINTAINER` |
7003 | This variable defines the name and e-mail address of the maintainer of a | ||
7004 | recipe. Such information can be used by human users submitted changes, | ||
7005 | and by automated tools to send notifications, for example about | ||
7006 | vulnerabilities or source updates. | ||
6176 | 7007 | ||
6177 | For information on build-time dependencies, see the | 7008 | The variable can be defined in a global distribution :oe_git:`maintainers.inc |
6178 | :term:`DEPENDS` variable. You can also see the | 7009 | </openembedded-core/tree/meta/conf/distro/include/maintainers.inc>` file:: |
6179 | ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and | 7010 | |
6180 | ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the | 7011 | meta/conf/distro/include/maintainers.inc:RECIPE_MAINTAINER:pn-sysvinit = "Ross Burton <ross.burton@arm.com>" |
6181 | BitBake User Manual for additional information on tasks and | 7012 | |
6182 | dependencies. | 7013 | It can also be directly defined in a recipe, |
7014 | for example in the ``libgpiod`` one:: | ||
7015 | |||
7016 | RECIPE_MAINTAINER = "Bartosz Golaszewski <brgl@bgdev.pl>" | ||
7017 | |||
7018 | :term:`RECIPE_NO_UPDATE_REASON` | ||
7019 | If a recipe should not be replaced by a more recent upstream version, | ||
7020 | putting the reason why in this variable in a recipe allows | ||
7021 | ``devtool check-upgrade-status`` command to display it, as explained | ||
7022 | in the ":ref:`ref-manual/devtool-reference:checking on the upgrade status of a recipe`" | ||
7023 | section. | ||
7024 | |||
7025 | :term:`RECIPE_SYSROOT` | ||
7026 | This variable points to the directory that holds all files populated from | ||
7027 | recipes specified in :term:`DEPENDS`. As the name indicates, | ||
7028 | think of this variable as a custom root (``/``) for the recipe that will be | ||
7029 | used by the compiler in order to find headers and other files needed to complete | ||
7030 | its job. | ||
7031 | |||
7032 | This variable is related to :term:`STAGING_DIR_HOST` or :term:`STAGING_DIR_TARGET` | ||
7033 | according to the type of the recipe and the build target. | ||
7034 | |||
7035 | To better understand this variable, consider the following examples: | ||
7036 | |||
7037 | - For ``#include <header.h>``, ``header.h`` should be in ``"${RECIPE_SYSROOT}/usr/include"`` | ||
7038 | |||
7039 | - For ``-lexample``, ``libexample.so`` should be in ``"${RECIPE_SYSROOT}/lib"`` | ||
7040 | or other library sysroot directories. | ||
7041 | |||
7042 | The default value is ``"${WORKDIR}/recipe-sysroot"``. | ||
7043 | Do not modify it. | ||
7044 | |||
7045 | :term:`RECIPE_SYSROOT_NATIVE` | ||
7046 | This is similar to :term:`RECIPE_SYSROOT` but the populated files are from | ||
7047 | ``-native`` recipes. This allows a recipe built for the target machine to | ||
7048 | use ``native`` tools. | ||
7049 | |||
7050 | This variable is related to :term:`STAGING_DIR_NATIVE`. | ||
7051 | |||
7052 | The default value is ``"${WORKDIR}/recipe-sysroot-native"``. | ||
7053 | Do not modify it. | ||
7054 | |||
7055 | :term:`REPODIR` | ||
7056 | See :term:`bitbake:REPODIR` in the BitBake manual. | ||
6183 | 7057 | ||
6184 | :term:`REQUIRED_DISTRO_FEATURES` | 7058 | :term:`REQUIRED_DISTRO_FEATURES` |
6185 | When inheriting the | 7059 | When inheriting the :ref:`ref-classes-features_check` |
6186 | :ref:`features_check <ref-classes-features_check>` | ||
6187 | class, this variable identifies distribution features that must exist | 7060 | class, this variable identifies distribution features that must exist |
6188 | in the current configuration in order for the OpenEmbedded build | 7061 | in the current configuration in order for the OpenEmbedded build |
6189 | system to build the recipe. In other words, if the | 7062 | system to build the recipe. In other words, if the |
6190 | ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not | 7063 | :term:`REQUIRED_DISTRO_FEATURES` variable lists a feature that does not |
6191 | appear in ``DISTRO_FEATURES`` within the current configuration, then | 7064 | appear in :term:`DISTRO_FEATURES` within the current configuration, then |
6192 | the recipe will be skipped, and if the build system attempts to build | 7065 | the recipe will be skipped, and if the build system attempts to build |
6193 | the recipe then an error will be triggered. | 7066 | the recipe then an error will be triggered. |
6194 | 7067 | ||
7068 | :term:`REQUIRED_VERSION` | ||
7069 | If there are multiple versions of a recipe available, this variable | ||
7070 | determines which version should be given preference. | ||
7071 | :term:`REQUIRED_VERSION` works in exactly the same manner as | ||
7072 | :term:`PREFERRED_VERSION`, except that if the specified version is not | ||
7073 | available then an error message is shown and the build fails | ||
7074 | immediately. | ||
7075 | |||
7076 | If both :term:`REQUIRED_VERSION` and :term:`PREFERRED_VERSION` are set | ||
7077 | for the same recipe, the :term:`REQUIRED_VERSION` value applies. | ||
7078 | |||
6195 | :term:`RM_WORK_EXCLUDE` | 7079 | :term:`RM_WORK_EXCLUDE` |
6196 | With ``rm_work`` enabled, this variable specifies a list of recipes | 7080 | With :ref:`ref-classes-rm-work` enabled, this variable |
6197 | whose work directories should not be removed. See the | 7081 | specifies a list of recipes whose work directories should not be removed. |
6198 | ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more | 7082 | See the ":ref:`ref-classes-rm-work`" section for more details. |
6199 | details. | ||
6200 | 7083 | ||
6201 | :term:`ROOT_HOME` | 7084 | :term:`ROOT_HOME` |
6202 | Defines the root home directory. By default, this directory is set as | 7085 | Defines the root home directory. By default, this directory is set as |
6203 | follows in the BitBake configuration file: | 7086 | follows in the BitBake configuration file:: |
6204 | :: | ||
6205 | 7087 | ||
6206 | ROOT_HOME ??= "/home/root" | 7088 | ROOT_HOME ??= "/home/root" |
6207 | 7089 | ||
@@ -6214,8 +7096,7 @@ system and gives an overview of their function and contents. | |||
6214 | You can override the default by setting the variable in any layer or | 7096 | You can override the default by setting the variable in any layer or |
6215 | in the ``local.conf`` file. Because the default is set using a "weak" | 7097 | in the ``local.conf`` file. Because the default is set using a "weak" |
6216 | assignment (i.e. "??="), you can use either of the following forms to | 7098 | assignment (i.e. "??="), you can use either of the following forms to |
6217 | define your override: | 7099 | define your override:: |
6218 | :: | ||
6219 | 7100 | ||
6220 | ROOT_HOME = "/root" | 7101 | ROOT_HOME = "/root" |
6221 | ROOT_HOME ?= "/root" | 7102 | ROOT_HOME ?= "/root" |
@@ -6227,16 +7108,15 @@ system and gives an overview of their function and contents. | |||
6227 | :term:`ROOTFS` | 7108 | :term:`ROOTFS` |
6228 | Indicates a filesystem image to include as the root filesystem. | 7109 | Indicates a filesystem image to include as the root filesystem. |
6229 | 7110 | ||
6230 | The ``ROOTFS`` variable is an optional variable used with the | 7111 | The :term:`ROOTFS` variable is an optional variable used with the |
6231 | :ref:`image-live <ref-classes-image-live>` class. | 7112 | :ref:`ref-classes-image-live` class. |
6232 | 7113 | ||
6233 | :term:`ROOTFS_POSTINSTALL_COMMAND` | 7114 | :term:`ROOTFS_POSTINSTALL_COMMAND` |
6234 | Specifies a list of functions to call after the OpenEmbedded build | 7115 | Specifies a list of functions to call after the OpenEmbedded build |
6235 | system has installed packages. You can specify functions separated by | 7116 | system has installed packages. You can specify functions separated by |
6236 | semicolons: | 7117 | spaces:: |
6237 | :: | ||
6238 | 7118 | ||
6239 | ROOTFS_POSTINSTALL_COMMAND += "function; ... " | 7119 | ROOTFS_POSTINSTALL_COMMAND += "function" |
6240 | 7120 | ||
6241 | If you need to pass the root filesystem path to a command within a | 7121 | If you need to pass the root filesystem path to a command within a |
6242 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7122 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6247,10 +7127,9 @@ system and gives an overview of their function and contents. | |||
6247 | :term:`ROOTFS_POSTPROCESS_COMMAND` | 7127 | :term:`ROOTFS_POSTPROCESS_COMMAND` |
6248 | Specifies a list of functions to call once the OpenEmbedded build | 7128 | Specifies a list of functions to call once the OpenEmbedded build |
6249 | system has created the root filesystem. You can specify functions | 7129 | system has created the root filesystem. You can specify functions |
6250 | separated by semicolons: | 7130 | separated by spaces:: |
6251 | :: | ||
6252 | 7131 | ||
6253 | ROOTFS_POSTPROCESS_COMMAND += "function; ... " | 7132 | ROOTFS_POSTPROCESS_COMMAND += "function" |
6254 | 7133 | ||
6255 | If you need to pass the root filesystem path to a command within a | 7134 | If you need to pass the root filesystem path to a command within a |
6256 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7135 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6263,10 +7142,9 @@ system and gives an overview of their function and contents. | |||
6263 | system has removed unnecessary packages. When runtime package | 7142 | system has removed unnecessary packages. When runtime package |
6264 | management is disabled in the image, several packages are removed | 7143 | management is disabled in the image, several packages are removed |
6265 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. | 7144 | including ``base-passwd``, ``shadow``, and ``update-alternatives``. |
6266 | You can specify functions separated by semicolons: | 7145 | You can specify functions separated by spaces:: |
6267 | :: | ||
6268 | 7146 | ||
6269 | ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " | 7147 | ROOTFS_POSTUNINSTALL_COMMAND += "function" |
6270 | 7148 | ||
6271 | If you need to pass the root filesystem path to a command within a | 7149 | If you need to pass the root filesystem path to a command within a |
6272 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7150 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6277,10 +7155,9 @@ system and gives an overview of their function and contents. | |||
6277 | :term:`ROOTFS_PREPROCESS_COMMAND` | 7155 | :term:`ROOTFS_PREPROCESS_COMMAND` |
6278 | Specifies a list of functions to call before the OpenEmbedded build | 7156 | Specifies a list of functions to call before the OpenEmbedded build |
6279 | system has created the root filesystem. You can specify functions | 7157 | system has created the root filesystem. You can specify functions |
6280 | separated by semicolons: | 7158 | separated by spaces:: |
6281 | :: | ||
6282 | 7159 | ||
6283 | ROOTFS_PREPROCESS_COMMAND += "function; ... " | 7160 | ROOTFS_PREPROCESS_COMMAND += "function" |
6284 | 7161 | ||
6285 | If you need to pass the root filesystem path to a command within a | 7162 | If you need to pass the root filesystem path to a command within a |
6286 | function, you can use ``${IMAGE_ROOTFS}``, which points to the | 7163 | function, you can use ``${IMAGE_ROOTFS}``, which points to the |
@@ -6288,68 +7165,68 @@ system and gives an overview of their function and contents. | |||
6288 | :term:`IMAGE_ROOTFS` variable for more | 7165 | :term:`IMAGE_ROOTFS` variable for more |
6289 | information. | 7166 | information. |
6290 | 7167 | ||
7168 | :term:`RPMBUILD_EXTRA_PARAMS` | ||
7169 | Specifies extra user-defined parameters for the ``rpmbuild`` command. | ||
7170 | |||
6291 | :term:`RPROVIDES` | 7171 | :term:`RPROVIDES` |
6292 | A list of package name aliases that a package also provides. These | 7172 | A list of package name aliases that a package also provides. These |
6293 | aliases are useful for satisfying runtime dependencies of other | 7173 | aliases are useful for satisfying runtime dependencies of other |
6294 | packages both during the build and on the target (as specified by | 7174 | packages both during the build and on the target (as specified by |
6295 | ``RDEPENDS``). | 7175 | :term:`RDEPENDS`). |
6296 | 7176 | ||
6297 | .. note:: | 7177 | .. note:: |
6298 | 7178 | ||
6299 | A package's own name is implicitly already in its ``RPROVIDES`` list. | 7179 | A package's own name is implicitly already in its :term:`RPROVIDES` list. |
6300 | 7180 | ||
6301 | As with all package-controlling variables, you must always use the | 7181 | As with all package-controlling variables, you must always use the |
6302 | variable in conjunction with a package name override. Here is an | 7182 | variable in conjunction with a package name override. Here is an |
6303 | example: | 7183 | example:: |
6304 | :: | ||
6305 | 7184 | ||
6306 | RPROVIDES_${PN} = "widget-abi-2" | 7185 | RPROVIDES:${PN} = "widget-abi-2" |
6307 | 7186 | ||
6308 | :term:`RRECOMMENDS` | 7187 | :term:`RRECOMMENDS` |
6309 | A list of packages that extends the usability of a package being | 7188 | A list of packages that extends the usability of a package being |
6310 | built. The package being built does not depend on this list of | 7189 | built. The package being built does not depend on this list of |
6311 | packages in order to successfully build, but rather uses them for | 7190 | packages in order to successfully build, but rather uses them for |
6312 | extended usability. To specify runtime dependencies for packages, see | 7191 | extended usability. To specify runtime dependencies for packages, see |
6313 | the ``RDEPENDS`` variable. | 7192 | the :term:`RDEPENDS` variable. |
6314 | 7193 | ||
6315 | The package manager will automatically install the ``RRECOMMENDS`` | 7194 | The package manager will automatically install the :term:`RRECOMMENDS` |
6316 | list of packages when installing the built package. However, you can | 7195 | list of packages when installing the built package. However, you can |
6317 | prevent listed packages from being installed by using the | 7196 | prevent listed packages from being installed by using the |
6318 | :term:`BAD_RECOMMENDATIONS`, | 7197 | :term:`BAD_RECOMMENDATIONS`, |
6319 | :term:`NO_RECOMMENDATIONS`, and | 7198 | :term:`NO_RECOMMENDATIONS`, and |
6320 | :term:`PACKAGE_EXCLUDE` variables. | 7199 | :term:`PACKAGE_EXCLUDE` variables. |
6321 | 7200 | ||
6322 | Packages specified in ``RRECOMMENDS`` need not actually be produced. | 7201 | Packages specified in :term:`RRECOMMENDS` need not actually be produced. |
6323 | However, a recipe must exist that provides each package, either | 7202 | However, there must be a recipe providing each package, either |
6324 | through the :term:`PACKAGES` or | 7203 | through the :term:`PACKAGES` or |
6325 | :term:`PACKAGES_DYNAMIC` variables or the | 7204 | :term:`PACKAGES_DYNAMIC` variables or the |
6326 | :term:`RPROVIDES` variable, or an error will occur | 7205 | :term:`RPROVIDES` variable, or an error will occur |
6327 | during the build. If such a recipe does exist and the package is not | 7206 | during the build. If such a recipe does exist and the package is not |
6328 | produced, the build continues without error. | 7207 | produced, the build continues without error. |
6329 | 7208 | ||
6330 | Because the ``RRECOMMENDS`` variable applies to packages being built, | 7209 | Because the :term:`RRECOMMENDS` variable applies to packages being built, |
6331 | you should always attach an override to the variable to specify the | 7210 | you should always attach an override to the variable to specify the |
6332 | particular package whose usability is being extended. For example, | 7211 | particular package whose usability is being extended. For example, |
6333 | suppose you are building a development package that is extended to | 7212 | suppose you are building a development package that is extended to |
6334 | support wireless functionality. In this case, you would use the | 7213 | support wireless functionality. In this case, you would use the |
6335 | following: | 7214 | following:: |
6336 | :: | ||
6337 | 7215 | ||
6338 | RRECOMMENDS_${PN}-dev += "wireless_package_name" | 7216 | RRECOMMENDS:${PN}-dev += "wireless_package_name" |
6339 | 7217 | ||
6340 | In the | 7218 | In the |
6341 | example, the package name (``${PN}-dev``) must appear as it would in | 7219 | example, the package name (``${PN}-dev``) must appear as it would in |
6342 | the ``PACKAGES`` namespace before any renaming of the output package | 7220 | the :term:`PACKAGES` namespace before any renaming of the output package |
6343 | by classes such as ``debian.bbclass``. | 7221 | by classes such as :ref:`ref-classes-debian`. |
6344 | 7222 | ||
6345 | BitBake, which the OpenEmbedded build system uses, supports | 7223 | BitBake, which the OpenEmbedded build system uses, supports |
6346 | specifying versioned recommends. Although the syntax varies depending | 7224 | specifying versioned recommends. Although the syntax varies depending |
6347 | on the packaging format, BitBake hides these differences from you. | 7225 | on the packaging format, BitBake hides these differences from you. |
6348 | Here is the general syntax to specify versions with the | 7226 | Here is the general syntax to specify versions with the |
6349 | ``RRECOMMENDS`` variable: | 7227 | :term:`RRECOMMENDS` variable:: |
6350 | :: | ||
6351 | 7228 | ||
6352 | RRECOMMENDS_${PN} = "package (operator version)" | 7229 | RRECOMMENDS:${PN} = "package (operator version)" |
6353 | 7230 | ||
6354 | For ``operator``, you can specify the following: | 7231 | For ``operator``, you can specify the following: |
6355 | 7232 | ||
@@ -6360,32 +7237,29 @@ system and gives an overview of their function and contents. | |||
6360 | - >= | 7237 | - >= |
6361 | 7238 | ||
6362 | For example, the following sets up a recommend on version 1.2 or | 7239 | For example, the following sets up a recommend on version 1.2 or |
6363 | greater of the package ``foo``: | 7240 | greater of the package ``foo``:: |
6364 | :: | ||
6365 | 7241 | ||
6366 | RRECOMMENDS_${PN} = "foo (>= 1.2)" | 7242 | RRECOMMENDS:${PN} = "foo (>= 1.2)" |
6367 | 7243 | ||
6368 | :term:`RREPLACES` | 7244 | :term:`RREPLACES` |
6369 | A list of packages replaced by a package. The package manager uses | 7245 | A list of packages replaced by a package. The package manager uses |
6370 | this variable to determine which package should be installed to | 7246 | this variable to determine which package should be installed to |
6371 | replace other package(s) during an upgrade. In order to also have the | 7247 | replace other package(s) during an upgrade. In order to also have the |
6372 | other package(s) removed at the same time, you must add the name of | 7248 | other package(s) removed at the same time, you must add the name of |
6373 | the other package to the ``RCONFLICTS`` variable. | 7249 | the other package to the :term:`RCONFLICTS` variable. |
6374 | 7250 | ||
6375 | As with all package-controlling variables, you must use this variable | 7251 | As with all package-controlling variables, you must use this variable |
6376 | in conjunction with a package name override. Here is an example: | 7252 | in conjunction with a package name override. Here is an example:: |
6377 | :: | ||
6378 | 7253 | ||
6379 | RREPLACES_${PN} = "other_package_being_replaced" | 7254 | RREPLACES:${PN} = "other_package_being_replaced" |
6380 | 7255 | ||
6381 | BitBake, which the OpenEmbedded build system uses, supports | 7256 | BitBake, which the OpenEmbedded build system uses, supports |
6382 | specifying versioned replacements. Although the syntax varies | 7257 | specifying versioned replacements. Although the syntax varies |
6383 | depending on the packaging format, BitBake hides these differences | 7258 | depending on the packaging format, BitBake hides these differences |
6384 | from you. Here is the general syntax to specify versions with the | 7259 | from you. Here is the general syntax to specify versions with the |
6385 | ``RREPLACES`` variable: | 7260 | :term:`RREPLACES` variable:: |
6386 | :: | ||
6387 | 7261 | ||
6388 | RREPLACES_${PN} = "package (operator version)" | 7262 | RREPLACES:${PN} = "package (operator version)" |
6389 | 7263 | ||
6390 | For ``operator``, you can specify the following: | 7264 | For ``operator``, you can specify the following: |
6391 | 7265 | ||
@@ -6396,10 +7270,9 @@ system and gives an overview of their function and contents. | |||
6396 | - >= | 7270 | - >= |
6397 | 7271 | ||
6398 | For example, the following sets up a replacement using version 1.2 | 7272 | For example, the following sets up a replacement using version 1.2 |
6399 | or greater of the package ``foo``: | 7273 | or greater of the package ``foo``:: |
6400 | :: | ||
6401 | 7274 | ||
6402 | RREPLACES_${PN} = "foo (>= 1.2)" | 7275 | RREPLACES:${PN} = "foo (>= 1.2)" |
6403 | 7276 | ||
6404 | :term:`RSUGGESTS` | 7277 | :term:`RSUGGESTS` |
6405 | A list of additional packages that you can suggest for installation | 7278 | A list of additional packages that you can suggest for installation |
@@ -6408,10 +7281,14 @@ system and gives an overview of their function and contents. | |||
6408 | 7281 | ||
6409 | As with all package-controlling variables, you must always use this | 7282 | As with all package-controlling variables, you must always use this |
6410 | variable in conjunction with a package name override. Here is an | 7283 | variable in conjunction with a package name override. Here is an |
6411 | example: | 7284 | example:: |
6412 | :: | 7285 | |
7286 | RSUGGESTS:${PN} = "useful_package another_package" | ||
6413 | 7287 | ||
6414 | RSUGGESTS_${PN} = "useful_package another_package" | 7288 | :term:`RUST_CHANNEL` |
7289 | Specifies which version of Rust to build - "stable", "beta" or "nightly". | ||
7290 | The default value is "stable". Set this at your own risk, as values other | ||
7291 | than "stable" are not guaranteed to work at a given time. | ||
6415 | 7292 | ||
6416 | :term:`S` | 7293 | :term:`S` |
6417 | The location in the :term:`Build Directory` where | 7294 | The location in the :term:`Build Directory` where |
@@ -6421,14 +7298,13 @@ system and gives an overview of their function and contents. | |||
6421 | version. If the source tarball extracts the code to a directory named | 7298 | version. If the source tarball extracts the code to a directory named |
6422 | anything other than ``${BPN}-${PV}``, or if the source code is | 7299 | anything other than ``${BPN}-${PV}``, or if the source code is |
6423 | fetched from an SCM such as Git or Subversion, then you must set | 7300 | fetched from an SCM such as Git or Subversion, then you must set |
6424 | ``S`` in the recipe so that the OpenEmbedded build system knows where | 7301 | :term:`S` in the recipe so that the OpenEmbedded build system knows where |
6425 | to find the unpacked source. | 7302 | to find the unpacked source. |
6426 | 7303 | ||
6427 | As an example, assume a :term:`Source Directory` | 7304 | As an example, assume a :term:`Source Directory` |
6428 | top-level folder named ``poky`` and a default Build Directory at | 7305 | top-level folder named ``poky`` and a default :term:`Build Directory` at |
6429 | ``poky/build``. In this case, the work directory the build system | 7306 | ``poky/build``. In this case, the work directory the build system |
6430 | uses to keep the unpacked recipe for ``db`` is the following: | 7307 | uses to keep the unpacked recipe for ``db`` is the following:: |
6431 | :: | ||
6432 | 7308 | ||
6433 | poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 | 7309 | poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 |
6434 | 7310 | ||
@@ -6437,11 +7313,10 @@ system and gives an overview of their function and contents. | |||
6437 | This next example assumes a Git repository. By default, Git | 7313 | This next example assumes a Git repository. By default, Git |
6438 | repositories are cloned to ``${WORKDIR}/git`` during | 7314 | repositories are cloned to ``${WORKDIR}/git`` during |
6439 | :ref:`ref-tasks-fetch`. Since this path is different | 7315 | :ref:`ref-tasks-fetch`. Since this path is different |
6440 | from the default value of ``S``, you must set it specifically so the | 7316 | from the default value of :term:`S`, you must set it specifically so the |
6441 | source can be located: | 7317 | source can be located:: |
6442 | :: | ||
6443 | 7318 | ||
6444 | SRC_URI = "git://path/to/repo.git" | 7319 | SRC_URI = "git://path/to/repo.git;branch=main" |
6445 | S = "${WORKDIR}/git" | 7320 | S = "${WORKDIR}/git" |
6446 | 7321 | ||
6447 | :term:`SANITY_REQUIRED_UTILITIES` | 7322 | :term:`SANITY_REQUIRED_UTILITIES` |
@@ -6455,7 +7330,7 @@ system and gives an overview of their function and contents. | |||
6455 | been tested against. Identifiers consist of the host distributor ID | 7330 | been tested against. Identifiers consist of the host distributor ID |
6456 | followed by the release, as reported by the ``lsb_release`` tool or | 7331 | followed by the release, as reported by the ``lsb_release`` tool or |
6457 | as read from ``/etc/lsb-release``. Separate the list items with | 7332 | as read from ``/etc/lsb-release``. Separate the list items with |
6458 | explicit newline characters (``\n``). If ``SANITY_TESTED_DISTROS`` is | 7333 | explicit newline characters (``\n``). If :term:`SANITY_TESTED_DISTROS` is |
6459 | not empty and the current value of | 7334 | not empty and the current value of |
6460 | :term:`NATIVELSBSTRING` does not appear in the | 7335 | :term:`NATIVELSBSTRING` does not appear in the |
6461 | list, then the build system reports a warning that indicates the | 7336 | list, then the build system reports a warning that indicates the |
@@ -6465,12 +7340,29 @@ system and gives an overview of their function and contents. | |||
6465 | The target architecture for the SDK. Typically, you do not directly | 7340 | The target architecture for the SDK. Typically, you do not directly |
6466 | set this variable. Instead, use :term:`SDKMACHINE`. | 7341 | set this variable. Instead, use :term:`SDKMACHINE`. |
6467 | 7342 | ||
7343 | :term:`SDK_ARCHIVE_TYPE` | ||
7344 | Specifies the type of archive to create for the SDK. Valid values: | ||
7345 | |||
7346 | - ``tar.xz`` (default) | ||
7347 | - ``zip`` | ||
7348 | |||
7349 | Only one archive type can be specified. | ||
7350 | |||
7351 | :term:`SDK_BUILDINFO_FILE` | ||
7352 | When using the :ref:`ref-classes-image-buildinfo` class, | ||
7353 | specifies the file in the SDK to write the build information into. The | ||
7354 | default value is "``/buildinfo``". | ||
7355 | |||
7356 | :term:`SDK_CUSTOM_TEMPLATECONF` | ||
7357 | When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to | ||
7358 | "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory` | ||
7359 | (:term:`TOPDIR`) then this will be copied into the SDK. | ||
7360 | |||
6468 | :term:`SDK_DEPLOY` | 7361 | :term:`SDK_DEPLOY` |
6469 | The directory set up and used by the | 7362 | The directory set up and used by the |
6470 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which | 7363 | :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which the |
6471 | the SDK is deployed. The ``populate_sdk_base`` class defines | 7364 | SDK is deployed. The :ref:`populate_sdk_base <ref-classes-populate-sdk>` |
6472 | ``SDK_DEPLOY`` as follows: | 7365 | class defines :term:`SDK_DEPLOY` as follows:: |
6473 | :: | ||
6474 | 7366 | ||
6475 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" | 7367 | SDK_DEPLOY = "${TMPDIR}/deploy/sdk" |
6476 | 7368 | ||
@@ -6478,15 +7370,14 @@ system and gives an overview of their function and contents. | |||
6478 | The parent directory used by the OpenEmbedded build system when | 7370 | The parent directory used by the OpenEmbedded build system when |
6479 | creating SDK output. The | 7371 | creating SDK output. The |
6480 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines | 7372 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines |
6481 | the variable as follows: | 7373 | the variable as follows:: |
6482 | :: | ||
6483 | 7374 | ||
6484 | SDK_DIR = "${WORKDIR}/sdk" | 7375 | SDK_DIR = "${WORKDIR}/sdk" |
6485 | 7376 | ||
6486 | .. note:: | 7377 | .. note:: |
6487 | 7378 | ||
6488 | The ``SDK_DIR`` directory is a temporary directory as it is part of | 7379 | The :term:`SDK_DIR` directory is a temporary directory as it is part of |
6489 | ``WORKDIR``. The final output directory is :term:`SDK_DEPLOY`. | 7380 | :term:`WORKDIR`. The final output directory is :term:`SDK_DEPLOY`. |
6490 | 7381 | ||
6491 | :term:`SDK_EXT_TYPE` | 7382 | :term:`SDK_EXT_TYPE` |
6492 | Controls whether or not shared state artifacts are copied into the | 7383 | Controls whether or not shared state artifacts are copied into the |
@@ -6504,14 +7395,12 @@ system and gives an overview of their function and contents. | |||
6504 | The manifest file for the host part of the SDK. This file lists all | 7395 | The manifest file for the host part of the SDK. This file lists all |
6505 | the installed packages that make up the host part of the SDK. The | 7396 | the installed packages that make up the host part of the SDK. The |
6506 | file contains package information on a line-per-package basis as | 7397 | file contains package information on a line-per-package basis as |
6507 | follows: | 7398 | follows:: |
6508 | :: | ||
6509 | 7399 | ||
6510 | packagename packagearch version | 7400 | packagename packagearch version |
6511 | 7401 | ||
6512 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | 7402 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class |
6513 | defines the manifest file as follows: | 7403 | defines the manifest file as follows:: |
6514 | :: | ||
6515 | 7404 | ||
6516 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" | 7405 | SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" |
6517 | 7406 | ||
@@ -6527,7 +7416,7 @@ system and gives an overview of their function and contents. | |||
6527 | 7416 | ||
6528 | .. note:: | 7417 | .. note:: |
6529 | 7418 | ||
6530 | Enabling the ``SDK_INCLUDE_PKGDATA`` | 7419 | Enabling the :term:`SDK_INCLUDE_PKGDATA` |
6531 | variable significantly increases build time because all of world | 7420 | variable significantly increases build time because all of world |
6532 | needs to be built. Enabling the variable also slightly increases | 7421 | needs to be built. Enabling the variable also slightly increases |
6533 | the size of the extensible SDK. | 7422 | the size of the extensible SDK. |
@@ -6541,82 +7430,21 @@ system and gives an overview of their function and contents. | |||
6541 | IDE or from other tools and you do not want to perform additional | 7430 | IDE or from other tools and you do not want to perform additional |
6542 | steps to install the toolchain. | 7431 | steps to install the toolchain. |
6543 | 7432 | ||
6544 | The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if | 7433 | The :term:`SDK_INCLUDE_TOOLCHAIN` variable defaults to "0" if |
6545 | ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if | 7434 | :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if |
6546 | ``SDK_EXT_TYPE`` is set to "full". | 7435 | :term:`SDK_EXT_TYPE` is set to "full". |
6547 | |||
6548 | :term:`SDK_INHERIT_BLACKLIST` | ||
6549 | A list of classes to remove from the :term:`INHERIT` | ||
6550 | value globally within the extensible SDK configuration. The | ||
6551 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the | ||
6552 | default value: | ||
6553 | :: | ||
6554 | |||
6555 | SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" | ||
6556 | |||
6557 | Some classes are not generally applicable within the extensible SDK | ||
6558 | context. You can use this variable to disable those classes. | ||
6559 | |||
6560 | For additional information on how to customize the extensible SDK's | ||
6561 | configuration, see the | ||
6562 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6563 | section in the Yocto Project Application Development and the | ||
6564 | Extensible Software Development Kit (eSDK) manual. | ||
6565 | |||
6566 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6567 | A list of variables not allowed through from the OpenEmbedded build | ||
6568 | system configuration into the extensible SDK configuration. Usually, | ||
6569 | these are variables that are specific to the machine on which the | ||
6570 | build system is running and thus would be potentially problematic | ||
6571 | within the extensible SDK. | ||
6572 | |||
6573 | By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the | ||
6574 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and | ||
6575 | excludes the following variables: | ||
6576 | |||
6577 | - :term:`CONF_VERSION` | ||
6578 | - :term:`BB_NUMBER_THREADS` | ||
6579 | - :term:`bitbake:BB_NUMBER_PARSE_THREADS` | ||
6580 | - :term:`PARALLEL_MAKE` | ||
6581 | - :term:`PRSERV_HOST` | ||
6582 | - :term:`SSTATE_MIRRORS` :term:`DL_DIR` | ||
6583 | - :term:`SSTATE_DIR` :term:`TMPDIR` | ||
6584 | - :term:`BB_SERVER_TIMEOUT` | ||
6585 | |||
6586 | For additional information on how to customize the extensible SDK's | ||
6587 | configuration, see the | ||
6588 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6589 | section in the Yocto Project Application Development and the | ||
6590 | Extensible Software Development Kit (eSDK) manual. | ||
6591 | |||
6592 | :term:`SDK_LOCAL_CONF_WHITELIST` | ||
6593 | A list of variables allowed through from the OpenEmbedded build | ||
6594 | system configuration into the extensible SDK configuration. By | ||
6595 | default, the list of variables is empty and is set in the | ||
6596 | :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. | ||
6597 | |||
6598 | This list overrides the variables specified using the | ||
6599 | :term:`SDK_LOCAL_CONF_BLACKLIST` | ||
6600 | variable as well as any variables identified by automatic | ||
6601 | blacklisting due to the "/" character being found at the start of the | ||
6602 | value, which is usually indicative of being a path and thus might not | ||
6603 | be valid on the system where the SDK is installed. | ||
6604 | |||
6605 | For additional information on how to customize the extensible SDK's | ||
6606 | configuration, see the | ||
6607 | ":ref:`sdk-manual/appendix-customizing:configuring the extensible sdk`" | ||
6608 | section in the Yocto Project Application Development and the | ||
6609 | Extensible Software Development Kit (eSDK) manual. | ||
6610 | 7436 | ||
6611 | :term:`SDK_NAME` | 7437 | :term:`SDK_NAME` |
6612 | The base name for SDK output files. The name is derived from the | 7438 | The base name for SDK output files. The default value (as set in |
6613 | :term:`DISTRO`, :term:`TCLIBC`, | 7439 | ``meta-poky/conf/distro/poky.conf``) is derived from the |
6614 | :term:`SDK_ARCH`, | 7440 | :term:`DISTRO`, |
6615 | :term:`IMAGE_BASENAME`, and | 7441 | :term:`TCLIBC`, |
6616 | :term:`TUNE_PKGARCH` variables: | 7442 | :term:`SDKMACHINE`, |
6617 | :: | 7443 | :term:`IMAGE_BASENAME`, |
7444 | :term:`TUNE_PKGARCH`, and | ||
7445 | :term:`MACHINE` variables:: | ||
6618 | 7446 | ||
6619 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" | 7447 | SDK_NAME = "${DISTRO}-${TCLIBC}-${SDKMACHINE}-${IMAGE_BASENAME}-${TUNE_PKGARCH}-${MACHINE}" |
6620 | 7448 | ||
6621 | :term:`SDK_OS` | 7449 | :term:`SDK_OS` |
6622 | Specifies the operating system for which the SDK will be built. The | 7450 | Specifies the operating system for which the SDK will be built. The |
@@ -6625,8 +7453,7 @@ system and gives an overview of their function and contents. | |||
6625 | :term:`SDK_OUTPUT` | 7453 | :term:`SDK_OUTPUT` |
6626 | The location used by the OpenEmbedded build system when creating SDK | 7454 | The location used by the OpenEmbedded build system when creating SDK |
6627 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` | 7455 | output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` |
6628 | class defines the variable as follows: | 7456 | class defines the variable as follows:: |
6629 | :: | ||
6630 | 7457 | ||
6631 | SDK_DIR = "${WORKDIR}/sdk" | 7458 | SDK_DIR = "${WORKDIR}/sdk" |
6632 | SDK_OUTPUT = "${SDK_DIR}/image" | 7459 | SDK_OUTPUT = "${SDK_DIR}/image" |
@@ -6634,7 +7461,7 @@ system and gives an overview of their function and contents. | |||
6634 | 7461 | ||
6635 | .. note:: | 7462 | .. note:: |
6636 | 7463 | ||
6637 | The ``SDK_OUTPUT`` directory is a temporary directory as it is part of | 7464 | The :term:`SDK_OUTPUT` directory is a temporary directory as it is part of |
6638 | :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is | 7465 | :term:`WORKDIR` by way of :term:`SDK_DIR`. The final output directory is |
6639 | :term:`SDK_DEPLOY`. | 7466 | :term:`SDK_DEPLOY`. |
6640 | 7467 | ||
@@ -6642,13 +7469,15 @@ system and gives an overview of their function and contents. | |||
6642 | Specifies a list of architectures compatible with the SDK machine. | 7469 | Specifies a list of architectures compatible with the SDK machine. |
6643 | This variable is set automatically and should not normally be | 7470 | This variable is set automatically and should not normally be |
6644 | hand-edited. Entries are separated using spaces and listed in order | 7471 | hand-edited. Entries are separated using spaces and listed in order |
6645 | of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any | 7472 | of priority. The default value for :term:`SDK_PACKAGE_ARCHS` is "all any |
6646 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". | 7473 | noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". |
6647 | 7474 | ||
6648 | :term:`SDK_POSTPROCESS_COMMAND` | 7475 | :term:`SDK_POSTPROCESS_COMMAND` |
6649 | Specifies a list of functions to call once the OpenEmbedded build | 7476 | Specifies a list of functions to call once the OpenEmbedded build |
6650 | system creates the SDK. You can specify functions separated by | 7477 | system creates the SDK. You can specify functions separated by |
6651 | semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " | 7478 | spaces: |
7479 | |||
7480 | SDK_POSTPROCESS_COMMAND += "function" | ||
6652 | 7481 | ||
6653 | If you need to pass an SDK path to a command within a function, you | 7482 | If you need to pass an SDK path to a command within a function, you |
6654 | can use ``${SDK_DIR}``, which points to the parent directory used by | 7483 | can use ``${SDK_DIR}``, which points to the parent directory used by |
@@ -6656,8 +7485,9 @@ system and gives an overview of their function and contents. | |||
6656 | :term:`SDK_DIR` variable for more information. | 7485 | :term:`SDK_DIR` variable for more information. |
6657 | 7486 | ||
6658 | :term:`SDK_PREFIX` | 7487 | :term:`SDK_PREFIX` |
6659 | The toolchain binary prefix used for ``nativesdk`` recipes. The | 7488 | The toolchain binary prefix used for |
6660 | OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the | 7489 | :ref:`ref-classes-nativesdk` recipes. The |
7490 | OpenEmbedded build system uses the :term:`SDK_PREFIX` value to set the | ||
6661 | :term:`TARGET_PREFIX` when building | 7491 | :term:`TARGET_PREFIX` when building |
6662 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". | 7492 | ``nativesdk`` recipes. The default value is "${SDK_SYS}-". |
6663 | 7493 | ||
@@ -6665,15 +7495,15 @@ system and gives an overview of their function and contents. | |||
6665 | A list of shared state tasks added to the extensible SDK. By default, | 7495 | A list of shared state tasks added to the extensible SDK. By default, |
6666 | the following tasks are added: | 7496 | the following tasks are added: |
6667 | 7497 | ||
6668 | - do_populate_lic | 7498 | - :ref:`ref-tasks-populate_lic` |
6669 | - do_package_qa | 7499 | - :ref:`ref-tasks-package_qa` |
6670 | - do_populate_sysroot | 7500 | - :ref:`ref-tasks-populate_sysroot` |
6671 | - do_deploy | 7501 | - :ref:`ref-tasks-deploy` |
6672 | 7502 | ||
6673 | Despite the default value of "" for the | 7503 | Despite the default value of "" for the |
6674 | ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added | 7504 | :term:`SDK_RECRDEP_TASKS` variable, the above four tasks are always added |
6675 | to the SDK. To specify tasks beyond these four, you need to use the | 7505 | to the SDK. To specify tasks beyond these four, you need to use the |
6676 | ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional | 7506 | :term:`SDK_RECRDEP_TASKS` variable (e.g. you are defining additional |
6677 | tasks that are needed in order to build | 7507 | tasks that are needed in order to build |
6678 | :term:`SDK_TARGETS`). | 7508 | :term:`SDK_TARGETS`). |
6679 | 7509 | ||
@@ -6684,21 +7514,19 @@ system and gives an overview of their function and contents. | |||
6684 | The OpenEmbedded build system automatically sets this variable based | 7514 | The OpenEmbedded build system automatically sets this variable based |
6685 | on :term:`SDK_ARCH`, | 7515 | on :term:`SDK_ARCH`, |
6686 | :term:`SDK_VENDOR`, and | 7516 | :term:`SDK_VENDOR`, and |
6687 | :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` | 7517 | :term:`SDK_OS`. You do not need to set the :term:`SDK_SYS` |
6688 | variable yourself. | 7518 | variable yourself. |
6689 | 7519 | ||
6690 | :term:`SDK_TARGET_MANIFEST` | 7520 | :term:`SDK_TARGET_MANIFEST` |
6691 | The manifest file for the target part of the SDK. This file lists all | 7521 | The manifest file for the target part of the SDK. This file lists all |
6692 | the installed packages that make up the target part of the SDK. The | 7522 | the installed packages that make up the target part of the SDK. The |
6693 | file contains package information on a line-per-package basis as | 7523 | file contains package information on a line-per-package basis as |
6694 | follows: | 7524 | follows:: |
6695 | :: | ||
6696 | 7525 | ||
6697 | packagename packagearch version | 7526 | packagename packagearch version |
6698 | 7527 | ||
6699 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class | 7528 | The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class |
6700 | defines the manifest file as follows: | 7529 | defines the manifest file as follows:: |
6701 | :: | ||
6702 | 7530 | ||
6703 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" | 7531 | SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" |
6704 | 7532 | ||
@@ -6710,7 +7538,7 @@ system and gives an overview of their function and contents. | |||
6710 | standard or extensible SDK installation. The default value is "${PN}" | 7538 | standard or extensible SDK installation. The default value is "${PN}" |
6711 | (i.e. the image from which the SDK is built). | 7539 | (i.e. the image from which the SDK is built). |
6712 | 7540 | ||
6713 | The ``SDK_TARGETS`` variable is an internal variable and typically | 7541 | The :term:`SDK_TARGETS` variable is an internal variable and typically |
6714 | would not be changed. | 7542 | would not be changed. |
6715 | 7543 | ||
6716 | :term:`SDK_TITLE` | 7544 | :term:`SDK_TITLE` |
@@ -6718,19 +7546,22 @@ system and gives an overview of their function and contents. | |||
6718 | this title is based on the :term:`DISTRO_NAME` or | 7546 | this title is based on the :term:`DISTRO_NAME` or |
6719 | :term:`DISTRO` variable and is set in the | 7547 | :term:`DISTRO` variable and is set in the |
6720 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | 7548 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as |
6721 | follows: | 7549 | follows:: |
6722 | :: | ||
6723 | 7550 | ||
6724 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" | 7551 | SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK" |
6725 | 7552 | ||
6726 | For the default distribution "poky", | 7553 | For the default distribution "poky", |
6727 | ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". | 7554 | :term:`SDK_TITLE` is set to "Poky (Yocto Project Reference Distro)". |
6728 | 7555 | ||
6729 | For information on how to change this default title, see the | 7556 | For information on how to change this default title, see the |
6730 | ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" | 7557 | ":ref:`sdk-manual/appendix-customizing:changing the extensible sdk installer title`" |
6731 | section in the Yocto Project Application Development and the | 7558 | section in the Yocto Project Application Development and the |
6732 | Extensible Software Development Kit (eSDK) manual. | 7559 | Extensible Software Development Kit (eSDK) manual. |
6733 | 7560 | ||
7561 | :term:`SDK_TOOLCHAIN_LANGS` | ||
7562 | Specifies programming languages to support in the SDK, as a | ||
7563 | space-separated list. Currently supported items are ``rust`` and ``go``. | ||
7564 | |||
6734 | :term:`SDK_UPDATE_URL` | 7565 | :term:`SDK_UPDATE_URL` |
6735 | An optional URL for an update server for the extensible SDK. If set, | 7566 | An optional URL for an update server for the extensible SDK. If set, |
6736 | the value is used as the default update server when running | 7567 | the value is used as the default update server when running |
@@ -6740,29 +7571,32 @@ system and gives an overview of their function and contents. | |||
6740 | Specifies the name of the SDK vendor. | 7571 | Specifies the name of the SDK vendor. |
6741 | 7572 | ||
6742 | :term:`SDK_VERSION` | 7573 | :term:`SDK_VERSION` |
6743 | Specifies the version of the SDK. The distribution configuration file | 7574 | Specifies the version of the SDK. The Poky distribution configuration file |
6744 | (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the | 7575 | (``/meta-poky/conf/distro/poky.conf``) sets the default |
6745 | ``SDK_VERSION`` as follows: | 7576 | :term:`SDK_VERSION` as follows:: |
6746 | :: | ||
6747 | 7577 | ||
6748 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" | 7578 | SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${METADATA_REVISION}', 'snapshot')}" |
6749 | 7579 | ||
6750 | For additional information, see the | 7580 | For additional information, see the |
6751 | :term:`DISTRO_VERSION` and | 7581 | :term:`DISTRO_VERSION` and |
6752 | :term:`DATE` variables. | 7582 | :term:`METADATA_REVISION` variables. |
7583 | |||
7584 | :term:`SDK_ZIP_OPTIONS` | ||
7585 | Specifies extra options to pass to the ``zip`` command when zipping the SDK | ||
7586 | (i.e. when :term:`SDK_ARCHIVE_TYPE` is set to "zip"). The default value is | ||
7587 | "-y". | ||
6753 | 7588 | ||
6754 | :term:`SDKEXTPATH` | 7589 | :term:`SDKEXTPATH` |
6755 | The default installation directory for the Extensible SDK. By | 7590 | The default installation directory for the Extensible SDK. By |
6756 | default, this directory is based on the :term:`DISTRO` | 7591 | default, this directory is based on the :term:`DISTRO` |
6757 | variable and is set in the | 7592 | variable and is set in the |
6758 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as | 7593 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as |
6759 | follows: | 7594 | follows:: |
6760 | :: | ||
6761 | 7595 | ||
6762 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" | 7596 | SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" |
6763 | 7597 | ||
6764 | For the | 7598 | For the |
6765 | default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". | 7599 | default distribution "poky", the :term:`SDKEXTPATH` is set to "poky_sdk". |
6766 | 7600 | ||
6767 | For information on how to change this default directory, see the | 7601 | For information on how to change this default directory, see the |
6768 | ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" | 7602 | ":ref:`sdk-manual/appendix-customizing:changing the default sdk installation directory`" |
@@ -6770,32 +7604,33 @@ system and gives an overview of their function and contents. | |||
6770 | Extensible Software Development Kit (eSDK) manual. | 7604 | Extensible Software Development Kit (eSDK) manual. |
6771 | 7605 | ||
6772 | :term:`SDKIMAGE_FEATURES` | 7606 | :term:`SDKIMAGE_FEATURES` |
6773 | Equivalent to ``IMAGE_FEATURES``. However, this variable applies to | 7607 | Equivalent to :term:`IMAGE_FEATURES`. However, this variable applies to |
6774 | the SDK generated from an image using the following command: | 7608 | the SDK generated from an image using the following command:: |
6775 | :: | ||
6776 | 7609 | ||
6777 | $ bitbake -c populate_sdk imagename | 7610 | $ bitbake -c populate_sdk imagename |
6778 | 7611 | ||
6779 | :term:`SDKMACHINE` | 7612 | :term:`SDKMACHINE` |
6780 | The machine for which the SDK is built. In other words, the SDK is | 7613 | The machine for which the SDK is built. In other words, the SDK is built |
6781 | built such that it runs on the target you specify with the | 7614 | such that it runs on the target you specify with the :term:`SDKMACHINE` |
6782 | ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` | 7615 | value. The value points to a corresponding ``.conf`` file under |
6783 | file under ``conf/machine-sdk/``. | 7616 | ``conf/machine-sdk/`` in the enabled layers, for example ``aarch64``, |
7617 | ``i586``, ``i686``, ``ppc64``, ``ppc64le``, and ``x86_64`` are | ||
7618 | :oe_git:`available in OpenEmbedded-Core </openembedded-core/tree/meta/conf/machine-sdk>`. | ||
6784 | 7619 | ||
6785 | You can use "i686" and "x86_64" as possible values for this variable. | 7620 | The variable defaults to :term:`BUILD_ARCH` so that SDKs are built for the |
6786 | The variable defaults to "i686" and is set in the local.conf file in | 7621 | architecture of the build machine. |
6787 | the Build Directory. | ||
6788 | :: | ||
6789 | |||
6790 | SDKMACHINE ?= "i686" | ||
6791 | 7622 | ||
6792 | .. note:: | 7623 | .. note:: |
6793 | 7624 | ||
6794 | You cannot set the ``SDKMACHINE`` | 7625 | You cannot set the :term:`SDKMACHINE` |
6795 | variable in your distribution configuration file. If you do, the | 7626 | variable in your distribution configuration file. If you do, the |
6796 | configuration will not take affect. | 7627 | configuration will not take effect. |
6797 | 7628 | ||
6798 | :term:`SDKPATH` | 7629 | :term:`SDKPATH` |
7630 | Defines the path used to collect the SDK components and build the | ||
7631 | installer. | ||
7632 | |||
7633 | :term:`SDKPATHINSTALL` | ||
6799 | Defines the path offered to the user for installation of the SDK that | 7634 | Defines the path offered to the user for installation of the SDK that |
6800 | is generated by the OpenEmbedded build system. The path appears as | 7635 | is generated by the OpenEmbedded build system. The path appears as |
6801 | the default location for installing the SDK when you run the SDK's | 7636 | the default location for installing the SDK when you run the SDK's |
@@ -6805,7 +7640,7 @@ system and gives an overview of their function and contents. | |||
6805 | :term:`SDKTARGETSYSROOT` | 7640 | :term:`SDKTARGETSYSROOT` |
6806 | The full path to the sysroot used for cross-compilation within an SDK | 7641 | The full path to the sysroot used for cross-compilation within an SDK |
6807 | as it will be when installed into the default | 7642 | as it will be when installed into the default |
6808 | :term:`SDKPATH`. | 7643 | :term:`SDKPATHINSTALL`. |
6809 | 7644 | ||
6810 | :term:`SECTION` | 7645 | :term:`SECTION` |
6811 | The section in which packages should be categorized. Package | 7646 | The section in which packages should be categorized. Package |
@@ -6816,50 +7651,43 @@ system and gives an overview of their function and contents. | |||
6816 | building for the target. The flags are passed through the default | 7651 | building for the target. The flags are passed through the default |
6817 | value of the :term:`TARGET_CFLAGS` variable. | 7652 | value of the :term:`TARGET_CFLAGS` variable. |
6818 | 7653 | ||
6819 | The ``SELECTED_OPTIMIZATION`` variable takes the value of | 7654 | The :term:`SELECTED_OPTIMIZATION` variable takes the value of |
6820 | ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the | 7655 | :term:`FULL_OPTIMIZATION` unless :term:`DEBUG_BUILD` = "1", in which |
6821 | case, the value of ``DEBUG_OPTIMIZATION`` is used. | 7656 | case the value of :term:`DEBUG_OPTIMIZATION` is used. |
6822 | |||
6823 | :term:`SERIAL_CONSOLE` | ||
6824 | Defines a serial console (TTY) to enable using | ||
6825 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | ||
6826 | value that specifies the baud rate followed by the TTY device name | ||
6827 | separated by a space. You cannot specify more than one TTY device: | ||
6828 | :: | ||
6829 | |||
6830 | SERIAL_CONSOLE = "115200 ttyS0" | ||
6831 | |||
6832 | .. note:: | ||
6833 | |||
6834 | The ``SERIAL_CONSOLE`` variable is deprecated. Please use the | ||
6835 | :term:`SERIAL_CONSOLES` variable. | ||
6836 | 7657 | ||
6837 | :term:`SERIAL_CONSOLES` | 7658 | :term:`SERIAL_CONSOLES` |
6838 | Defines a serial console (TTY) to enable using | 7659 | Defines a serial console (TTY) to enable using |
6839 | `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a | 7660 | :wikipedia:`getty <Getty_(Unix)>`. Provide a value that specifies the |
6840 | value that specifies the baud rate followed by the TTY device name | 7661 | baud rate followed by the TTY device name separated by a semicolon. |
6841 | separated by a semicolon. Use spaces to separate multiple devices: | 7662 | Use spaces to separate multiple devices:: |
6842 | :: | ||
6843 | 7663 | ||
6844 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" | 7664 | SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" |
6845 | 7665 | ||
6846 | :term:`SERIAL_CONSOLES_CHECK` | 7666 | :term:`SETUPTOOLS_BUILD_ARGS` |
6847 | Specifies serial consoles, which must be listed in | 7667 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` |
6848 | :term:`SERIAL_CONSOLES`, to check against | 7668 | class, this variable can be used to specify additional arguments to be |
6849 | ``/proc/console`` before enabling them using getty. This variable | 7669 | passed to ``setup.py build`` in the ``setuptools3_do_compile()`` task. |
6850 | allows aliasing in the format: <device>:<alias>. If a device was | 7670 | |
6851 | listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in | 7671 | :term:`SETUPTOOLS_INSTALL_ARGS` |
6852 | ``/proc/console``, you would do the following: :: | 7672 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` |
7673 | class, this variable can be used to specify additional arguments to be | ||
7674 | passed to ``setup.py install`` in the ``setuptools3_do_install()`` task. | ||
6853 | 7675 | ||
6854 | SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0" | 7676 | :term:`SETUPTOOLS_SETUP_PATH` |
7677 | When used by recipes that inherit the :ref:`ref-classes-setuptools3` | ||
7678 | class, this variable should be used to specify the directory in which | ||
7679 | the ``setup.py`` file is located if it is not at the root of the source | ||
7680 | tree (as specified by :term:`S`). For example, in a recipe where the | ||
7681 | sources are fetched from a Git repository and ``setup.py`` is in a | ||
7682 | ``python/pythonmodule`` subdirectory, you would have this:: | ||
6855 | 7683 | ||
6856 | This variable is currently only supported with SysVinit (i.e. not | 7684 | S = "${WORKDIR}/git" |
6857 | with systemd). | 7685 | SETUPTOOLS_SETUP_PATH = "${S}/python/pythonmodule" |
6858 | 7686 | ||
6859 | :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` | 7687 | :term:`SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS` |
6860 | A list of recipe dependencies that should not be used to determine | 7688 | A list of recipe dependencies that should not be used to determine |
6861 | signatures of tasks from one recipe when they depend on tasks from | 7689 | signatures of tasks from one recipe when they depend on tasks from |
6862 | another recipe. For example: :: | 7690 | another recipe. For example:: |
6863 | 7691 | ||
6864 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" | 7692 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2" |
6865 | 7693 | ||
@@ -6867,7 +7695,7 @@ system and gives an overview of their function and contents. | |||
6867 | 7695 | ||
6868 | You can use the special token ``"*"`` on the left-hand side of the | 7696 | You can use the special token ``"*"`` on the left-hand side of the |
6869 | dependency to match all recipes except the one on the right-hand | 7697 | dependency to match all recipes except the one on the right-hand |
6870 | side. Here is an example: :: | 7698 | side. Here is an example:: |
6871 | 7699 | ||
6872 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" | 7700 | SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native" |
6873 | 7701 | ||
@@ -6912,15 +7740,27 @@ system and gives an overview of their function and contents. | |||
6912 | 7740 | ||
6913 | To enable file removal, set the variable to "1" in your | 7741 | To enable file removal, set the variable to "1" in your |
6914 | ``conf/local.conf`` configuration file in your: | 7742 | ``conf/local.conf`` configuration file in your: |
6915 | :term:`Build Directory`. | 7743 | :term:`Build Directory`:: |
6916 | :: | ||
6917 | 7744 | ||
6918 | SKIP_FILEDEPS = "1" | 7745 | SKIP_FILEDEPS = "1" |
6919 | 7746 | ||
7747 | :term:`SKIP_RECIPE` | ||
7748 | Used to prevent the OpenEmbedded build system from building a given | ||
7749 | recipe. Specify the :term:`PN` value as a variable flag (``varflag``) | ||
7750 | and provide a reason, which will be reported when attempting to | ||
7751 | build the recipe. | ||
7752 | |||
7753 | To prevent a recipe from being built, use the :term:`SKIP_RECIPE` | ||
7754 | variable in your ``local.conf`` file or distribution configuration. | ||
7755 | Here is an example which prevents ``myrecipe`` from being built:: | ||
7756 | |||
7757 | SKIP_RECIPE[myrecipe] = "Not supported by our organization." | ||
7758 | |||
6920 | :term:`SOC_FAMILY` | 7759 | :term:`SOC_FAMILY` |
6921 | Groups together machines based upon the same family of SOC (System On | 7760 | A colon-separated list grouping together machines based upon the same |
6922 | Chip). You typically set this variable in a common ``.inc`` file that | 7761 | family of SoC (System On Chip). You typically set this variable in a |
6923 | you include in the configuration files of all the machines. | 7762 | common ``.inc`` file that you include in the configuration files of all |
7763 | the machines. | ||
6924 | 7764 | ||
6925 | .. note:: | 7765 | .. note:: |
6926 | 7766 | ||
@@ -6933,7 +7773,7 @@ system and gives an overview of their function and contents. | |||
6933 | defined in the ``meta/conf/bitbake.conf`` configuration file. | 7773 | defined in the ``meta/conf/bitbake.conf`` configuration file. |
6934 | 7774 | ||
6935 | You will see this variable referenced in the default values of | 7775 | You will see this variable referenced in the default values of |
6936 | ``FILES_${PN}``. | 7776 | ``FILES:${PN}``. |
6937 | 7777 | ||
6938 | :term:`SOLIBSDEV` | 7778 | :term:`SOLIBSDEV` |
6939 | Defines the suffix for the development symbolic link (symlink) for | 7779 | Defines the suffix for the development symbolic link (symlink) for |
@@ -6942,11 +7782,28 @@ system and gives an overview of their function and contents. | |||
6942 | ``meta/conf/bitbake.conf`` configuration file. | 7782 | ``meta/conf/bitbake.conf`` configuration file. |
6943 | 7783 | ||
6944 | You will see this variable referenced in the default values of | 7784 | You will see this variable referenced in the default values of |
6945 | ``FILES_${PN}-dev``. | 7785 | ``FILES:${PN}-dev``. |
7786 | |||
7787 | :term:`SOURCE_DATE_EPOCH` | ||
7788 | This defines a date expressed in number of seconds since | ||
7789 | the UNIX EPOCH (01 Jan 1970 00:00:00 UTC), which is used by | ||
7790 | multiple build systems to force a timestamp in built binaries. | ||
7791 | Many upstream projects already support this variable. | ||
7792 | |||
7793 | You will find more details in the `official specifications | ||
7794 | <https://reproducible-builds.org/specs/source-date-epoch/>`__. | ||
7795 | |||
7796 | A value for each recipe is computed from the sources by | ||
7797 | :oe_git:`meta/lib/oe/reproducible.py </openembedded-core/tree/meta/lib/oe/reproducible.py>`. | ||
7798 | |||
7799 | If a recipe wishes to override the default behavior, it should set its | ||
7800 | own :term:`SOURCE_DATE_EPOCH` value:: | ||
7801 | |||
7802 | SOURCE_DATE_EPOCH = "1613559011" | ||
6946 | 7803 | ||
6947 | :term:`SOURCE_MIRROR_FETCH` | 7804 | :term:`SOURCE_MIRROR_FETCH` |
6948 | When you are fetching files to create a mirror of sources (i.e. | 7805 | When you are fetching files to create a mirror of sources (i.e. |
6949 | creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in | 7806 | creating a source mirror), setting :term:`SOURCE_MIRROR_FETCH` to "1" in |
6950 | your ``local.conf`` configuration file ensures the source for all | 7807 | your ``local.conf`` configuration file ensures the source for all |
6951 | recipes are fetched regardless of whether or not a recipe is | 7808 | recipes are fetched regardless of whether or not a recipe is |
6952 | compatible with the configuration. A recipe is considered | 7809 | compatible with the configuration. A recipe is considered |
@@ -6958,7 +7815,7 @@ system and gives an overview of their function and contents. | |||
6958 | 7815 | ||
6959 | .. note:: | 7816 | .. note:: |
6960 | 7817 | ||
6961 | Do not set the ``SOURCE_MIRROR_FETCH`` | 7818 | Do not set the :term:`SOURCE_MIRROR_FETCH` |
6962 | variable unless you are creating a source mirror. In other words, | 7819 | variable unless you are creating a source mirror. In other words, |
6963 | do not set the variable during a normal build. | 7820 | do not set the variable during a normal build. |
6964 | 7821 | ||
@@ -6968,20 +7825,132 @@ system and gives an overview of their function and contents. | |||
6968 | specified in :term:`SRC_URI`. | 7825 | specified in :term:`SRC_URI`. |
6969 | 7826 | ||
6970 | To use this variable, you must globally inherit the | 7827 | To use this variable, you must globally inherit the |
6971 | :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide | 7828 | :ref:`ref-classes-own-mirrors` class and then provide |
6972 | the URL to your mirrors. Here is the general syntax: | 7829 | the URL to your mirrors. Here is the general syntax:: |
6973 | :: | ||
6974 | 7830 | ||
6975 | INHERIT += "own-mirrors" | 7831 | INHERIT += "own-mirrors" |
6976 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" | 7832 | SOURCE_MIRROR_URL = "http://example.com/my_source_mirror" |
6977 | 7833 | ||
6978 | .. note:: | 7834 | .. note:: |
6979 | 7835 | ||
6980 | You can specify only a single URL in ``SOURCE_MIRROR_URL``. | 7836 | You can specify only a single URL in :term:`SOURCE_MIRROR_URL`. |
7837 | |||
7838 | :term:`SPDX_ARCHIVE_PACKAGED` | ||
7839 | This option allows to add to :term:`SPDX` output compressed archives | ||
7840 | of the files in the generated target packages. | ||
7841 | |||
7842 | Such archives are available in | ||
7843 | ``tmp/deploy/spdx/MACHINE/packages/packagename.tar.zst`` | ||
7844 | under the :term:`Build Directory`. | ||
7845 | |||
7846 | Enable this option as follows:: | ||
7847 | |||
7848 | SPDX_ARCHIVE_PACKAGED = "1" | ||
7849 | |||
7850 | According to our tests on release 4.1 "langdale", building | ||
7851 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling this | ||
7852 | option multiplied the size of the ``tmp/deploy/spdx`` directory by a | ||
7853 | factor of 13 (+1.6 GiB for this image), compared to just using the | ||
7854 | :ref:`ref-classes-create-spdx` class with no option. | ||
7855 | |||
7856 | Note that this option doesn't increase the size of :term:`SPDX` | ||
7857 | files in ``tmp/deploy/images/MACHINE``. | ||
7858 | |||
7859 | :term:`SPDX_ARCHIVE_SOURCES` | ||
7860 | This option allows to add to :term:`SPDX` output compressed archives | ||
7861 | of the sources for packages installed on the target. It currently | ||
7862 | only works when :term:`SPDX_INCLUDE_SOURCES` is set. | ||
7863 | |||
7864 | This is one way of fulfilling "source code access" license | ||
7865 | requirements. | ||
7866 | |||
7867 | Such source archives are available in | ||
7868 | ``tmp/deploy/spdx/MACHINE/recipes/recipe-packagename.tar.zst`` | ||
7869 | under the :term:`Build Directory`. | ||
7870 | |||
7871 | Enable this option as follows:: | ||
7872 | |||
7873 | SPDX_INCLUDE_SOURCES = "1" | ||
7874 | SPDX_ARCHIVE_SOURCES = "1" | ||
7875 | |||
7876 | According to our tests on release 4.1 "langdale", building | ||
7877 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling | ||
7878 | these options multiplied the size of the ``tmp/deploy/spdx`` | ||
7879 | directory by a factor of 11 (+1.4 GiB for this image), | ||
7880 | compared to just using the :ref:`ref-classes-create-spdx` | ||
7881 | class with no option. | ||
7882 | |||
7883 | Note that using this option only marginally increases the size | ||
7884 | of the :term:`SPDX` output in ``tmp/deploy/images/MACHINE/`` | ||
7885 | (+ 0.07\% with the tested image), compared to just enabling | ||
7886 | :term:`SPDX_INCLUDE_SOURCES`. | ||
7887 | |||
7888 | :term:`SPDX_CUSTOM_ANNOTATION_VARS` | ||
7889 | This option allows to associate `SPDX annotations | ||
7890 | <https://spdx.github.io/spdx-spec/v2.3/annotations/>`__ to a recipe, | ||
7891 | using the values of variables in the recipe:: | ||
7892 | |||
7893 | ANNOTATION1 = "First annotation for recipe" | ||
7894 | ANNOTATION2 = "Second annotation for recipe" | ||
7895 | SPDX_CUSTOM_ANNOTATION_VARS = "ANNOTATION1 ANNOTATION2" | ||
7896 | |||
7897 | This will add a new block to the recipe ``.sdpx.json`` output:: | ||
7898 | |||
7899 | "annotations": [ | ||
7900 | { | ||
7901 | "annotationDate": "2023-04-18T08:32:12Z", | ||
7902 | "annotationType": "OTHER", | ||
7903 | "annotator": "Tool: oe-spdx-creator - 1.0", | ||
7904 | "comment": "ANNOTATION1=First annotation for recipe" | ||
7905 | }, | ||
7906 | { | ||
7907 | "annotationDate": "2023-04-18T08:32:12Z", | ||
7908 | "annotationType": "OTHER", | ||
7909 | "annotator": "Tool: oe-spdx-creator - 1.0", | ||
7910 | "comment": "ANNOTATION2=Second annotation for recipe" | ||
7911 | } | ||
7912 | ], | ||
7913 | |||
7914 | :term:`SPDX_INCLUDE_SOURCES` | ||
7915 | This option allows to add a description of the source files used to build | ||
7916 | the host tools and the target packages, to the ``spdx.json`` files in | ||
7917 | ``tmp/deploy/spdx/MACHINE/recipes/`` under the :term:`Build Directory`. | ||
7918 | As a consequence, the ``spdx.json`` files under the ``by-namespace`` and | ||
7919 | ``packages`` subdirectories in ``tmp/deploy/spdx/MACHINE`` are also | ||
7920 | modified to include references to such source file descriptions. | ||
7921 | |||
7922 | Enable this option as follows:: | ||
7923 | |||
7924 | SPDX_INCLUDE_SOURCES = "1" | ||
7925 | |||
7926 | According to our tests on release 4.1 "langdale", building | ||
7927 | ``core-image-minimal`` for the ``qemux86-64`` machine, enabling | ||
7928 | this option multiplied the total size of the ``tmp/deploy/spdx`` | ||
7929 | directory by a factor of 3 (+291 MiB for this image), | ||
7930 | and the size of the ``IMAGE-MACHINE.spdx.tar.zst`` in | ||
7931 | ``tmp/deploy/images/MACHINE`` by a factor of 130 (+15 MiB for this | ||
7932 | image), compared to just using the :ref:`ref-classes-create-spdx` class | ||
7933 | with no option. | ||
7934 | |||
7935 | :term:`SPDX_NAMESPACE_PREFIX` | ||
7936 | This option could be used in order to change the prefix of ``spdxDocument`` | ||
7937 | and the prefix of ``documentNamespace``. It is set by default to | ||
7938 | ``http://spdx.org/spdxdoc``. | ||
7939 | |||
7940 | :term:`SPDX_PRETTY` | ||
7941 | This option makes the SPDX output more human-readable, using | ||
7942 | identation and newlines, instead of the default output in a | ||
7943 | single line:: | ||
7944 | |||
7945 | SPDX_PRETTY = "1" | ||
7946 | |||
7947 | The generated SPDX files are approximately 20% bigger, but | ||
7948 | this option is recommended if you want to inspect the SPDX | ||
7949 | output files with a text editor. | ||
6981 | 7950 | ||
6982 | :term:`SPDXLICENSEMAP` | 7951 | :term:`SPDXLICENSEMAP` |
6983 | Maps commonly used license names to their SPDX counterparts found in | 7952 | Maps commonly used license names to their SPDX counterparts found in |
6984 | ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` | 7953 | ``meta/files/common-licenses/``. For the default :term:`SPDXLICENSEMAP` |
6985 | mappings, see the ``meta/conf/licenses.conf`` file. | 7954 | mappings, see the ``meta/conf/licenses.conf`` file. |
6986 | 7955 | ||
6987 | For additional information, see the :term:`LICENSE` | 7956 | For additional information, see the :term:`LICENSE` |
@@ -7001,8 +7970,7 @@ system and gives an overview of their function and contents. | |||
7001 | U-Boot recipe. | 7970 | U-Boot recipe. |
7002 | 7971 | ||
7003 | The SPL file type is set to "null" by default in the ``u-boot.inc`` | 7972 | The SPL file type is set to "null" by default in the ``u-boot.inc`` |
7004 | file as follows: | 7973 | file as follows:: |
7005 | :: | ||
7006 | 7974 | ||
7007 | # Some versions of u-boot build an SPL (Second Program Loader) image that | 7975 | # Some versions of u-boot build an SPL (Second Program Loader) image that |
7008 | # should be packaged along with the u-boot binary as well as placed in the | 7976 | # should be packaged along with the u-boot binary as well as placed in the |
@@ -7013,171 +7981,132 @@ system and gives an overview of their function and contents. | |||
7013 | SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" | 7981 | SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" |
7014 | SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" | 7982 | SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}" |
7015 | 7983 | ||
7016 | The ``SPL_BINARY`` variable helps form | 7984 | The :term:`SPL_BINARY` variable helps form |
7017 | various ``SPL_*`` variables used by the OpenEmbedded build system. | 7985 | various ``SPL_*`` variables used by the OpenEmbedded build system. |
7018 | 7986 | ||
7019 | See the BeagleBone machine configuration example in the | 7987 | See the BeagleBone machine configuration example in the |
7020 | ":ref:`dev-manual/common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`" | 7988 | ":ref:`dev-manual/layers:adding a layer using the \`\`bitbake-layers\`\` script`" |
7021 | section in the Yocto Project Board Support Package Developer's Guide | 7989 | section in the Yocto Project Board Support Package Developer's Guide |
7022 | for additional information. | 7990 | for additional information. |
7023 | 7991 | ||
7024 | :term:`SRC_URI` | 7992 | :term:`SPL_MKIMAGE_DTCOPTS` |
7025 | The list of source files - local or remote. This variable tells the | 7993 | Options for the device tree compiler passed to ``mkimage -D`` feature |
7026 | OpenEmbedded build system which bits to pull in for the build and how | 7994 | while creating a FIT image with the :ref:`ref-classes-uboot-sign` |
7027 | to pull them in. For example, if the recipe or append file only needs | 7995 | class. If :term:`SPL_MKIMAGE_DTCOPTS` is not set then the |
7028 | to fetch a tarball from the Internet, the recipe or append file uses | 7996 | :ref:`ref-classes-uboot-sign` class will not pass the ``-D`` option |
7029 | a single ``SRC_URI`` entry. On the other hand, if the recipe or | 7997 | to ``mkimage``. |
7030 | append file needs to fetch a tarball, apply two patches, and include | ||
7031 | a custom file, the recipe or append file would include four instances | ||
7032 | of the variable. | ||
7033 | |||
7034 | The following list explains the available URI protocols. URI | ||
7035 | protocols are highly dependent on particular BitBake Fetcher | ||
7036 | submodules. Depending on the fetcher BitBake uses, various URL | ||
7037 | parameters are employed. For specifics on the supported Fetchers, see | ||
7038 | the ":ref:`Fetchers <bitbake:bitbake-user-manual/bitbake-user-manual-fetching:fetchers>`" section in the | ||
7039 | BitBake User Manual. | ||
7040 | |||
7041 | - ``file://`` - Fetches files, which are usually files shipped | ||
7042 | with the :term:`Metadata`, from the local machine (e.g. | ||
7043 | :ref:`patch <overview-manual/concepts:patching>` files). | ||
7044 | The path is relative to the :term:`FILESPATH` | ||
7045 | variable. Thus, the build system searches, in order, from the | ||
7046 | following directories, which are assumed to be a subdirectories of | ||
7047 | the directory in which the recipe file (``.bb``) or append file | ||
7048 | (``.bbappend``) resides: | ||
7049 | |||
7050 | - ``${BPN}`` - The base recipe name without any special suffix | ||
7051 | or version numbers. | ||
7052 | |||
7053 | - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and | ||
7054 | version but without any special package name suffix. | ||
7055 | |||
7056 | - *files -* Files within a directory, which is named ``files`` | ||
7057 | and is also alongside the recipe or append file. | ||
7058 | 7998 | ||
7059 | .. note:: | 7999 | The default value is set to "" by the :ref:`ref-classes-uboot-config` |
8000 | class. | ||
8001 | |||
8002 | :term:`SPL_SIGN_ENABLE` | ||
8003 | Enable signing of the U-Boot FIT image. The default value is "0". | ||
8004 | This variable is used by the :ref:`ref-classes-uboot-sign` class. | ||
7060 | 8005 | ||
7061 | If you want the build system to pick up files specified through | 8006 | :term:`SPL_SIGN_KEYDIR` |
7062 | a | 8007 | Location of the directory containing the RSA key and certificate used for |
7063 | SRC_URI | 8008 | signing the U-Boot FIT image, used by the :ref:`ref-classes-uboot-sign` |
7064 | statement from your append file, you need to be sure to extend | 8009 | class. |
7065 | the | 8010 | |
7066 | FILESPATH | 8011 | :term:`SPL_SIGN_KEYNAME` |
7067 | variable by also using the | 8012 | The name of keys used by the :ref:`ref-classes-kernel-fitimage` class |
7068 | FILESEXTRAPATHS | 8013 | for signing U-Boot FIT image stored in the :term:`SPL_SIGN_KEYDIR` |
7069 | variable from within your append file. | 8014 | directory. If we have for example a ``dev.key`` key and a ``dev.crt`` |
8015 | certificate stored in the :term:`SPL_SIGN_KEYDIR` directory, you will | ||
8016 | have to set :term:`SPL_SIGN_KEYNAME` to ``dev``. | ||
7070 | 8017 | ||
7071 | - ``bzr://`` - Fetches files from a Bazaar revision control | 8018 | :term:`SPLASH` |
7072 | repository. | 8019 | This variable, used by the :ref:`ref-classes-image` class, allows |
8020 | to choose splashscreen applications. Set it to the names of packages | ||
8021 | for such applications to use. This variable is set by default to | ||
8022 | ``psplash``. | ||
7073 | 8023 | ||
7074 | - ``git://`` - Fetches files from a Git revision control | 8024 | :term:`SPLASH_IMAGES` |
7075 | repository. | 8025 | This variable, used by the ``psplash`` recipe, allows to customize |
8026 | the default splashscreen image. | ||
7076 | 8027 | ||
7077 | - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service) | 8028 | Specified images in PNG format are converted to ``.h`` files by the recipe, |
7078 | revision control repository. | 8029 | and are included in the ``psplash`` binary, so you won't find them in |
8030 | the root filesystem. | ||
7079 | 8031 | ||
7080 | - ``repo://`` - Fetches files from a repo (Git) repository. | 8032 | To make such a change, it is recommended to customize the |
8033 | ``psplash`` recipe in a custom layer. Here is an example structure for | ||
8034 | an ``ACME`` board:: | ||
7081 | 8035 | ||
7082 | - ``ccrc://`` - Fetches files from a ClearCase repository. | 8036 | meta-acme/recipes-core/psplash |
8037 | ├── files | ||
8038 | │  └── logo-acme.png | ||
8039 | └── psplash_%.bbappend | ||
7083 | 8040 | ||
7084 | - ``http://`` - Fetches files from the Internet using ``http``. | 8041 | And here are the contents of the ``psplash_%.bbappend`` file in |
8042 | this example:: | ||
7085 | 8043 | ||
7086 | - ``https://`` - Fetches files from the Internet using ``https``. | 8044 | SPLASH_IMAGES = "file://logo-acme.png;outsuffix=default" |
8045 | FILESEXTRAPATHS:prepend := "${THISDIR}/files:" | ||
7087 | 8046 | ||
7088 | - ``ftp://`` - Fetches files from the Internet using ``ftp``. | 8047 | You could even add specific configuration options for ``psplash``, |
8048 | for example:: | ||
7089 | 8049 | ||
7090 | - ``cvs://`` - Fetches files from a CVS revision control | 8050 | EXTRA_OECONF += "--disable-startup-msg --enable-img-fullscreen" |
7091 | repository. | ||
7092 | 8051 | ||
7093 | - ``hg://`` - Fetches files from a Mercurial (``hg``) revision | 8052 | For information on append files, see the |
7094 | control repository. | 8053 | ":ref:`dev-manual/layers:appending other layers metadata with your layer`" |
8054 | section. | ||
7095 | 8055 | ||
7096 | - ``p4://`` - Fetches files from a Perforce (``p4``) revision | 8056 | :term:`SRCREV_FORMAT` |
7097 | control repository. | 8057 | See :term:`bitbake:SRCREV_FORMAT` in the BitBake manual. |
7098 | 8058 | ||
7099 | - ``ssh://`` - Fetches files from a secure shell. | 8059 | :term:`SRC_URI` |
7100 | 8060 | ||
7101 | - ``svn://`` - Fetches files from a Subversion (``svn``) revision | 8061 | See the BitBake manual for the initial description for this variable: |
7102 | control repository. | 8062 | :term:`bitbake:SRC_URI`. |
7103 | 8063 | ||
7104 | - ``npm://`` - Fetches JavaScript modules from a registry. | 8064 | The following features are added by OpenEmbedded and the Yocto Project. |
7105 | 8065 | ||
7106 | Standard and recipe-specific options for ``SRC_URI`` exist. Here are | 8066 | There are standard and recipe-specific options. Here are standard ones: |
7107 | standard options: | ||
7108 | 8067 | ||
7109 | - ``apply`` - Whether to apply the patch or not. The default | 8068 | - ``apply`` --- whether to apply the patch or not. The default |
7110 | action is to apply the patch. | 8069 | action is to apply the patch. |
7111 | 8070 | ||
7112 | - ``striplevel`` - Which striplevel to use when applying the | 8071 | - ``striplevel`` --- which striplevel to use when applying the |
7113 | patch. The default level is 1. | 8072 | patch. The default level is 1. |
7114 | 8073 | ||
7115 | - ``patchdir`` - Specifies the directory in which the patch should | 8074 | - ``patchdir`` --- specifies the directory in which the patch should |
7116 | be applied. The default is ``${``\ :term:`S`\ ``}``. | 8075 | be applied. The default is ``${``\ :term:`S`\ ``}``. |
7117 | 8076 | ||
7118 | Here are options specific to recipes building code from a revision | 8077 | Here are options specific to recipes building code from a revision |
7119 | control system: | 8078 | control system: |
7120 | 8079 | ||
7121 | - ``mindate`` - Apply the patch only if | 8080 | - ``mindate`` --- apply the patch only if |
7122 | :term:`SRCDATE` is equal to or greater than | 8081 | :term:`SRCDATE` is equal to or greater than |
7123 | ``mindate``. | 8082 | ``mindate``. |
7124 | 8083 | ||
7125 | - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later | 8084 | - ``maxdate`` --- apply the patch only if :term:`SRCDATE` is not later |
7126 | than ``maxdate``. | 8085 | than ``maxdate``. |
7127 | 8086 | ||
7128 | - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or | 8087 | - ``minrev`` --- apply the patch only if :term:`SRCREV` is equal to or |
7129 | greater than ``minrev``. | 8088 | greater than ``minrev``. |
7130 | 8089 | ||
7131 | - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later | 8090 | - ``maxrev`` --- apply the patch only if :term:`SRCREV` is not later |
7132 | than ``maxrev``. | 8091 | than ``maxrev``. |
7133 | 8092 | ||
7134 | - ``rev`` - Apply the patch only if ``SRCREV`` is equal to | 8093 | - ``rev`` --- apply the patch only if :term:`SRCREV` is equal to |
7135 | ``rev``. | 8094 | ``rev``. |
7136 | 8095 | ||
7137 | - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to | 8096 | - ``notrev`` --- apply the patch only if :term:`SRCREV` is not equal to |
7138 | ``rev``. | 8097 | ``rev``. |
7139 | 8098 | ||
7140 | Here are some additional options worth mentioning: | 8099 | .. note:: |
7141 | |||
7142 | - ``unpack`` - Controls whether or not to unpack the file if it is | ||
7143 | an archive. The default action is to unpack the file. | ||
7144 | |||
7145 | - ``destsuffix`` - Places the file (or extracts its contents) into | ||
7146 | the specified subdirectory of :term:`WORKDIR` when | ||
7147 | the Git fetcher is used. | ||
7148 | |||
7149 | - ``subdir`` - Places the file (or extracts its contents) into the | ||
7150 | specified subdirectory of ``WORKDIR`` when the local (``file://``) | ||
7151 | fetcher is used. | ||
7152 | |||
7153 | - ``localdir`` - Places the file (or extracts its contents) into | ||
7154 | the specified subdirectory of ``WORKDIR`` when the CVS fetcher is | ||
7155 | used. | ||
7156 | |||
7157 | - ``subpath`` - Limits the checkout to a specific subpath of the | ||
7158 | tree when using the Git fetcher is used. | ||
7159 | |||
7160 | - ``name`` - Specifies a name to be used for association with | ||
7161 | ``SRC_URI`` checksums or :term:`SRCREV` when you have more than one | ||
7162 | file or git repository specified in ``SRC_URI``. For example: | ||
7163 | :: | ||
7164 | |||
7165 | SRC_URI = "git://example.com/foo.git;name=first \ | ||
7166 | git://example.com/bar.git;name=second \ | ||
7167 | http://example.com/file.tar.gz;name=third" | ||
7168 | |||
7169 | SRCREV_first = "f1d2d2f924e986ac86fdf7b36c94bcdf32beec15" | ||
7170 | SRCREV_second = "e242ed3bffccdf271b7fbaf34ed72d089537b42f" | ||
7171 | SRC_URI[third.sha256sum] = "13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de" | ||
7172 | |||
7173 | 8100 | ||
7174 | - ``downloadfilename`` - Specifies the filename used when storing | 8101 | If you want the build system to pick up files specified through |
7175 | the downloaded file. | 8102 | a :term:`SRC_URI` statement from your append file, you need to be |
8103 | sure to extend the :term:`FILESPATH` variable by also using the | ||
8104 | :term:`FILESEXTRAPATHS` variable from within your append file. | ||
7176 | 8105 | ||
7177 | :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` | 8106 | :term:`SRC_URI_OVERRIDES_PACKAGE_ARCH` |
7178 | By default, the OpenEmbedded build system automatically detects | 8107 | By default, the OpenEmbedded build system automatically detects |
7179 | whether ``SRC_URI`` contains files that are machine-specific. If so, | 8108 | whether :term:`SRC_URI` contains files that are machine-specific. If so, |
7180 | the build system automatically changes ``PACKAGE_ARCH``. Setting this | 8109 | the build system automatically changes :term:`PACKAGE_ARCH`. Setting this |
7181 | variable to "0" disables this behavior. | 8110 | variable to "0" disables this behavior. |
7182 | 8111 | ||
7183 | :term:`SRCDATE` | 8112 | :term:`SRCDATE` |
@@ -7189,18 +8118,16 @@ system and gives an overview of their function and contents. | |||
7189 | Returns the version string of the current package. This string is | 8118 | Returns the version string of the current package. This string is |
7190 | used to help define the value of :term:`PV`. | 8119 | used to help define the value of :term:`PV`. |
7191 | 8120 | ||
7192 | The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` | 8121 | The :term:`SRCPV` variable is defined in the ``meta/conf/bitbake.conf`` |
7193 | configuration file in the :term:`Source Directory` as | 8122 | configuration file in the :term:`Source Directory` as |
7194 | follows: | 8123 | follows:: |
7195 | :: | ||
7196 | 8124 | ||
7197 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" | 8125 | SRCPV = "${@bb.fetch2.get_srcrev(d)}" |
7198 | 8126 | ||
7199 | Recipes that need to define ``PV`` do so with the help of the | 8127 | Recipes that need to define :term:`PV` do so with the help of the |
7200 | ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) | 8128 | :term:`SRCPV`. For example, the ``ofono`` recipe (``ofono_git.bb``) |
7201 | located in ``meta/recipes-connectivity`` in the Source Directory | 8129 | located in ``meta/recipes-connectivity`` in the Source Directory |
7202 | defines ``PV`` as follows: | 8130 | defines :term:`PV` as follows:: |
7203 | :: | ||
7204 | 8131 | ||
7205 | PV = "0.12-git${SRCPV}" | 8132 | PV = "0.12-git${SRCPV}" |
7206 | 8133 | ||
@@ -7209,26 +8136,76 @@ system and gives an overview of their function and contents. | |||
7209 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note | 8136 | variable applies to Subversion, Git, Mercurial, and Bazaar only. Note |
7210 | that if you want to build a fixed revision and you want to avoid | 8137 | that if you want to build a fixed revision and you want to avoid |
7211 | performing a query on the remote repository every time BitBake parses | 8138 | performing a query on the remote repository every time BitBake parses |
7212 | your recipe, you should specify a ``SRCREV`` that is a full revision | 8139 | your recipe, you should specify a :term:`SRCREV` that is a full revision |
7213 | identifier and not just a tag. | 8140 | identifier (e.g. the full SHA hash in git) and not just a tag. |
7214 | 8141 | ||
7215 | .. note:: | 8142 | .. note:: |
7216 | 8143 | ||
7217 | For information on limitations when inheriting the latest revision | 8144 | For information on limitations when inheriting the latest revision |
7218 | of software using ``SRCREV``, see the :term:`AUTOREV` variable | 8145 | of software using :term:`SRCREV`, see the :term:`AUTOREV` variable |
7219 | description and the | 8146 | description and the |
7220 | ":ref:`dev-manual/common-tasks:automatically incrementing a package version number`" | 8147 | ":ref:`dev-manual/packages:automatically incrementing a package version number`" |
7221 | section, which is in the Yocto Project Development Tasks Manual. | 8148 | section, which is in the Yocto Project Development Tasks Manual. |
7222 | 8149 | ||
8150 | :term:`SRCTREECOVEREDTASKS` | ||
8151 | A list of tasks that are typically not relevant (and therefore skipped) | ||
8152 | when building using the :ref:`ref-classes-externalsrc` | ||
8153 | class. The default value as set in that class file is the set of tasks | ||
8154 | that are rarely needed when using external source:: | ||
8155 | |||
8156 | SRCTREECOVEREDTASKS ?= "do_patch do_unpack do_fetch" | ||
8157 | |||
8158 | The notable exception is when processing external kernel source as | ||
8159 | defined in the :ref:`ref-classes-kernel-yocto` class file (formatted for | ||
8160 | aesthetics):: | ||
8161 | |||
8162 | SRCTREECOVEREDTASKS += "\ | ||
8163 | do_validate_branches \ | ||
8164 | do_kernel_configcheck \ | ||
8165 | do_kernel_checkout \ | ||
8166 | do_fetch \ | ||
8167 | do_unpack \ | ||
8168 | do_patch \ | ||
8169 | " | ||
8170 | |||
8171 | See the associated :term:`EXTERNALSRC` and :term:`EXTERNALSRC_BUILD` | ||
8172 | variables for more information. | ||
8173 | |||
7223 | :term:`SSTATE_DIR` | 8174 | :term:`SSTATE_DIR` |
7224 | The directory for the shared state cache. | 8175 | The directory for the shared state cache. |
7225 | 8176 | ||
8177 | :term:`SSTATE_EXCLUDEDEPS_SYSROOT` | ||
8178 | This variable allows to specify indirect dependencies to exclude | ||
8179 | from sysroots, for example to avoid the situations when a dependency on | ||
8180 | any ``-native`` recipe will pull in all dependencies of that recipe | ||
8181 | in the recipe sysroot. This behaviour might not always be wanted, | ||
8182 | for example when that ``-native`` recipe depends on build tools | ||
8183 | that are not relevant for the current recipe. | ||
8184 | |||
8185 | This way, irrelevant dependencies are ignored, which could have | ||
8186 | prevented the reuse of prebuilt artifacts stored in the Shared | ||
8187 | State Cache. | ||
8188 | |||
8189 | :term:`SSTATE_EXCLUDEDEPS_SYSROOT` is evaluated as two regular | ||
8190 | expressions of recipe and dependency to ignore. An example | ||
8191 | is the rule in :oe_git:`meta/conf/layer.conf </openembedded-core/tree/meta/conf/layer.conf>`:: | ||
8192 | |||
8193 | # Nothing needs to depend on libc-initial | ||
8194 | # base-passwd/shadow-sysroot don't need their dependencies | ||
8195 | SSTATE_EXCLUDEDEPS_SYSROOT += "\ | ||
8196 | .*->.*-initial.* \ | ||
8197 | .*(base-passwd|shadow-sysroot)->.* \ | ||
8198 | " | ||
8199 | |||
8200 | The ``->`` substring represents the dependency between | ||
8201 | the two regular expressions. | ||
8202 | |||
7226 | :term:`SSTATE_MIRROR_ALLOW_NETWORK` | 8203 | :term:`SSTATE_MIRROR_ALLOW_NETWORK` |
7227 | If set to "1", allows fetches from mirrors that are specified in | 8204 | If set to "1", allows fetches from mirrors that are specified in |
7228 | :term:`SSTATE_MIRRORS` to work even when | 8205 | :term:`SSTATE_MIRRORS` to work even when |
7229 | fetching from the network is disabled by setting ``BB_NO_NETWORK`` to | 8206 | fetching from the network is disabled by setting :term:`BB_NO_NETWORK` to |
7230 | "1". Using the ``SSTATE_MIRROR_ALLOW_NETWORK`` variable is useful if | 8207 | "1". Using the :term:`SSTATE_MIRROR_ALLOW_NETWORK` variable is useful if |
7231 | you have set ``SSTATE_MIRRORS`` to point to an internal server for | 8208 | you have set :term:`SSTATE_MIRRORS` to point to an internal server for |
7232 | your shared state cache, but you want to disable any other fetching | 8209 | your shared state cache, but you want to disable any other fetching |
7233 | from the network. | 8210 | from the network. |
7234 | 8211 | ||
@@ -7246,26 +8223,33 @@ system and gives an overview of their function and contents. | |||
7246 | 8223 | ||
7247 | When pointing to sstate build artifacts on another machine that uses | 8224 | When pointing to sstate build artifacts on another machine that uses |
7248 | a different GCC version for native builds, you must configure | 8225 | a different GCC version for native builds, you must configure |
7249 | ``SSTATE_MIRRORS`` with a regular expression that maps local search | 8226 | :term:`SSTATE_MIRRORS` with a regular expression that maps local search |
7250 | paths to server paths. The paths need to take into account | 8227 | paths to server paths. The paths need to take into account |
7251 | :term:`NATIVELSBSTRING` set by the | 8228 | :term:`NATIVELSBSTRING` set by the :ref:`ref-classes-uninative` class. |
7252 | :ref:`uninative <ref-classes-uninative>` class. For example, the | 8229 | For example, the following maps the local search path ``universal-4.9`` |
7253 | following maps the local search path ``universal-4.9`` to the | 8230 | to the server-provided path server_url_sstate_path:: |
7254 | server-provided path server_url_sstate_path: | ||
7255 | :: | ||
7256 | 8231 | ||
7257 | SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n" | 8232 | SSTATE_MIRRORS ?= "file://universal-4.9/(.*) https://server_url_sstate_path/universal-4.8/\1" |
7258 | 8233 | ||
7259 | If a mirror uses the same structure as | 8234 | If a mirror uses the same structure as |
7260 | :term:`SSTATE_DIR`, you need to add "PATH" at the | 8235 | :term:`SSTATE_DIR`, you need to add "PATH" at the |
7261 | end as shown in the examples below. The build system substitutes the | 8236 | end as shown in the examples below. The build system substitutes the |
7262 | correct path within the directory structure. | 8237 | correct path within the directory structure:: |
7263 | :: | ||
7264 | 8238 | ||
7265 | SSTATE_MIRRORS ?= "\ | 8239 | SSTATE_MIRRORS ?= "\ |
7266 | file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \ | 8240 | file://.* https://someserver.tld/share/sstate/PATH;downloadfilename=PATH \ |
7267 | file://.* file:///some-local-dir/sstate/PATH" | 8241 | file://.* file:///some-local-dir/sstate/PATH" |
7268 | 8242 | ||
8243 | The Yocto Project actually shares the cache data objects built by its | ||
8244 | autobuilder:: | ||
8245 | |||
8246 | SSTATE_MIRRORS ?= "file://.* http://cdn.jsdelivr.net/yocto/sstate/all/PATH;downloadfilename=PATH" | ||
8247 | |||
8248 | As such binary artifacts are built for the generic QEMU machines | ||
8249 | supported by the various Poky releases, they are less likely to be | ||
8250 | reusable in real projects building binaries optimized for a specific | ||
8251 | CPU family. | ||
8252 | |||
7269 | :term:`SSTATE_SCAN_FILES` | 8253 | :term:`SSTATE_SCAN_FILES` |
7270 | Controls the list of files the OpenEmbedded build system scans for | 8254 | Controls the list of files the OpenEmbedded build system scans for |
7271 | hardcoded installation paths. The variable uses a space-separated | 8255 | hardcoded installation paths. The variable uses a space-separated |
@@ -7276,14 +8260,12 @@ system and gives an overview of their function and contents. | |||
7276 | (sstate) object during the first stage of preparing the sysroots. | 8260 | (sstate) object during the first stage of preparing the sysroots. |
7277 | That object is scanned for hardcoded paths for original installation | 8261 | That object is scanned for hardcoded paths for original installation |
7278 | locations. The list of files that are scanned for paths is controlled | 8262 | locations. The list of files that are scanned for paths is controlled |
7279 | by the ``SSTATE_SCAN_FILES`` variable. Typically, recipes add files | 8263 | by the :term:`SSTATE_SCAN_FILES` variable. Typically, recipes add files |
7280 | they want to be scanned to the value of ``SSTATE_SCAN_FILES`` rather | 8264 | they want to be scanned to the value of :term:`SSTATE_SCAN_FILES` rather |
7281 | than the variable being comprehensively set. The | 8265 | than the variable being comprehensively set. The |
7282 | :ref:`sstate <ref-classes-sstate>` class specifies the default list | 8266 | :ref:`ref-classes-sstate` class specifies the default list of files. |
7283 | of files. | ||
7284 | 8267 | ||
7285 | For details on the process, see the | 8268 | For details on the process, see the :ref:`ref-classes-staging` class. |
7286 | :ref:`staging <ref-classes-staging>` class. | ||
7287 | 8269 | ||
7288 | :term:`STAGING_BASE_LIBDIR_NATIVE` | 8270 | :term:`STAGING_BASE_LIBDIR_NATIVE` |
7289 | Specifies the path to the ``/lib`` subdirectory of the sysroot | 8271 | Specifies the path to the ``/lib`` subdirectory of the sysroot |
@@ -7339,7 +8321,7 @@ system and gives an overview of their function and contents. | |||
7339 | 8321 | ||
7340 | .. note:: | 8322 | .. note:: |
7341 | 8323 | ||
7342 | Recipes should never write files directly under the ``STAGING_DIR`` | 8324 | Recipes should never write files directly under the :term:`STAGING_DIR` |
7343 | directory because the OpenEmbedded build system manages the | 8325 | directory because the OpenEmbedded build system manages the |
7344 | directory automatically. Instead, files should be installed to | 8326 | directory automatically. Instead, files should be installed to |
7345 | ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` | 8327 | ``${``\ :term:`D`\ ``}`` within your recipe's :ref:`ref-tasks-install` |
@@ -7352,9 +8334,9 @@ system and gives an overview of their function and contents. | |||
7352 | For most recipes, this sysroot is the one in which that recipe's | 8334 | For most recipes, this sysroot is the one in which that recipe's |
7353 | :ref:`ref-tasks-populate_sysroot` task copies | 8335 | :ref:`ref-tasks-populate_sysroot` task copies |
7354 | files. Exceptions include ``-native`` recipes, where the | 8336 | files. Exceptions include ``-native`` recipes, where the |
7355 | ``do_populate_sysroot`` task instead uses | 8337 | :ref:`ref-tasks-populate_sysroot` task instead uses |
7356 | :term:`STAGING_DIR_NATIVE`. Depending on | 8338 | :term:`STAGING_DIR_NATIVE`. Depending on |
7357 | the type of recipe and the build target, ``STAGING_DIR_HOST`` can | 8339 | the type of recipe and the build target, :term:`STAGING_DIR_HOST` can |
7358 | have the following values: | 8340 | have the following values: |
7359 | 8341 | ||
7360 | - For recipes building for the target machine, the value is | 8342 | - For recipes building for the target machine, the value is |
@@ -7368,11 +8350,11 @@ system and gives an overview of their function and contents. | |||
7368 | 8350 | ||
7369 | ``-native`` recipes are not installed into host paths like such | 8351 | ``-native`` recipes are not installed into host paths like such |
7370 | as ``/usr``. Rather, these recipes are installed into | 8352 | as ``/usr``. Rather, these recipes are installed into |
7371 | ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, | 8353 | :term:`STAGING_DIR_NATIVE`. When compiling ``-native`` recipes, |
7372 | standard build environment variables such as | 8354 | standard build environment variables such as |
7373 | :term:`CPPFLAGS` and | 8355 | :term:`CPPFLAGS` and |
7374 | :term:`CFLAGS` are set up so that both host paths | 8356 | :term:`CFLAGS` are set up so that both host paths |
7375 | and ``STAGING_DIR_NATIVE`` are searched for libraries and | 8357 | and :term:`STAGING_DIR_NATIVE` are searched for libraries and |
7376 | headers using, for example, GCC's ``-isystem`` option. | 8358 | headers using, for example, GCC's ``-isystem`` option. |
7377 | 8359 | ||
7378 | Thus, the emphasis is that the ``STAGING_DIR*`` variables | 8360 | Thus, the emphasis is that the ``STAGING_DIR*`` variables |
@@ -7380,28 +8362,33 @@ system and gives an overview of their function and contents. | |||
7380 | :ref:`ref-tasks-configure`, | 8362 | :ref:`ref-tasks-configure`, |
7381 | :ref:`ref-tasks-compile`, and | 8363 | :ref:`ref-tasks-compile`, and |
7382 | :ref:`ref-tasks-install`. Having the real system | 8364 | :ref:`ref-tasks-install`. Having the real system |
7383 | root correspond to ``STAGING_DIR_HOST`` makes conceptual sense | 8365 | root correspond to :term:`STAGING_DIR_HOST` makes conceptual sense |
7384 | for ``-native`` recipes, as they make use of host headers and | 8366 | for ``-native`` recipes, as they make use of host headers and |
7385 | libraries. | 8367 | libraries. |
7386 | 8368 | ||
8369 | Check :term:`RECIPE_SYSROOT` and :term:`RECIPE_SYSROOT_NATIVE`. | ||
8370 | |||
7387 | :term:`STAGING_DIR_NATIVE` | 8371 | :term:`STAGING_DIR_NATIVE` |
7388 | Specifies the path to the sysroot directory used when building | 8372 | Specifies the path to the sysroot directory used when building |
7389 | components that run on the build host itself. | 8373 | components that run on the build host itself. |
7390 | 8374 | ||
8375 | The default value is ``"${RECIPE_SYSROOT_NATIVE}"``, | ||
8376 | check :term:`RECIPE_SYSROOT_NATIVE`. | ||
8377 | |||
7391 | :term:`STAGING_DIR_TARGET` | 8378 | :term:`STAGING_DIR_TARGET` |
7392 | Specifies the path to the sysroot used for the system for which the | 8379 | Specifies the path to the sysroot used for the system for which the |
7393 | component generates code. For components that do not generate code, | 8380 | component generates code. For components that do not generate code, |
7394 | which is the majority, ``STAGING_DIR_TARGET`` is set to match | 8381 | which is the majority, :term:`STAGING_DIR_TARGET` is set to match |
7395 | :term:`STAGING_DIR_HOST`. | 8382 | :term:`STAGING_DIR_HOST`. |
7396 | 8383 | ||
7397 | Some recipes build binaries that can run on the target system but | 8384 | Some recipes build binaries that can run on the target system but those |
7398 | those binaries in turn generate code for another different system | 8385 | binaries in turn generate code for another different system (e.g. |
7399 | (e.g. cross-canadian recipes). Using terminology from GNU, the | 8386 | :ref:`ref-classes-cross-canadian` recipes). Using terminology from GNU, |
7400 | primary system is referred to as the "HOST" and the secondary, or | 8387 | the primary system is referred to as the "HOST" and the secondary, or |
7401 | different, system is referred to as the "TARGET". Thus, the binaries | 8388 | different, system is referred to as the "TARGET". Thus, the binaries |
7402 | run on the "HOST" system and generate binaries for the "TARGET" | 8389 | run on the "HOST" system and generate binaries for the "TARGET" |
7403 | system. The ``STAGING_DIR_HOST`` variable points to the sysroot used | 8390 | system. The :term:`STAGING_DIR_HOST` variable points to the sysroot used |
7404 | for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the | 8391 | for the "HOST" system, while :term:`STAGING_DIR_TARGET` points to the |
7405 | sysroot used for the "TARGET" system. | 8392 | sysroot used for the "TARGET" system. |
7406 | 8393 | ||
7407 | :term:`STAGING_ETCDIR_NATIVE` | 8394 | :term:`STAGING_ETCDIR_NATIVE` |
@@ -7426,7 +8413,7 @@ system and gives an overview of their function and contents. | |||
7426 | Points to the directory containing the kernel build artifacts. | 8413 | Points to the directory containing the kernel build artifacts. |
7427 | Recipes building software that needs to access kernel build artifacts | 8414 | Recipes building software that needs to access kernel build artifacts |
7428 | (e.g. ``systemtap-uprobes``) can look in the directory specified with | 8415 | (e.g. ``systemtap-uprobes``) can look in the directory specified with |
7429 | the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts | 8416 | the :term:`STAGING_KERNEL_BUILDDIR` variable to find these artifacts |
7430 | after the kernel has been built. | 8417 | after the kernel has been built. |
7431 | 8418 | ||
7432 | :term:`STAGING_KERNEL_DIR` | 8419 | :term:`STAGING_KERNEL_DIR` |
@@ -7446,9 +8433,8 @@ system and gives an overview of their function and contents. | |||
7446 | Specifies the base path used to create recipe stamp files. The path | 8433 | Specifies the base path used to create recipe stamp files. The path |
7447 | to an actual stamp file is constructed by evaluating this string and | 8434 | to an actual stamp file is constructed by evaluating this string and |
7448 | then appending additional information. Currently, the default | 8435 | then appending additional information. Currently, the default |
7449 | assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` | 8436 | assignment for :term:`STAMP` as set in the ``meta/conf/bitbake.conf`` |
7450 | file is: | 8437 | file is:: |
7451 | :: | ||
7452 | 8438 | ||
7453 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" | 8439 | STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" |
7454 | 8440 | ||
@@ -7463,6 +8449,9 @@ system and gives an overview of their function and contents. | |||
7463 | :term:`PV`, and :term:`PR` for related variable | 8449 | :term:`PV`, and :term:`PR` for related variable |
7464 | information. | 8450 | information. |
7465 | 8451 | ||
8452 | :term:`STAMPCLEAN` | ||
8453 | See :term:`bitbake:STAMPCLEAN` in the BitBake manual. | ||
8454 | |||
7466 | :term:`STAMPS_DIR` | 8455 | :term:`STAMPS_DIR` |
7467 | Specifies the base directory in which the OpenEmbedded build system | 8456 | Specifies the base directory in which the OpenEmbedded build system |
7468 | places stamps. The default directory is ``${TMPDIR}/stamps``. | 8457 | places stamps. The default directory is ``${TMPDIR}/stamps``. |
@@ -7474,8 +8463,8 @@ system and gives an overview of their function and contents. | |||
7474 | :term:`SUMMARY` | 8463 | :term:`SUMMARY` |
7475 | The short (72 characters or less) summary of the binary package for | 8464 | The short (72 characters or less) summary of the binary package for |
7476 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, | 8465 | packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, |
7477 | ``SUMMARY`` is used to define the | 8466 | :term:`SUMMARY` is used to define the |
7478 | :term:`DESCRIPTION` variable if ``DESCRIPTION`` is | 8467 | :term:`DESCRIPTION` variable if :term:`DESCRIPTION` is |
7479 | not set in the recipe. | 8468 | not set in the recipe. |
7480 | 8469 | ||
7481 | :term:`SVNDIR` | 8470 | :term:`SVNDIR` |
@@ -7485,12 +8474,11 @@ system and gives an overview of their function and contents. | |||
7485 | :term:`SYSLINUX_DEFAULT_CONSOLE` | 8474 | :term:`SYSLINUX_DEFAULT_CONSOLE` |
7486 | Specifies the kernel boot default console. If you want to use a | 8475 | Specifies the kernel boot default console. If you want to use a |
7487 | console other than the default, set this variable in your recipe as | 8476 | console other than the default, set this variable in your recipe as |
7488 | follows where "X" is the console number you want to use: | 8477 | follows where "X" is the console number you want to use:: |
7489 | :: | ||
7490 | 8478 | ||
7491 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" | 8479 | SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" |
7492 | 8480 | ||
7493 | The :ref:`syslinux <ref-classes-syslinux>` class initially sets | 8481 | The :ref:`ref-classes-syslinux` class initially sets |
7494 | this variable to null but then checks for a value later. | 8482 | this variable to null but then checks for a value later. |
7495 | 8483 | ||
7496 | :term:`SYSLINUX_OPTS` | 8484 | :term:`SYSLINUX_OPTS` |
@@ -7498,15 +8486,14 @@ system and gives an overview of their function and contents. | |||
7498 | this variable in your recipe. If you want to list multiple options, | 8486 | this variable in your recipe. If you want to list multiple options, |
7499 | separate the options with a semicolon character (``;``). | 8487 | separate the options with a semicolon character (``;``). |
7500 | 8488 | ||
7501 | The :ref:`syslinux <ref-classes-syslinux>` class uses this variable | 8489 | The :ref:`ref-classes-syslinux` class uses this variable |
7502 | to create a set of options. | 8490 | to create a set of options. |
7503 | 8491 | ||
7504 | :term:`SYSLINUX_SERIAL` | 8492 | :term:`SYSLINUX_SERIAL` |
7505 | Specifies the alternate serial port or turns it off. To turn off | 8493 | Specifies the alternate serial port or turns it off. To turn off |
7506 | serial, set this variable to an empty string in your recipe. The | 8494 | serial, set this variable to an empty string in your recipe. The |
7507 | variable's default value is set in the | 8495 | variable's default value is set in the |
7508 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | 8496 | :ref:`ref-classes-syslinux` class as follows:: |
7509 | :: | ||
7510 | 8497 | ||
7511 | SYSLINUX_SERIAL ?= "0 115200" | 8498 | SYSLINUX_SERIAL ?= "0 115200" |
7512 | 8499 | ||
@@ -7514,9 +8501,8 @@ system and gives an overview of their function and contents. | |||
7514 | 8501 | ||
7515 | :term:`SYSLINUX_SERIAL_TTY` | 8502 | :term:`SYSLINUX_SERIAL_TTY` |
7516 | Specifies the alternate console=tty... kernel boot argument. The | 8503 | Specifies the alternate console=tty... kernel boot argument. The |
7517 | variable's default value is set in the | 8504 | variable's default value is set in the :ref:`ref-classes-syslinux` |
7518 | :ref:`syslinux <ref-classes-syslinux>` class as follows: | 8505 | class as follows:: |
7519 | :: | ||
7520 | 8506 | ||
7521 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" | 8507 | SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" |
7522 | 8508 | ||
@@ -7526,7 +8512,7 @@ system and gives an overview of their function and contents. | |||
7526 | An ``.LSS`` file used as the background for the VGA boot menu when | 8512 | An ``.LSS`` file used as the background for the VGA boot menu when |
7527 | you use the boot menu. You need to set this variable in your recipe. | 8513 | you use the boot menu. You need to set this variable in your recipe. |
7528 | 8514 | ||
7529 | The :ref:`syslinux <ref-classes-syslinux>` class checks for this | 8515 | The :ref:`ref-classes-syslinux` class checks for this |
7530 | variable and if found, the OpenEmbedded build system installs the | 8516 | variable and if found, the OpenEmbedded build system installs the |
7531 | splash screen. | 8517 | splash screen. |
7532 | 8518 | ||
@@ -7539,8 +8525,7 @@ system and gives an overview of their function and contents. | |||
7539 | :term:`SYSROOT_DIRS` | 8525 | :term:`SYSROOT_DIRS` |
7540 | Directories that are staged into the sysroot by the | 8526 | Directories that are staged into the sysroot by the |
7541 | :ref:`ref-tasks-populate_sysroot` task. By | 8527 | :ref:`ref-tasks-populate_sysroot` task. By |
7542 | default, the following directories are staged: | 8528 | default, the following directories are staged:: |
7543 | :: | ||
7544 | 8529 | ||
7545 | SYSROOT_DIRS = " \ | 8530 | SYSROOT_DIRS = " \ |
7546 | ${includedir} \ | 8531 | ${includedir} \ |
@@ -7548,33 +8533,67 @@ system and gives an overview of their function and contents. | |||
7548 | ${base_libdir} \ | 8533 | ${base_libdir} \ |
7549 | ${nonarch_base_libdir} \ | 8534 | ${nonarch_base_libdir} \ |
7550 | ${datadir} \ | 8535 | ${datadir} \ |
8536 | /sysroot-only \ | ||
7551 | " | 8537 | " |
7552 | 8538 | ||
7553 | :term:`SYSROOT_DIRS_BLACKLIST` | 8539 | :term:`SYSROOT_DIRS_IGNORE` |
7554 | Directories that are not staged into the sysroot by the | 8540 | Directories that are not staged into the sysroot by the |
7555 | :ref:`ref-tasks-populate_sysroot` task. You | 8541 | :ref:`ref-tasks-populate_sysroot` task. You |
7556 | can use this variable to exclude certain subdirectories of | 8542 | can use this variable to exclude certain subdirectories of |
7557 | directories listed in :term:`SYSROOT_DIRS` from | 8543 | directories listed in :term:`SYSROOT_DIRS` from |
7558 | staging. By default, the following directories are not staged: | 8544 | staging. By default, the following directories are not staged:: |
7559 | :: | ||
7560 | 8545 | ||
7561 | SYSROOT_DIRS_BLACKLIST = " \ | 8546 | SYSROOT_DIRS_IGNORE = " \ |
7562 | ${mandir} \ | 8547 | ${mandir} \ |
7563 | ${docdir} \ | 8548 | ${docdir} \ |
7564 | ${infodir} \ | 8549 | ${infodir} \ |
7565 | ${datadir}/locale \ | 8550 | ${datadir}/X11/locale \ |
7566 | ${datadir}/applications \ | 8551 | ${datadir}/applications \ |
8552 | ${datadir}/bash-completion \ | ||
7567 | ${datadir}/fonts \ | 8553 | ${datadir}/fonts \ |
8554 | ${datadir}/gtk-doc/html \ | ||
8555 | ${datadir}/installed-tests \ | ||
8556 | ${datadir}/locale \ | ||
7568 | ${datadir}/pixmaps \ | 8557 | ${datadir}/pixmaps \ |
8558 | ${datadir}/terminfo \ | ||
8559 | ${libdir}/${BPN}/ptest \ | ||
7569 | " | 8560 | " |
7570 | 8561 | ||
8562 | Consider the following example in which you need to manipulate this variable. | ||
8563 | Assume you have a recipe ``A`` that provides a shared library ``.so.*`` that is | ||
8564 | installed into a custom folder other than "``${libdir}``" | ||
8565 | or "``${base_libdir}``", let's say "``/opt/lib``". | ||
8566 | |||
8567 | .. note:: | ||
8568 | |||
8569 | This is not a recommended way to deal with shared libraries, but this | ||
8570 | is just to show the usefulness of setting :term:`SYSROOT_DIRS`. | ||
8571 | |||
8572 | When a recipe ``B`` :term:`DEPENDS` on ``A``, it means what is in | ||
8573 | :term:`SYSROOT_DIRS` will be copied from :term:`D` of the recipe ``B`` | ||
8574 | into ``B``'s :term:`SYSROOT_DESTDIR` that is "``${WORKDIR}/sysroot-destdir``". | ||
8575 | |||
8576 | Now, since ``/opt/lib`` is not in :term:`SYSROOT_DIRS`, it will never be copied to | ||
8577 | ``A``'s :term:`RECIPE_SYSROOT`, which is "``${WORKDIR}/recipe-sysroot``". So, | ||
8578 | the linking process will fail. | ||
8579 | |||
8580 | To fix this, you need to add ``/opt/lib`` to :term:`SYSROOT_DIRS`:: | ||
8581 | |||
8582 | SYSROOT_DIRS:append = " /opt/lib" | ||
8583 | |||
8584 | .. note:: | ||
8585 | Even after setting ``/opt/lib`` to :term:`SYSROOT_DIRS`, the linking process will still fail | ||
8586 | because the linker does not know that location, since :term:`TARGET_LDFLAGS` | ||
8587 | doesn't contain it (if your recipe is for the target). Therefore, so you should add:: | ||
8588 | |||
8589 | TARGET_LDFLAGS:append = " -L${RECIPE_SYSROOT}/opt/lib" | ||
8590 | |||
7571 | :term:`SYSROOT_DIRS_NATIVE` | 8591 | :term:`SYSROOT_DIRS_NATIVE` |
7572 | Extra directories staged into the sysroot by the | 8592 | Extra directories staged into the sysroot by the |
7573 | :ref:`ref-tasks-populate_sysroot` task for | 8593 | :ref:`ref-tasks-populate_sysroot` task for |
7574 | ``-native`` recipes, in addition to those specified in | 8594 | ``-native`` recipes, in addition to those specified in |
7575 | :term:`SYSROOT_DIRS`. By default, the following | 8595 | :term:`SYSROOT_DIRS`. By default, the following |
7576 | extra directories are staged: | 8596 | extra directories are staged:: |
7577 | :: | ||
7578 | 8597 | ||
7579 | SYSROOT_DIRS_NATIVE = " \ | 8598 | SYSROOT_DIRS_NATIVE = " \ |
7580 | ${bindir} \ | 8599 | ${bindir} \ |
@@ -7598,13 +8617,12 @@ system and gives an overview of their function and contents. | |||
7598 | processing on the staged files, or to stage additional files. | 8617 | processing on the staged files, or to stage additional files. |
7599 | 8618 | ||
7600 | :term:`SYSTEMD_AUTO_ENABLE` | 8619 | :term:`SYSTEMD_AUTO_ENABLE` |
7601 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8620 | When inheriting the :ref:`ref-classes-systemd` class, |
7602 | this variable specifies whether the specified service in | 8621 | this variable specifies whether the specified service in |
7603 | :term:`SYSTEMD_SERVICE` should start | 8622 | :term:`SYSTEMD_SERVICE` should start |
7604 | automatically or not. By default, the service is enabled to | 8623 | automatically or not. By default, the service is enabled to |
7605 | automatically start at boot time. The default setting is in the | 8624 | automatically start at boot time. The default setting is in the |
7606 | :ref:`systemd <ref-classes-systemd>` class as follows: | 8625 | :ref:`ref-classes-systemd` class as follows:: |
7607 | :: | ||
7608 | 8626 | ||
7609 | SYSTEMD_AUTO_ENABLE ??= "enable" | 8627 | SYSTEMD_AUTO_ENABLE ??= "enable" |
7610 | 8628 | ||
@@ -7612,25 +8630,22 @@ system and gives an overview of their function and contents. | |||
7612 | 8630 | ||
7613 | :term:`SYSTEMD_BOOT_CFG` | 8631 | :term:`SYSTEMD_BOOT_CFG` |
7614 | When :term:`EFI_PROVIDER` is set to | 8632 | When :term:`EFI_PROVIDER` is set to |
7615 | "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the | 8633 | "systemd-boot", the :term:`SYSTEMD_BOOT_CFG` variable specifies the |
7616 | configuration file that should be used. By default, the | 8634 | configuration file that should be used. By default, the |
7617 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8635 | :ref:`ref-classes-systemd-boot` class sets the |
7618 | ``SYSTEMD_BOOT_CFG`` as follows: | 8636 | :term:`SYSTEMD_BOOT_CFG` as follows:: |
7619 | :: | ||
7620 | 8637 | ||
7621 | SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf" | 8638 | SYSTEMD_BOOT_CFG ?= "${S}/loader.conf" |
7622 | 8639 | ||
7623 | For information on Systemd-boot, see the `Systemd-boot | 8640 | For information on Systemd-boot, see the `Systemd-boot |
7624 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | 8641 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. |
7625 | 8642 | ||
7626 | :term:`SYSTEMD_BOOT_ENTRIES` | 8643 | :term:`SYSTEMD_BOOT_ENTRIES` |
7627 | When :term:`EFI_PROVIDER` is set to | 8644 | When :term:`EFI_PROVIDER` is set to |
7628 | "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a | 8645 | "systemd-boot", the :term:`SYSTEMD_BOOT_ENTRIES` variable specifies a |
7629 | list of entry files (``*.conf``) to install that contain one boot | 8646 | list of entry files (``*.conf``) to install that contain one boot |
7630 | entry per file. By default, the | 8647 | entry per file. By default, the :ref:`ref-classes-systemd-boot` class |
7631 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8648 | sets the :term:`SYSTEMD_BOOT_ENTRIES` as follows:: |
7632 | ``SYSTEMD_BOOT_ENTRIES`` as follows: | ||
7633 | :: | ||
7634 | 8649 | ||
7635 | SYSTEMD_BOOT_ENTRIES ?= "" | 8650 | SYSTEMD_BOOT_ENTRIES ?= "" |
7636 | 8651 | ||
@@ -7639,58 +8654,75 @@ system and gives an overview of their function and contents. | |||
7639 | 8654 | ||
7640 | :term:`SYSTEMD_BOOT_TIMEOUT` | 8655 | :term:`SYSTEMD_BOOT_TIMEOUT` |
7641 | When :term:`EFI_PROVIDER` is set to | 8656 | When :term:`EFI_PROVIDER` is set to |
7642 | "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the | 8657 | "systemd-boot", the :term:`SYSTEMD_BOOT_TIMEOUT` variable specifies the |
7643 | boot menu timeout in seconds. By default, the | 8658 | boot menu timeout in seconds. By default, the |
7644 | :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the | 8659 | :ref:`ref-classes-systemd-boot` class sets the |
7645 | ``SYSTEMD_BOOT_TIMEOUT`` as follows: | 8660 | :term:`SYSTEMD_BOOT_TIMEOUT` as follows:: |
7646 | :: | ||
7647 | 8661 | ||
7648 | SYSTEMD_BOOT_TIMEOUT ?= "10" | 8662 | SYSTEMD_BOOT_TIMEOUT ?= "10" |
7649 | 8663 | ||
7650 | For information on Systemd-boot, see the `Systemd-boot | 8664 | For information on Systemd-boot, see the `Systemd-boot |
7651 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. | 8665 | documentation <https://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. |
7652 | 8666 | ||
8667 | :term:`SYSTEMD_DEFAULT_TARGET` | ||
8668 | |||
8669 | This variable allows to set the default unit that systemd starts at bootup. | ||
8670 | Usually, this is either ``multi-user.target`` or ``graphical.target``. | ||
8671 | This works by creating a ``default.target`` symbolic link to the chosen systemd | ||
8672 | target file. | ||
8673 | |||
8674 | See `systemd's documentation | ||
8675 | <https://www.freedesktop.org/software/systemd/man/systemd.special.html>`__ | ||
8676 | for details. | ||
8677 | |||
8678 | For example, this variable is used in the :oe_git:`core-image-minimal-xfce.bb | ||
8679 | </meta-openembedded/tree/meta-xfce/recipes-core/images/core-image-minimal-xfce.bb>` | ||
8680 | recipe:: | ||
8681 | |||
8682 | SYSTEMD_DEFAULT_TARGET = "graphical.target" | ||
8683 | |||
7653 | :term:`SYSTEMD_PACKAGES` | 8684 | :term:`SYSTEMD_PACKAGES` |
7654 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8685 | When inheriting the :ref:`ref-classes-systemd` class, |
7655 | this variable locates the systemd unit files when they are not found | 8686 | this variable locates the systemd unit files when they are not found |
7656 | in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` | 8687 | in the main recipe's package. By default, the :term:`SYSTEMD_PACKAGES` |
7657 | variable is set such that the systemd unit files are assumed to | 8688 | variable is set such that the systemd unit files are assumed to |
7658 | reside in the recipes main package: | 8689 | reside in the recipes main package:: |
7659 | :: | ||
7660 | 8690 | ||
7661 | SYSTEMD_PACKAGES ?= "${PN}" | 8691 | SYSTEMD_PACKAGES ?= "${PN}" |
7662 | 8692 | ||
7663 | If these unit files are not in this recipe's main package, you need | 8693 | If these unit files are not in this recipe's main package, you need |
7664 | to use ``SYSTEMD_PACKAGES`` to list the package or packages in which | 8694 | to use :term:`SYSTEMD_PACKAGES` to list the package or packages in which |
7665 | the build system can find the systemd unit files. | 8695 | the build system can find the systemd unit files. |
7666 | 8696 | ||
7667 | :term:`SYSTEMD_SERVICE` | 8697 | :term:`SYSTEMD_SERVICE` |
7668 | When inheriting the :ref:`systemd <ref-classes-systemd>` class, | 8698 | When inheriting the :ref:`ref-classes-systemd` class, |
7669 | this variable specifies the systemd service name for a package. | 8699 | this variable specifies the systemd service name for a package. |
7670 | 8700 | ||
8701 | Multiple services can be specified, each one separated by a space. | ||
8702 | |||
7671 | When you specify this file in your recipe, use a package name | 8703 | When you specify this file in your recipe, use a package name |
7672 | override to indicate the package to which the value applies. Here is | 8704 | override to indicate the package to which the value applies. Here is |
7673 | an example from the connman recipe: | 8705 | an example from the connman recipe:: |
7674 | :: | 8706 | |
8707 | SYSTEMD_SERVICE:${PN} = "connman.service" | ||
7675 | 8708 | ||
7676 | SYSTEMD_SERVICE_${PN} = "connman.service" | 8709 | The package overrides that can be specified are directly related to the value of |
8710 | :term:`SYSTEMD_PACKAGES`. Overrides not included in :term:`SYSTEMD_PACKAGES` | ||
8711 | will be silently ignored. | ||
7677 | 8712 | ||
7678 | :term:`SYSVINIT_ENABLED_GETTYS` | 8713 | :term:`SYSVINIT_ENABLED_GETTYS` |
7679 | When using | 8714 | When using :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, |
7680 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | ||
7681 | specifies a space-separated list of the virtual terminals that should | 8715 | specifies a space-separated list of the virtual terminals that should |
7682 | run a `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ | 8716 | run a :wikipedia:`getty <Getty_(Unix)>` (allowing login), assuming |
7683 | (allowing login), assuming :term:`USE_VT` is not set to | 8717 | :term:`USE_VT` is not set to "0". |
7684 | "0". | ||
7685 | 8718 | ||
7686 | The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only | 8719 | The default value for :term:`SYSVINIT_ENABLED_GETTYS` is "1" (i.e. only |
7687 | run a getty on the first virtual terminal). | 8720 | run a getty on the first virtual terminal). |
7688 | 8721 | ||
7689 | :term:`T` | 8722 | :term:`T` |
7690 | This variable points to a directory were BitBake places temporary | 8723 | This variable points to a directory were BitBake places temporary |
7691 | files, which consist mostly of task logs and scripts, when building a | 8724 | files, which consist mostly of task logs and scripts, when building a |
7692 | particular recipe. The variable is typically set as follows: | 8725 | particular recipe. The variable is typically set as follows:: |
7693 | :: | ||
7694 | 8726 | ||
7695 | T = "${WORKDIR}/temp" | 8727 | T = "${WORKDIR}/temp" |
7696 | 8728 | ||
@@ -7698,7 +8730,7 @@ system and gives an overview of their function and contents. | |||
7698 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` | 8730 | BitBake unpacks and builds the recipe. The default ``bitbake.conf`` |
7699 | file sets this variable. | 8731 | file sets this variable. |
7700 | 8732 | ||
7701 | The ``T`` variable is not to be confused with the | 8733 | The :term:`T` variable is not to be confused with the |
7702 | :term:`TMPDIR` variable, which points to the root of | 8734 | :term:`TMPDIR` variable, which points to the root of |
7703 | the directory tree where BitBake places the output of an entire | 8735 | the directory tree where BitBake places the output of an entire |
7704 | build. | 8736 | build. |
@@ -7722,29 +8754,28 @@ system and gives an overview of their function and contents. | |||
7722 | 8754 | ||
7723 | :term:`TARGET_AS_ARCH` | 8755 | :term:`TARGET_AS_ARCH` |
7724 | Specifies architecture-specific assembler flags for the target | 8756 | Specifies architecture-specific assembler flags for the target |
7725 | system. ``TARGET_AS_ARCH`` is initialized from | 8757 | system. :term:`TARGET_AS_ARCH` is initialized from |
7726 | :term:`TUNE_ASARGS` by default in the BitBake | 8758 | :term:`TUNE_ASARGS` by default in the BitBake |
7727 | configuration file (``meta/conf/bitbake.conf``): | 8759 | configuration file (``meta/conf/bitbake.conf``):: |
7728 | :: | ||
7729 | 8760 | ||
7730 | TARGET_AS_ARCH = "${TUNE_ASARGS}" | 8761 | TARGET_AS_ARCH = "${TUNE_ASARGS}" |
7731 | 8762 | ||
7732 | :term:`TARGET_CC_ARCH` | 8763 | :term:`TARGET_CC_ARCH` |
7733 | Specifies architecture-specific C compiler flags for the target | 8764 | Specifies architecture-specific C compiler flags for the target |
7734 | system. ``TARGET_CC_ARCH`` is initialized from | 8765 | system. :term:`TARGET_CC_ARCH` is initialized from |
7735 | :term:`TUNE_CCARGS` by default. | 8766 | :term:`TUNE_CCARGS` by default. |
7736 | 8767 | ||
7737 | .. note:: | 8768 | .. note:: |
7738 | 8769 | ||
7739 | It is a common workaround to append :term:`LDFLAGS` to | 8770 | It is a common workaround to append :term:`LDFLAGS` to |
7740 | ``TARGET_CC_ARCH`` in recipes that build software for the target that | 8771 | :term:`TARGET_CC_ARCH` in recipes that build software for the target that |
7741 | would not otherwise respect the exported ``LDFLAGS`` variable. | 8772 | would not otherwise respect the exported :term:`LDFLAGS` variable. |
7742 | 8773 | ||
7743 | :term:`TARGET_CC_KERNEL_ARCH` | 8774 | :term:`TARGET_CC_KERNEL_ARCH` |
7744 | This is a specific kernel compiler flag for a CPU or Application | 8775 | This is a specific kernel compiler flag for a CPU or Application |
7745 | Binary Interface (ABI) tune. The flag is used rarely and only for | 8776 | Binary Interface (ABI) tune. The flag is used rarely and only for |
7746 | cases where a userspace :term:`TUNE_CCARGS` is not | 8777 | cases where a userspace :term:`TUNE_CCARGS` is not |
7747 | compatible with the kernel compilation. The ``TARGET_CC_KERNEL_ARCH`` | 8778 | compatible with the kernel compilation. The :term:`TARGET_CC_KERNEL_ARCH` |
7748 | variable allows the kernel (and associated modules) to use a | 8779 | variable allows the kernel (and associated modules) to use a |
7749 | different configuration. See the | 8780 | different configuration. See the |
7750 | ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the | 8781 | ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the |
@@ -7756,8 +8787,8 @@ system and gives an overview of their function and contents. | |||
7756 | :term:`CFLAGS` is set to the value of this variable by | 8787 | :term:`CFLAGS` is set to the value of this variable by |
7757 | default. | 8788 | default. |
7758 | 8789 | ||
7759 | Additionally, the SDK's environment setup script sets the ``CFLAGS`` | 8790 | Additionally, the SDK's environment setup script sets the :term:`CFLAGS` |
7760 | variable in the environment to the ``TARGET_CFLAGS`` value so that | 8791 | variable in the environment to the :term:`TARGET_CFLAGS` value so that |
7761 | executables built using the SDK also have the flags applied. | 8792 | executables built using the SDK also have the flags applied. |
7762 | 8793 | ||
7763 | :term:`TARGET_CPPFLAGS` | 8794 | :term:`TARGET_CPPFLAGS` |
@@ -7767,7 +8798,7 @@ system and gives an overview of their function and contents. | |||
7767 | value of this variable by default. | 8798 | value of this variable by default. |
7768 | 8799 | ||
7769 | Additionally, the SDK's environment setup script sets the | 8800 | Additionally, the SDK's environment setup script sets the |
7770 | ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` | 8801 | :term:`CPPFLAGS` variable in the environment to the :term:`TARGET_CPPFLAGS` |
7771 | value so that executables built using the SDK also have the flags | 8802 | value so that executables built using the SDK also have the flags |
7772 | applied. | 8803 | applied. |
7773 | 8804 | ||
@@ -7778,10 +8809,14 @@ system and gives an overview of their function and contents. | |||
7778 | by default. | 8809 | by default. |
7779 | 8810 | ||
7780 | Additionally, the SDK's environment setup script sets the | 8811 | Additionally, the SDK's environment setup script sets the |
7781 | ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` | 8812 | :term:`CXXFLAGS` variable in the environment to the :term:`TARGET_CXXFLAGS` |
7782 | value so that executables built using the SDK also have the flags | 8813 | value so that executables built using the SDK also have the flags |
7783 | applied. | 8814 | applied. |
7784 | 8815 | ||
8816 | :term:`TARGET_DBGSRC_DIR` | ||
8817 | Specifies the target path to debug source files. The default is | ||
8818 | ``/usr/src/debug/${PN}/${PV}``. | ||
8819 | |||
7785 | :term:`TARGET_FPU` | 8820 | :term:`TARGET_FPU` |
7786 | Specifies the method for handling FPU code. For FPU-less targets, | 8821 | Specifies the method for handling FPU code. For FPU-less targets, |
7787 | which include most ARM CPUs, the variable must be set to "soft". If | 8822 | which include most ARM CPUs, the variable must be set to "soft". If |
@@ -7790,10 +8825,9 @@ system and gives an overview of their function and contents. | |||
7790 | 8825 | ||
7791 | :term:`TARGET_LD_ARCH` | 8826 | :term:`TARGET_LD_ARCH` |
7792 | Specifies architecture-specific linker flags for the target system. | 8827 | Specifies architecture-specific linker flags for the target system. |
7793 | ``TARGET_LD_ARCH`` is initialized from | 8828 | :term:`TARGET_LD_ARCH` is initialized from |
7794 | :term:`TUNE_LDARGS` by default in the BitBake | 8829 | :term:`TUNE_LDARGS` by default in the BitBake |
7795 | configuration file (``meta/conf/bitbake.conf``): | 8830 | configuration file (``meta/conf/bitbake.conf``):: |
7796 | :: | ||
7797 | 8831 | ||
7798 | TARGET_LD_ARCH = "${TUNE_LDARGS}" | 8832 | TARGET_LD_ARCH = "${TUNE_LDARGS}" |
7799 | 8833 | ||
@@ -7805,29 +8839,29 @@ system and gives an overview of their function and contents. | |||
7805 | 8839 | ||
7806 | Additionally, the SDK's environment setup script sets the | 8840 | Additionally, the SDK's environment setup script sets the |
7807 | :term:`LDFLAGS` variable in the environment to the | 8841 | :term:`LDFLAGS` variable in the environment to the |
7808 | ``TARGET_LDFLAGS`` value so that executables built using the SDK also | 8842 | :term:`TARGET_LDFLAGS` value so that executables built using the SDK also |
7809 | have the flags applied. | 8843 | have the flags applied. |
7810 | 8844 | ||
7811 | :term:`TARGET_OS` | 8845 | :term:`TARGET_OS` |
7812 | Specifies the target's operating system. The variable can be set to | 8846 | Specifies the target's operating system. The variable can be set to |
7813 | "linux" for glibc-based systems (GNU C Library) and to "linux-musl" | 8847 | "linux" for glibc-based systems (GNU C Library) and to "linux-musl" |
7814 | for musl libc. For ARM/EABI targets, "linux-gnueabi" and | 8848 | for musl libc. For ARM/EABI targets, the possible values are |
7815 | "linux-musleabi" possible values exist. | 8849 | "linux-gnueabi" and "linux-musleabi". |
7816 | 8850 | ||
7817 | :term:`TARGET_PREFIX` | 8851 | :term:`TARGET_PREFIX` |
7818 | Specifies the prefix used for the toolchain binary target tools. | 8852 | Specifies the prefix used for the toolchain binary target tools. |
7819 | 8853 | ||
7820 | Depending on the type of recipe and the build target, | 8854 | Depending on the type of recipe and the build target, |
7821 | ``TARGET_PREFIX`` is set as follows: | 8855 | :term:`TARGET_PREFIX` is set as follows: |
7822 | 8856 | ||
7823 | - For recipes building for the target machine, the value is | 8857 | - For recipes building for the target machine, the value is |
7824 | "${:term:`TARGET_SYS`}-". | 8858 | "${:term:`TARGET_SYS`}-". |
7825 | 8859 | ||
7826 | - For native recipes, the build system sets the variable to the | 8860 | - For native recipes, the build system sets the variable to the |
7827 | value of ``BUILD_PREFIX``. | 8861 | value of :term:`BUILD_PREFIX`. |
7828 | 8862 | ||
7829 | - For native SDK recipes (``nativesdk``), the build system sets the | 8863 | - For native SDK recipes (:ref:`ref-classes-nativesdk`), |
7830 | variable to the value of ``SDK_PREFIX``. | 8864 | the build system sets the variable to the value of :term:`SDK_PREFIX`. |
7831 | 8865 | ||
7832 | :term:`TARGET_SYS` | 8866 | :term:`TARGET_SYS` |
7833 | Specifies the system, including the architecture and the operating | 8867 | Specifies the system, including the architecture and the operating |
@@ -7841,7 +8875,7 @@ system and gives an overview of their function and contents. | |||
7841 | 8875 | ||
7842 | .. note:: | 8876 | .. note:: |
7843 | 8877 | ||
7844 | You do not need to set the ``TARGET_SYS`` variable yourself. | 8878 | You do not need to set the :term:`TARGET_SYS` variable yourself. |
7845 | 8879 | ||
7846 | Consider these two examples: | 8880 | Consider these two examples: |
7847 | 8881 | ||
@@ -7856,27 +8890,25 @@ system and gives an overview of their function and contents. | |||
7856 | 8890 | ||
7857 | :term:`TCLIBC` | 8891 | :term:`TCLIBC` |
7858 | Specifies the GNU standard C library (``libc``) variant to use during | 8892 | Specifies the GNU standard C library (``libc``) variant to use during |
7859 | the build process. This variable replaces ``POKYLIBC``, which is no | 8893 | the build process. |
7860 | longer supported. | ||
7861 | 8894 | ||
7862 | You can select "glibc", "musl", "newlib", or "baremetal" | 8895 | You can select "glibc", "musl", "newlib", or "baremetal". |
7863 | 8896 | ||
7864 | :term:`TCLIBCAPPEND` | 8897 | :term:`TCLIBCAPPEND` |
7865 | Specifies a suffix to be appended onto the | 8898 | Specifies a suffix to be appended onto the :term:`TMPDIR` value. The |
7866 | :term:`TMPDIR` value. The suffix identifies the | 8899 | suffix identifies the ``libc`` variant for building. When you are |
7867 | ``libc`` variant for building. When you are building for multiple | 8900 | building for multiple variants with the same :term:`Build Directory`, |
7868 | variants with the same :term:`Build Directory`, this | 8901 | this mechanism ensures that output for different ``libc`` variants is |
7869 | mechanism ensures that output for different ``libc`` variants is kept | 8902 | kept separate to avoid potential conflicts. |
7870 | separate to avoid potential conflicts. | ||
7871 | 8903 | ||
7872 | In the ``defaultsetup.conf`` file, the default value of | 8904 | In the ``defaultsetup.conf`` file, the default value of |
7873 | ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, | 8905 | :term:`TCLIBCAPPEND` is "-${TCLIBC}". However, distros such as poky, |
7874 | which normally only support one ``libc`` variant, set | 8906 | which normally only support one ``libc`` variant, set |
7875 | ``TCLIBCAPPEND`` to "" in their distro configuration file resulting | 8907 | :term:`TCLIBCAPPEND` to "" in their distro configuration file resulting |
7876 | in no suffix being applied. | 8908 | in no suffix being applied. |
7877 | 8909 | ||
7878 | :term:`TCMODE` | 8910 | :term:`TCMODE` |
7879 | Specifies the toolchain selector. ``TCMODE`` controls the | 8911 | Specifies the toolchain selector. :term:`TCMODE` controls the |
7880 | characteristics of the generated packages and images by telling the | 8912 | characteristics of the generated packages and images by telling the |
7881 | OpenEmbedded build system which toolchain profile to use. By default, | 8913 | OpenEmbedded build system which toolchain profile to use. By default, |
7882 | the OpenEmbedded build system builds its own internal toolchain. The | 8914 | the OpenEmbedded build system builds its own internal toolchain. The |
@@ -7885,17 +8917,15 @@ system and gives an overview of their function and contents. | |||
7885 | 8917 | ||
7886 | .. note:: | 8918 | .. note:: |
7887 | 8919 | ||
7888 | If ``TCMODE`` is set to a value other than "default", then it is your | 8920 | If :term:`TCMODE` is set to a value other than "default", then it is your |
7889 | responsibility to ensure that the toolchain is compatible with the | 8921 | responsibility to ensure that the toolchain is compatible with the |
7890 | default toolchain. Using older or newer versions of these | 8922 | default toolchain. Using older or newer versions of these |
7891 | components might cause build problems. See the Release Notes for | 8923 | components might cause build problems. See |
7892 | the Yocto Project release for the specific components with which | 8924 | :doc:`Release Information </migration-guides/index>` for your |
7893 | the toolchain must be compatible. To access the Release Notes, go | 8925 | version of the Yocto Project, to find the specific components with |
7894 | to the :yocto_home:`Downloads </software-overview/downloads>` | 8926 | which the toolchain must be compatible. |
7895 | page on the Yocto Project website and click on the "RELEASE | 8927 | |
7896 | INFORMATION" link for the appropriate release. | 8928 | The :term:`TCMODE` variable is similar to :term:`TCLIBC`, |
7897 | |||
7898 | The ``TCMODE`` variable is similar to :term:`TCLIBC`, | ||
7899 | which controls the variant of the GNU standard C library (``libc``) | 8929 | which controls the variant of the GNU standard C library (``libc``) |
7900 | used during the build process: ``glibc`` or ``musl``. | 8930 | used during the build process: ``glibc`` or ``musl``. |
7901 | 8931 | ||
@@ -7906,22 +8936,47 @@ system and gives an overview of their function and contents. | |||
7906 | https://github.com/MentorEmbedded/meta-sourcery/. | 8936 | https://github.com/MentorEmbedded/meta-sourcery/. |
7907 | 8937 | ||
7908 | The layer's ``README`` file contains information on how to use the | 8938 | The layer's ``README`` file contains information on how to use the |
7909 | Sourcery G++ Toolchain as an external toolchain. In summary, you must | 8939 | Sourcery G++ Toolchain as an external toolchain. You will have to |
7910 | be sure to add the layer to your ``bblayers.conf`` file in front of | 8940 | add the layer to your ``bblayers.conf`` file and then set the |
7911 | the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable | 8941 | :term:`EXTERNAL_TOOLCHAIN` variable in your ``local.conf`` file to |
7912 | in your ``local.conf`` file to the location in which you installed | 8942 | the location of the toolchain. |
7913 | the toolchain. | ||
7914 | 8943 | ||
7915 | The fundamentals used for this example apply to any external | 8944 | The fundamentals used for this example apply to any external |
7916 | toolchain. You can use ``meta-sourcery`` as a template for adding | 8945 | toolchain. You can use ``meta-sourcery`` as a template for adding |
7917 | support for other external toolchains. | 8946 | support for other external toolchains. |
7918 | 8947 | ||
8948 | In addition to toolchain configuration, you will also need a | ||
8949 | corresponding toolchain recipe file. This recipe file needs to package | ||
8950 | up any pre-built objects in the toolchain such as ``libgcc``, | ||
8951 | ``libstdcc++``, any locales, and ``libc``. | ||
8952 | |||
8953 | :term:`TC_CXX_RUNTIME` | ||
8954 | Specifies the C/C++ STL and runtime variant to use during | ||
8955 | the build process. Default value is 'gnu' | ||
8956 | |||
8957 | You can select "gnu", "llvm", or "android". | ||
8958 | |||
8959 | :term:`TEMPLATECONF` | ||
8960 | Specifies the directory used by the build system to find templates | ||
8961 | from which to build the ``bblayers.conf`` and ``local.conf`` files. | ||
8962 | Use this variable if you wish to customize such files, and the default | ||
8963 | BitBake targets shown when sourcing the ``oe-init-build-env`` script. | ||
8964 | |||
8965 | For details, see the | ||
8966 | :ref:`dev-manual/custom-template-configuration-directory:creating a custom template configuration directory` | ||
8967 | section in the Yocto Project Development Tasks manual. | ||
8968 | |||
8969 | .. note:: | ||
8970 | |||
8971 | You must set this variable in the external environment in order | ||
8972 | for it to work. | ||
8973 | |||
7919 | :term:`TEST_EXPORT_DIR` | 8974 | :term:`TEST_EXPORT_DIR` |
7920 | The location the OpenEmbedded build system uses to export tests when | 8975 | The location the OpenEmbedded build system uses to export tests when |
7921 | the :term:`TEST_EXPORT_ONLY` variable is set | 8976 | the :term:`TEST_EXPORT_ONLY` variable is set |
7922 | to "1". | 8977 | to "1". |
7923 | 8978 | ||
7924 | The ``TEST_EXPORT_DIR`` variable defaults to | 8979 | The :term:`TEST_EXPORT_DIR` variable defaults to |
7925 | ``"${TMPDIR}/testimage/${PN}"``. | 8980 | ``"${TMPDIR}/testimage/${PN}"``. |
7926 | 8981 | ||
7927 | :term:`TEST_EXPORT_ONLY` | 8982 | :term:`TEST_EXPORT_ONLY` |
@@ -7931,7 +8986,7 @@ system and gives an overview of their function and contents. | |||
7931 | 8986 | ||
7932 | :term:`TEST_LOG_DIR` | 8987 | :term:`TEST_LOG_DIR` |
7933 | Holds the SSH log and the boot log for QEMU machines. The | 8988 | Holds the SSH log and the boot log for QEMU machines. The |
7934 | ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. | 8989 | :term:`TEST_LOG_DIR` variable defaults to ``"${WORKDIR}/testimage"``. |
7935 | 8990 | ||
7936 | .. note:: | 8991 | .. note:: |
7937 | 8992 | ||
@@ -7951,7 +9006,7 @@ system and gives an overview of their function and contents. | |||
7951 | For automated hardware testing, specifies additional arguments to | 9006 | For automated hardware testing, specifies additional arguments to |
7952 | pass through to the command specified in | 9007 | pass through to the command specified in |
7953 | :term:`TEST_POWERCONTROL_CMD`. Setting | 9008 | :term:`TEST_POWERCONTROL_CMD`. Setting |
7954 | ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you | 9009 | :term:`TEST_POWERCONTROL_EXTRA_ARGS` is optional. You can use it if you |
7955 | wish, for example, to separate the machine-specific and | 9010 | wish, for example, to separate the machine-specific and |
7956 | non-machine-specific parts of the arguments. | 9011 | non-machine-specific parts of the arguments. |
7957 | 9012 | ||
@@ -7963,7 +9018,7 @@ system and gives an overview of their function and contents. | |||
7963 | file. | 9018 | file. |
7964 | 9019 | ||
7965 | For more information on testing images, see the | 9020 | For more information on testing images, see the |
7966 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 9021 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
7967 | section in the Yocto Project Development Tasks Manual. | 9022 | section in the Yocto Project Development Tasks Manual. |
7968 | 9023 | ||
7969 | :term:`TEST_SERIALCONTROL_CMD` | 9024 | :term:`TEST_SERIALCONTROL_CMD` |
@@ -7974,8 +9029,7 @@ system and gives an overview of their function and contents. | |||
7974 | program does. | 9029 | program does. |
7975 | 9030 | ||
7976 | For example, to use the Picocom terminal program on serial device | 9031 | For example, to use the Picocom terminal program on serial device |
7977 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: | 9032 | ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:: |
7978 | :: | ||
7979 | 9033 | ||
7980 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" | 9034 | TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" |
7981 | 9035 | ||
@@ -7983,7 +9037,7 @@ system and gives an overview of their function and contents. | |||
7983 | For automated hardware testing, specifies additional arguments to | 9037 | For automated hardware testing, specifies additional arguments to |
7984 | pass through to the command specified in | 9038 | pass through to the command specified in |
7985 | :term:`TEST_SERIALCONTROL_CMD`. Setting | 9039 | :term:`TEST_SERIALCONTROL_CMD`. Setting |
7986 | ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you | 9040 | :term:`TEST_SERIALCONTROL_EXTRA_ARGS` is optional. You can use it if you |
7987 | wish, for example, to separate the machine-specific and | 9041 | wish, for example, to separate the machine-specific and |
7988 | non-machine-specific parts of the command. | 9042 | non-machine-specific parts of the command. |
7989 | 9043 | ||
@@ -7995,7 +9049,7 @@ system and gives an overview of their function and contents. | |||
7995 | 9049 | ||
7996 | .. note:: | 9050 | .. note:: |
7997 | 9051 | ||
7998 | The ``TEST_SERVER_IP`` variable is only used for a small number of | 9052 | The :term:`TEST_SERVER_IP` variable is only used for a small number of |
7999 | tests such as the "dnf" test suite, which needs to download packages | 9053 | tests such as the "dnf" test suite, which needs to download packages |
8000 | from ``WORKDIR/oe-rootfs-repo``. | 9054 | from ``WORKDIR/oe-rootfs-repo``. |
8001 | 9055 | ||
@@ -8012,18 +9066,16 @@ system and gives an overview of their function and contents. | |||
8012 | QEMU. | 9066 | QEMU. |
8013 | 9067 | ||
8014 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add | 9068 | Tests include ``ping``, ``ssh``, ``df`` among others. You can add |
8015 | your own tests to the list of tests by appending ``TEST_SUITES`` as | 9069 | your own tests to the list of tests by appending :term:`TEST_SUITES` as |
8016 | follows: | 9070 | follows:: |
8017 | :: | ||
8018 | 9071 | ||
8019 | TEST_SUITES_append = " mytest" | 9072 | TEST_SUITES:append = " mytest" |
8020 | 9073 | ||
8021 | Alternatively, you can | 9074 | Alternatively, you can |
8022 | provide the "auto" option to have all applicable tests run against | 9075 | provide the "auto" option to have all applicable tests run against |
8023 | the image. | 9076 | the image:: |
8024 | :: | ||
8025 | 9077 | ||
8026 | TEST_SUITES_append = " auto" | 9078 | TEST_SUITES:append = " auto" |
8027 | 9079 | ||
8028 | Using this option causes the | 9080 | Using this option causes the |
8029 | build system to automatically run tests that are applicable to the | 9081 | build system to automatically run tests that are applicable to the |
@@ -8033,19 +9085,17 @@ system and gives an overview of their function and contents. | |||
8033 | another test must appear later in the list than the test on which | 9085 | another test must appear later in the list than the test on which |
8034 | they depend. For example, if you append the list of tests with two | 9086 | they depend. For example, if you append the list of tests with two |
8035 | tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on | 9087 | tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on |
8036 | ``test_A``, then you must order the tests as follows: | 9088 | ``test_A``, then you must order the tests as follows:: |
8037 | :: | ||
8038 | 9089 | ||
8039 | TEST_SUITES = "test_A test_B" | 9090 | TEST_SUITES = "test_A test_B" |
8040 | 9091 | ||
8041 | For more information on testing images, see the | 9092 | For more information on testing images, see the |
8042 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 9093 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
8043 | section in the Yocto Project Development Tasks Manual. | 9094 | section in the Yocto Project Development Tasks Manual. |
8044 | 9095 | ||
8045 | :term:`TEST_TARGET` | 9096 | :term:`TEST_TARGET` |
8046 | Specifies the target controller to use when running tests against a | 9097 | Specifies the target controller to use when running tests against a |
8047 | test image. The default controller to use is "qemu": | 9098 | test image. The default controller to use is "qemu":: |
8048 | :: | ||
8049 | 9099 | ||
8050 | TEST_TARGET = "qemu" | 9100 | TEST_TARGET = "qemu" |
8051 | 9101 | ||
@@ -8054,12 +9104,12 @@ system and gives an overview of their function and contents. | |||
8054 | the controllers by adding a module in the layer's | 9104 | the controllers by adding a module in the layer's |
8055 | ``/lib/oeqa/controllers`` directory and by inheriting the | 9105 | ``/lib/oeqa/controllers`` directory and by inheriting the |
8056 | ``BaseTarget`` class, which is an abstract class that cannot be used | 9106 | ``BaseTarget`` class, which is an abstract class that cannot be used |
8057 | as a value of ``TEST_TARGET``. | 9107 | as a value of :term:`TEST_TARGET`. |
8058 | 9108 | ||
8059 | You can provide the following arguments with ``TEST_TARGET``: | 9109 | You can provide the following arguments with :term:`TEST_TARGET`: |
8060 | 9110 | ||
8061 | - *"qemu":* Boots a QEMU image and runs the tests. See the | 9111 | - *"qemu":* Boots a QEMU image and runs the tests. See the |
8062 | ":ref:`dev-manual/common-tasks:enabling runtime tests on qemu`" section | 9112 | ":ref:`dev-manual/runtime-testing:enabling runtime tests on qemu`" section |
8063 | in the Yocto Project Development Tasks Manual for more | 9113 | in the Yocto Project Development Tasks Manual for more |
8064 | information. | 9114 | information. |
8065 | 9115 | ||
@@ -8075,17 +9125,16 @@ system and gives an overview of their function and contents. | |||
8075 | ``meta/lib/oeqa/controllers/simpleremote.py``. | 9125 | ``meta/lib/oeqa/controllers/simpleremote.py``. |
8076 | 9126 | ||
8077 | For information on running tests on hardware, see the | 9127 | For information on running tests on hardware, see the |
8078 | ":ref:`dev-manual/common-tasks:enabling runtime tests on hardware`" | 9128 | ":ref:`dev-manual/runtime-testing:enabling runtime tests on hardware`" |
8079 | section in the Yocto Project Development Tasks Manual. | 9129 | section in the Yocto Project Development Tasks Manual. |
8080 | 9130 | ||
8081 | :term:`TEST_TARGET_IP` | 9131 | :term:`TEST_TARGET_IP` |
8082 | The IP address of your hardware under test. The ``TEST_TARGET_IP`` | 9132 | The IP address of your hardware under test. The :term:`TEST_TARGET_IP` |
8083 | variable has no effect when :term:`TEST_TARGET` is | 9133 | variable has no effect when :term:`TEST_TARGET` is |
8084 | set to "qemu". | 9134 | set to "qemu". |
8085 | 9135 | ||
8086 | When you specify the IP address, you can also include a port. Here is | 9136 | When you specify the IP address, you can also include a port. Here is |
8087 | an example: | 9137 | an example:: |
8088 | :: | ||
8089 | 9138 | ||
8090 | TEST_TARGET_IP = "192.168.1.4:2201" | 9139 | TEST_TARGET_IP = "192.168.1.4:2201" |
8091 | 9140 | ||
@@ -8097,7 +9146,7 @@ system and gives an overview of their function and contents. | |||
8097 | 9146 | ||
8098 | :term:`TESTIMAGE_AUTO` | 9147 | :term:`TESTIMAGE_AUTO` |
8099 | Automatically runs the series of automated tests for images when an | 9148 | Automatically runs the series of automated tests for images when an |
8100 | image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes | 9149 | image is successfully built. Setting :term:`TESTIMAGE_AUTO` to "1" causes |
8101 | any image that successfully builds to automatically boot under QEMU. | 9150 | any image that successfully builds to automatically boot under QEMU. |
8102 | Using the variable also adds in dependencies so that any SDK for | 9151 | Using the variable also adds in dependencies so that any SDK for |
8103 | which testing is requested is automatically built first. | 9152 | which testing is requested is automatically built first. |
@@ -8113,9 +9162,9 @@ system and gives an overview of their function and contents. | |||
8113 | 9162 | ||
8114 | For more information | 9163 | For more information |
8115 | on enabling, running, and writing these tests, see the | 9164 | on enabling, running, and writing these tests, see the |
8116 | ":ref:`dev-manual/common-tasks:performing automated runtime testing`" | 9165 | ":ref:`dev-manual/runtime-testing:performing automated runtime testing`" |
8117 | section in the Yocto Project Development Tasks Manual and the | 9166 | section in the Yocto Project Development Tasks Manual and the |
8118 | ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. | 9167 | ":ref:`ref-classes-testimage`" section. |
8119 | 9168 | ||
8120 | :term:`THISDIR` | 9169 | :term:`THISDIR` |
8121 | The directory in which the file BitBake is currently parsing is | 9170 | The directory in which the file BitBake is currently parsing is |
@@ -8129,24 +9178,23 @@ system and gives an overview of their function and contents. | |||
8129 | :term:`TMPDIR` | 9178 | :term:`TMPDIR` |
8130 | This variable is the base directory the OpenEmbedded build system | 9179 | This variable is the base directory the OpenEmbedded build system |
8131 | uses for all build output and intermediate files (other than the | 9180 | uses for all build output and intermediate files (other than the |
8132 | shared state cache). By default, the ``TMPDIR`` variable points to | 9181 | shared state cache). By default, the :term:`TMPDIR` variable points to |
8133 | ``tmp`` within the :term:`Build Directory`. | 9182 | ``tmp`` within the :term:`Build Directory`. |
8134 | 9183 | ||
8135 | If you want to establish this directory in a location other than the | 9184 | If you want to establish this directory in a location other than the |
8136 | default, you can uncomment and edit the following statement in the | 9185 | default, you can uncomment and edit the following statement in the |
8137 | ``conf/local.conf`` file in the :term:`Source Directory`: | 9186 | ``conf/local.conf`` file in the :term:`Source Directory`:: |
8138 | :: | ||
8139 | 9187 | ||
8140 | #TMPDIR = "${TOPDIR}/tmp" | 9188 | #TMPDIR = "${TOPDIR}/tmp" |
8141 | 9189 | ||
8142 | An example use for this scenario is to set ``TMPDIR`` to a local disk, | 9190 | An example use for this scenario is to set :term:`TMPDIR` to a local disk, |
8143 | which does not use NFS, while having the Build Directory use NFS. | 9191 | which does not use NFS, while having the :term:`Build Directory` use NFS. |
8144 | 9192 | ||
8145 | The filesystem used by ``TMPDIR`` must have standard filesystem | 9193 | The filesystem used by :term:`TMPDIR` must have standard filesystem |
8146 | semantics (i.e. mixed-case files are unique, POSIX file locking, and | 9194 | semantics (i.e. mixed-case files are unique, POSIX file locking, and |
8147 | persistent inodes). Due to various issues with NFS and bugs in some | 9195 | persistent inodes). Due to various issues with NFS and bugs in some |
8148 | implementations, NFS does not meet this minimum requirement. | 9196 | implementations, NFS does not meet this minimum requirement. |
8149 | Consequently, ``TMPDIR`` cannot be on NFS. | 9197 | Consequently, :term:`TMPDIR` cannot be on NFS. |
8150 | 9198 | ||
8151 | :term:`TOOLCHAIN_HOST_TASK` | 9199 | :term:`TOOLCHAIN_HOST_TASK` |
8152 | This variable lists packages the OpenEmbedded build system uses when | 9200 | This variable lists packages the OpenEmbedded build system uses when |
@@ -8154,8 +9202,7 @@ system and gives an overview of their function and contents. | |||
8154 | packages specified by this variable are part of the toolchain set | 9202 | packages specified by this variable are part of the toolchain set |
8155 | that runs on the :term:`SDKMACHINE`, and each | 9203 | that runs on the :term:`SDKMACHINE`, and each |
8156 | package should usually have the prefix ``nativesdk-``. For example, | 9204 | package should usually have the prefix ``nativesdk-``. For example, |
8157 | consider the following command when building an SDK: | 9205 | consider the following command when building an SDK:: |
8158 | :: | ||
8159 | 9206 | ||
8160 | $ bitbake -c populate_sdk imagename | 9207 | $ bitbake -c populate_sdk imagename |
8161 | 9208 | ||
@@ -8173,11 +9220,29 @@ system and gives an overview of their function and contents. | |||
8173 | information on setting up a cross-development environment, see the | 9220 | information on setting up a cross-development environment, see the |
8174 | :doc:`/sdk-manual/index` manual. | 9221 | :doc:`/sdk-manual/index` manual. |
8175 | 9222 | ||
9223 | Note that this variable applies to building an SDK, not an eSDK, | ||
9224 | in which case the :term:`TOOLCHAIN_HOST_TASK_ESDK` setting should be | ||
9225 | used instead. | ||
9226 | |||
9227 | :term:`TOOLCHAIN_HOST_TASK_ESDK` | ||
9228 | This variable allows to extend what is installed in the host | ||
9229 | portion of an eSDK. This is similar to :term:`TOOLCHAIN_HOST_TASK` | ||
9230 | applying to SDKs. | ||
9231 | |||
9232 | :term:`TOOLCHAIN_OPTIONS` | ||
9233 | This variable holds extra options passed to the compiler and the linker | ||
9234 | for non ``-native`` recipes as they have to point to their custom | ||
9235 | ``sysroot`` folder pointed to by :term:`RECIPE_SYSROOT`:: | ||
9236 | |||
9237 | TOOLCHAIN_OPTIONS = " --sysroot=${RECIPE_SYSROOT}" | ||
9238 | |||
9239 | Native recipes don't need this variable to be set, as they are | ||
9240 | built for the host machine with the native compiler. | ||
9241 | |||
8176 | :term:`TOOLCHAIN_OUTPUTNAME` | 9242 | :term:`TOOLCHAIN_OUTPUTNAME` |
8177 | This variable defines the name used for the toolchain output. The | 9243 | This variable defines the name used for the toolchain output. The |
8178 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets | 9244 | :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets |
8179 | the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: | 9245 | the :term:`TOOLCHAIN_OUTPUTNAME` variable as follows:: |
8180 | :: | ||
8181 | 9246 | ||
8182 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" | 9247 | TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" |
8183 | 9248 | ||
@@ -8204,16 +9269,14 @@ system and gives an overview of their function and contents. | |||
8204 | :doc:`/sdk-manual/index` manual. | 9269 | :doc:`/sdk-manual/index` manual. |
8205 | 9270 | ||
8206 | :term:`TOPDIR` | 9271 | :term:`TOPDIR` |
8207 | The top-level :term:`Build Directory`. BitBake | 9272 | See :term:`bitbake:TOPDIR` in the BitBake manual. |
8208 | automatically sets this variable when you initialize your build | ||
8209 | environment using :ref:`structure-core-script`. | ||
8210 | 9273 | ||
8211 | :term:`TRANSLATED_TARGET_ARCH` | 9274 | :term:`TRANSLATED_TARGET_ARCH` |
8212 | A sanitized version of :term:`TARGET_ARCH`. This | 9275 | A sanitized version of :term:`TARGET_ARCH`. This |
8213 | variable is used where the architecture is needed in a value where | 9276 | variable is used where the architecture is needed in a value where |
8214 | underscores are not allowed, for example within package filenames. In | 9277 | underscores are not allowed, for example within package filenames. In |
8215 | this case, dash characters replace any underscore characters used in | 9278 | this case, dash characters replace any underscore characters used in |
8216 | ``TARGET_ARCH``. | 9279 | :term:`TARGET_ARCH`. |
8217 | 9280 | ||
8218 | Do not edit this variable. | 9281 | Do not edit this variable. |
8219 | 9282 | ||
@@ -8222,19 +9285,18 @@ system and gives an overview of their function and contents. | |||
8222 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses | 9285 | ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses |
8223 | this value to setup configuration. | 9286 | this value to setup configuration. |
8224 | 9287 | ||
8225 | ``TUNE_ARCH`` definitions are specific to a given architecture. The | 9288 | :term:`TUNE_ARCH` definitions are specific to a given architecture. The |
8226 | definitions can be a single static definition, or can be dynamically | 9289 | definitions can be a single static definition, or can be dynamically |
8227 | adjusted. You can see details for a given CPU family by looking at | 9290 | adjusted. You can see details for a given CPU family by looking at |
8228 | the architecture's ``README`` file. For example, the | 9291 | the architecture's ``README`` file. For example, the |
8229 | ``meta/conf/machine/include/mips/README`` file in the | 9292 | ``meta/conf/machine/include/mips/README`` file in the |
8230 | :term:`Source Directory` provides information for | 9293 | :term:`Source Directory` provides information for |
8231 | ``TUNE_ARCH`` specific to the ``mips`` architecture. | 9294 | :term:`TUNE_ARCH` specific to the ``mips`` architecture. |
8232 | 9295 | ||
8233 | ``TUNE_ARCH`` is tied closely to | 9296 | :term:`TUNE_ARCH` is tied closely to |
8234 | :term:`TARGET_ARCH`, which defines the target | 9297 | :term:`TARGET_ARCH`, which defines the target |
8235 | machine's architecture. The BitBake configuration file | 9298 | machine's architecture. The BitBake configuration file |
8236 | (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: | 9299 | (``meta/conf/bitbake.conf``) sets :term:`TARGET_ARCH` as follows:: |
8237 | :: | ||
8238 | 9300 | ||
8239 | TARGET_ARCH = "${TUNE_ARCH}" | 9301 | TARGET_ARCH = "${TUNE_ARCH}" |
8240 | 9302 | ||
@@ -8252,12 +9314,11 @@ system and gives an overview of their function and contents. | |||
8252 | :term:`TUNE_ASARGS` | 9314 | :term:`TUNE_ASARGS` |
8253 | Specifies architecture-specific assembler flags for the target | 9315 | Specifies architecture-specific assembler flags for the target |
8254 | system. The set of flags is based on the selected tune features. | 9316 | system. The set of flags is based on the selected tune features. |
8255 | ``TUNE_ASARGS`` is set using the tune include files, which are | 9317 | :term:`TUNE_ASARGS` is set using the tune include files, which are |
8256 | typically under ``meta/conf/machine/include/`` and are influenced | 9318 | typically under ``meta/conf/machine/include/`` and are influenced |
8257 | through :term:`TUNE_FEATURES`. For example, the | 9319 | through :term:`TUNE_FEATURES`. For example, the |
8258 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | 9320 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags |
8259 | for the x86 architecture as follows: | 9321 | for the x86 architecture as follows:: |
8260 | :: | ||
8261 | 9322 | ||
8262 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" | 9323 | TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" |
8263 | 9324 | ||
@@ -8270,7 +9331,7 @@ system and gives an overview of their function and contents. | |||
8270 | :term:`TUNE_CCARGS` | 9331 | :term:`TUNE_CCARGS` |
8271 | Specifies architecture-specific C compiler flags for the target | 9332 | Specifies architecture-specific C compiler flags for the target |
8272 | system. The set of flags is based on the selected tune features. | 9333 | system. The set of flags is based on the selected tune features. |
8273 | ``TUNE_CCARGS`` is set using the tune include files, which are | 9334 | :term:`TUNE_CCARGS` is set using the tune include files, which are |
8274 | typically under ``meta/conf/machine/include/`` and are influenced | 9335 | typically under ``meta/conf/machine/include/`` and are influenced |
8275 | through :term:`TUNE_FEATURES`. | 9336 | through :term:`TUNE_FEATURES`. |
8276 | 9337 | ||
@@ -8290,22 +9351,20 @@ system and gives an overview of their function and contents. | |||
8290 | are not conflicting and that they are supported. | 9351 | are not conflicting and that they are supported. |
8291 | 9352 | ||
8292 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines | 9353 | The BitBake configuration file (``meta/conf/bitbake.conf``) defines |
8293 | ``TUNE_FEATURES`` as follows: | 9354 | :term:`TUNE_FEATURES` as follows:: |
8294 | :: | ||
8295 | 9355 | ||
8296 | TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" | 9356 | TUNE_FEATURES ??= "${TUNE_FEATURES:tune-${DEFAULTTUNE}}" |
8297 | 9357 | ||
8298 | See the :term:`DEFAULTTUNE` variable for more information. | 9358 | See the :term:`DEFAULTTUNE` variable for more information. |
8299 | 9359 | ||
8300 | :term:`TUNE_LDARGS` | 9360 | :term:`TUNE_LDARGS` |
8301 | Specifies architecture-specific linker flags for the target system. | 9361 | Specifies architecture-specific linker flags for the target system. |
8302 | The set of flags is based on the selected tune features. | 9362 | The set of flags is based on the selected tune features. |
8303 | ``TUNE_LDARGS`` is set using the tune include files, which are | 9363 | :term:`TUNE_LDARGS` is set using the tune include files, which are |
8304 | typically under ``meta/conf/machine/include/`` and are influenced | 9364 | typically under ``meta/conf/machine/include/`` and are influenced |
8305 | through :term:`TUNE_FEATURES`. For example, the | 9365 | through :term:`TUNE_FEATURES`. For example, the |
8306 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags | 9366 | ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags |
8307 | for the x86 architecture as follows: | 9367 | for the x86 architecture as follows:: |
8308 | :: | ||
8309 | 9368 | ||
8310 | TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" | 9369 | TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}" |
8311 | 9370 | ||
@@ -8318,51 +9377,15 @@ system and gives an overview of their function and contents. | |||
8318 | :term:`TUNE_PKGARCH` | 9377 | :term:`TUNE_PKGARCH` |
8319 | The package architecture understood by the packaging system to define | 9378 | The package architecture understood by the packaging system to define |
8320 | the architecture, ABI, and tuning of output packages. The specific | 9379 | the architecture, ABI, and tuning of output packages. The specific |
8321 | tune is defined using the "_tune" override as follows: | 9380 | tune is defined using the "_tune" override as follows:: |
8322 | :: | ||
8323 | 9381 | ||
8324 | TUNE_PKGARCH_tune-tune = "tune" | 9382 | TUNE_PKGARCH:tune-tune = "tune" |
8325 | 9383 | ||
8326 | These tune-specific package architectures are defined in the machine | 9384 | These tune-specific package architectures are defined in the machine |
8327 | include files. Here is an example of the "core2-32" tuning as used in | 9385 | include files. Here is an example of the "core2-32" tuning as used in |
8328 | the ``meta/conf/machine/include/tune-core2.inc`` file: | 9386 | the ``meta/conf/machine/include/x86/tune-core2.inc`` file:: |
8329 | :: | 9387 | |
8330 | 9388 | TUNE_PKGARCH:tune-core2-32 = "core2-32" | |
8331 | TUNE_PKGARCH_tune-core2-32 = "core2-32" | ||
8332 | |||
8333 | :term:`TUNEABI` | ||
8334 | An underlying Application Binary Interface (ABI) used by a particular | ||
8335 | tuning in a given toolchain layer. Providers that use prebuilt | ||
8336 | libraries can use the ``TUNEABI``, | ||
8337 | :term:`TUNEABI_OVERRIDE`, and | ||
8338 | :term:`TUNEABI_WHITELIST` variables to check | ||
8339 | compatibility of tunings against their selection of libraries. | ||
8340 | |||
8341 | If ``TUNEABI`` is undefined, then every tuning is allowed. See the | ||
8342 | :ref:`sanity <ref-classes-sanity>` class to see how the variable is | ||
8343 | used. | ||
8344 | |||
8345 | :term:`TUNEABI_OVERRIDE` | ||
8346 | If set, the OpenEmbedded system ignores the | ||
8347 | :term:`TUNEABI_WHITELIST` variable. | ||
8348 | Providers that use prebuilt libraries can use the | ||
8349 | ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and | ||
8350 | :term:`TUNEABI` variables to check compatibility of a | ||
8351 | tuning against their selection of libraries. | ||
8352 | |||
8353 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8354 | variable is used. | ||
8355 | |||
8356 | :term:`TUNEABI_WHITELIST` | ||
8357 | A whitelist of permissible :term:`TUNEABI` values. If | ||
8358 | ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers | ||
8359 | that use prebuilt libraries can use the ``TUNEABI_WHITELIST``, | ||
8360 | :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` | ||
8361 | variables to check compatibility of a tuning against their selection | ||
8362 | of libraries. | ||
8363 | |||
8364 | See the :ref:`sanity <ref-classes-sanity>` class to see how the | ||
8365 | variable is used. | ||
8366 | 9389 | ||
8367 | :term:`TUNECONFLICTS[feature]` | 9390 | :term:`TUNECONFLICTS[feature]` |
8368 | Specifies CPU or Application Binary Interface (ABI) tuning features | 9391 | Specifies CPU or Application Binary Interface (ABI) tuning features |
@@ -8372,8 +9395,7 @@ system and gives an overview of their function and contents. | |||
8372 | the :term:`Source Directory`. Here is an example from | 9395 | the :term:`Source Directory`. Here is an example from |
8373 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file | 9396 | the ``meta/conf/machine/include/mips/arch-mips.inc`` include file |
8374 | that lists the "o32" and "n64" features as conflicting with the "n32" | 9397 | that lists the "o32" and "n64" features as conflicting with the "n32" |
8375 | feature: | 9398 | feature:: |
8376 | :: | ||
8377 | 9399 | ||
8378 | TUNECONFLICTS[n32] = "o32 n64" | 9400 | TUNECONFLICTS[n32] = "o32 n64" |
8379 | 9401 | ||
@@ -8382,65 +9404,164 @@ system and gives an overview of their function and contents. | |||
8382 | feature. The specified feature is stored as a flag. Valid features | 9404 | feature. The specified feature is stored as a flag. Valid features |
8383 | are specified in the machine include files (e.g. | 9405 | are specified in the machine include files (e.g. |
8384 | ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example | 9406 | ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example |
8385 | from that file: | 9407 | from that file:: |
8386 | :: | ||
8387 | 9408 | ||
8388 | TUNEVALID[bigendian] = "Enable big-endian mode." | 9409 | TUNEVALID[bigendian] = "Enable big-endian mode." |
8389 | 9410 | ||
8390 | See the machine include files in the :term:`Source Directory` | 9411 | See the machine include files in the :term:`Source Directory` |
8391 | for these features. | 9412 | for these features. |
8392 | 9413 | ||
8393 | :term:`UBOOT_CONFIG` | 9414 | :term:`UBOOT_BINARY` |
8394 | Configures the :term:`UBOOT_MACHINE` and can | 9415 | Specifies the name of the binary build by U-Boot. |
8395 | also define :term:`IMAGE_FSTYPES` for individual | ||
8396 | cases. | ||
8397 | |||
8398 | Following is an example from the ``meta-fsl-arm`` layer. :: | ||
8399 | |||
8400 | UBOOT_CONFIG ??= "sd" | ||
8401 | UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" | ||
8402 | UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" | ||
8403 | UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" | ||
8404 | UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" | ||
8405 | |||
8406 | In this example, "sd" is selected as the configuration of the possible four for the | ||
8407 | ``UBOOT_MACHINE``. The "sd" configuration defines | ||
8408 | "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the | ||
8409 | "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-Boot image. | ||
8410 | 9416 | ||
8411 | For more information on how the ``UBOOT_CONFIG`` is handled, see the | 9417 | :term:`UBOOT_CONFIG` |
8412 | :ref:`uboot-config <ref-classes-uboot-config>` | 9418 | Configures one or more U-Boot configurations to build. Each |
8413 | class. | 9419 | configuration can define the :term:`UBOOT_MACHINE` and optionally the |
9420 | :term:`IMAGE_FSTYPES` and the :term:`UBOOT_BINARY`. | ||
9421 | |||
9422 | Here is an example from the ``meta-freescale`` layer. :: | ||
9423 | |||
9424 | UBOOT_CONFIG ??= "sdcard-ifc-secure-boot sdcard-ifc sdcard-qspi lpuart qspi secure-boot nor" | ||
9425 | UBOOT_CONFIG[nor] = "ls1021atwr_nor_defconfig" | ||
9426 | UBOOT_CONFIG[sdcard-ifc] = "ls1021atwr_sdcard_ifc_defconfig,,u-boot-with-spl-pbl.bin" | ||
9427 | UBOOT_CONFIG[sdcard-qspi] = "ls1021atwr_sdcard_qspi_defconfig,,u-boot-with-spl-pbl.bin" | ||
9428 | UBOOT_CONFIG[lpuart] = "ls1021atwr_nor_lpuart_defconfig" | ||
9429 | UBOOT_CONFIG[qspi] = "ls1021atwr_qspi_defconfig" | ||
9430 | UBOOT_CONFIG[secure-boot] = "ls1021atwr_nor_SECURE_BOOT_defconfig" | ||
9431 | UBOOT_CONFIG[sdcard-ifc-secure-boot] = "ls1021atwr_sdcard_ifc_SECURE_BOOT_defconfig,,u-boot-with-spl-pbl.bin" | ||
9432 | |||
9433 | In this example, all possible seven configurations are selected. Each | ||
9434 | configuration specifies "..._defconfig" as :term:`UBOOT_MACHINE`, and | ||
9435 | the "sd..." configurations define an individual name for | ||
9436 | :term:`UBOOT_BINARY`. No configuration defines a second parameter for | ||
9437 | :term:`IMAGE_FSTYPES` to use for the U-Boot image. | ||
9438 | |||
9439 | For more information on how the :term:`UBOOT_CONFIG` is handled, see the | ||
9440 | :ref:`ref-classes-uboot-config` class. | ||
8414 | 9441 | ||
8415 | :term:`UBOOT_DTB_LOADADDRESS` | 9442 | :term:`UBOOT_DTB_LOADADDRESS` |
8416 | Specifies the load address for the dtb image used by U-Boot. During FIT | 9443 | Specifies the load address for the dtb image used by U-Boot. During FIT |
8417 | image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in | 9444 | image creation, the :term:`UBOOT_DTB_LOADADDRESS` variable is used in |
8418 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify | 9445 | :ref:`ref-classes-kernel-fitimage` class to specify the load address to be |
8419 | the load address to be used in | 9446 | used in creating the dtb sections of Image Tree Source for the FIT image. |
8420 | creating the dtb sections of Image Tree Source for the FIT image. | ||
8421 | 9447 | ||
8422 | :term:`UBOOT_DTBO_LOADADDRESS` | 9448 | :term:`UBOOT_DTBO_LOADADDRESS` |
8423 | Specifies the load address for the dtbo image used by U-Boot. During FIT | 9449 | Specifies the load address for the dtbo image used by U-Boot. During FIT |
8424 | image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in | 9450 | image creation, the :term:`UBOOT_DTBO_LOADADDRESS` variable is used in |
8425 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in | 9451 | :ref:`ref-classes-kernel-fitimage` class to specify the load address to be |
8426 | creating the dtbo sections of Image Tree Source for the FIT image. | 9452 | used in creating the dtbo sections of Image Tree Source for the FIT image. |
8427 | 9453 | ||
8428 | :term:`UBOOT_ENTRYPOINT` | 9454 | :term:`UBOOT_ENTRYPOINT` |
8429 | Specifies the entry point for the U-Boot image. During U-Boot image | 9455 | Specifies the entry point for the U-Boot image. During U-Boot image |
8430 | creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a | 9456 | creation, the :term:`UBOOT_ENTRYPOINT` variable is passed as a |
8431 | command-line parameter to the ``uboot-mkimage`` utility. | 9457 | command-line parameter to the ``uboot-mkimage`` utility. |
8432 | 9458 | ||
9459 | To pass a 64 bit address for FIT image creation, you will need to set: | ||
9460 | - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. | ||
9461 | - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. | ||
9462 | |||
9463 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9464 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, | ||
9465 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9466 | classes. | ||
9467 | |||
9468 | :term:`UBOOT_FIT_ADDRESS_CELLS` | ||
9469 | Specifies the value of the ``#address-cells`` value for the | ||
9470 | description of the U-Boot FIT image. | ||
9471 | |||
9472 | The default value is set to "1" by the :ref:`ref-classes-uboot-sign` | ||
9473 | class, which corresponds to 32 bit addresses. | ||
9474 | |||
9475 | For platforms that need to set 64 bit addresses in | ||
9476 | :term:`UBOOT_LOADADDRESS` and :term:`UBOOT_ENTRYPOINT`, you need to | ||
9477 | set this value to "2", as two 32 bit values (cells) will be needed | ||
9478 | to represent such addresses. | ||
9479 | |||
9480 | Here is an example setting "0x400000000" as a load address:: | ||
9481 | |||
9482 | UBOOT_FIT_ADDRESS_CELLS = "2" | ||
9483 | UBOOT_LOADADDRESS= "0x04 0x00000000" | ||
9484 | |||
9485 | See `more details about #address-cells <https://elinux.org/Device_Tree_Usage#How_Addressing_Works>`__. | ||
9486 | |||
9487 | :term:`UBOOT_FIT_DESC` | ||
9488 | Specifies the description string encoded into a U-Boot fitImage. The default | ||
9489 | value is set by the :ref:`ref-classes-uboot-sign` class as follows:: | ||
9490 | |||
9491 | UBOOT_FIT_DESC ?= "U-Boot fitImage for ${DISTRO_NAME}/${PV}/${MACHINE}" | ||
9492 | |||
9493 | :term:`UBOOT_FIT_GENERATE_KEYS` | ||
9494 | Decides whether to generate the keys for signing the U-Boot fitImage if | ||
9495 | they don't already exist. The keys are created in :term:`SPL_SIGN_KEYDIR`. | ||
9496 | The default value is "0". | ||
9497 | |||
9498 | Enable this as follows:: | ||
9499 | |||
9500 | UBOOT_FIT_GENERATE_KEYS = "1" | ||
9501 | |||
9502 | This variable is used in the :ref:`ref-classes-uboot-sign` class. | ||
9503 | |||
9504 | :term:`UBOOT_FIT_HASH_ALG` | ||
9505 | Specifies the hash algorithm used in creating the U-Boot FIT Image. | ||
9506 | It is set by default to ``sha256`` by the :ref:`ref-classes-uboot-sign` | ||
9507 | class. | ||
9508 | |||
9509 | :term:`UBOOT_FIT_KEY_GENRSA_ARGS` | ||
9510 | Arguments to ``openssl genrsa`` for generating a RSA private key for | ||
9511 | signing the U-Boot FIT image. The default value of this variable | ||
9512 | is set to "-F4" by the :ref:`ref-classes-uboot-sign` class. | ||
9513 | |||
9514 | :term:`UBOOT_FIT_KEY_REQ_ARGS` | ||
9515 | Arguments to ``openssl req`` for generating a certificate for signing | ||
9516 | the U-Boot FIT image. The default value is "-batch -new" by the | ||
9517 | :ref:`ref-classes-uboot-sign` class, "batch" for | ||
9518 | non interactive mode and "new" for generating new keys. | ||
9519 | |||
9520 | :term:`UBOOT_FIT_KEY_SIGN_PKCS` | ||
9521 | Format for the public key certificate used for signing the U-Boot FIT | ||
9522 | image. The default value is set to "x509" by the | ||
9523 | :ref:`ref-classes-uboot-sign` class. | ||
9524 | |||
9525 | :term:`UBOOT_FIT_SIGN_ALG` | ||
9526 | Specifies the signature algorithm used in creating the U-Boot FIT Image. | ||
9527 | This variable is set by default to "rsa2048" by the | ||
9528 | :ref:`ref-classes-uboot-sign` class. | ||
9529 | |||
9530 | :term:`UBOOT_FIT_SIGN_NUMBITS` | ||
9531 | Size of the private key used in signing the U-Boot FIT image, in number | ||
9532 | of bits. The default value for this variable is set to "2048" | ||
9533 | by the :ref:`ref-classes-uboot-sign` class. | ||
9534 | |||
9535 | :term:`UBOOT_FITIMAGE_ENABLE` | ||
9536 | This variable allows to generate a FIT image for U-Boot, which is one | ||
9537 | of the ways to implement a verified boot process. | ||
9538 | |||
9539 | Its default value is "0", so set it to "1" to enable this functionality:: | ||
9540 | |||
9541 | UBOOT_FITIMAGE_ENABLE = "1" | ||
9542 | |||
9543 | See the :ref:`ref-classes-uboot-sign` class for details. | ||
9544 | |||
8433 | :term:`UBOOT_LOADADDRESS` | 9545 | :term:`UBOOT_LOADADDRESS` |
8434 | Specifies the load address for the U-Boot image. During U-Boot image | 9546 | Specifies the load address for the U-Boot image. During U-Boot image |
8435 | creation, the ``UBOOT_LOADADDRESS`` variable is passed as a | 9547 | creation, the :term:`UBOOT_LOADADDRESS` variable is passed as a |
8436 | command-line parameter to the ``uboot-mkimage`` utility. | 9548 | command-line parameter to the ``uboot-mkimage`` utility. |
8437 | 9549 | ||
9550 | To pass a 64 bit address, you will also need to set: | ||
9551 | |||
9552 | - The :term:`FIT_ADDRESS_CELLS` variable for FIT image creation. | ||
9553 | - The :term:`UBOOT_FIT_ADDRESS_CELLS` variable for U-Boot FIT image creation. | ||
9554 | |||
9555 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9556 | :ref:`ref-classes-kernel-uimage`, :ref:`ref-classes-kernel`, | ||
9557 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9558 | classes. | ||
9559 | |||
8438 | :term:`UBOOT_LOCALVERSION` | 9560 | :term:`UBOOT_LOCALVERSION` |
8439 | Appends a string to the name of the local version of the U-Boot | 9561 | Appends a string to the name of the local version of the U-Boot |
8440 | image. For example, assuming the version of the U-Boot image built | 9562 | image. For example, assuming the version of the U-Boot image built |
8441 | was "2013.10", the full version string reported by U-Boot would be | 9563 | was "2013.10", the full version string reported by U-Boot would be |
8442 | "2013.10-yocto" given the following statement: | 9564 | "2013.10-yocto" given the following statement:: |
8443 | :: | ||
8444 | 9565 | ||
8445 | UBOOT_LOCALVERSION = "-yocto" | 9566 | UBOOT_LOCALVERSION = "-yocto" |
8446 | 9567 | ||
@@ -8459,56 +9580,65 @@ system and gives an overview of their function and contents. | |||
8459 | 9580 | ||
8460 | :term:`UBOOT_MKIMAGE` | 9581 | :term:`UBOOT_MKIMAGE` |
8461 | Specifies the name of the mkimage command as used by the | 9582 | Specifies the name of the mkimage command as used by the |
8462 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to assemble | 9583 | :ref:`ref-classes-kernel-fitimage` class to assemble |
8463 | the FIT image. This can be used to substitute an alternative command, wrapper | 9584 | the FIT image. This can be used to substitute an alternative command, wrapper |
8464 | script or function if desired. The default is "uboot-mkimage". | 9585 | script or function if desired. The default is "uboot-mkimage". |
8465 | 9586 | ||
8466 | :term:`UBOOT_MKIMAGE_DTCOPTS` | 9587 | :term:`UBOOT_MKIMAGE_DTCOPTS` |
8467 | Options for the device tree compiler passed to mkimage '-D' | 9588 | Options for the device tree compiler passed to ``mkimage -D`` feature |
8468 | feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class. | 9589 | while creating a FIT image with the :ref:`ref-classes-kernel-fitimage` |
8469 | If ``UBOOT_MKIMAGE_DTCOPTS`` is not set then kernel-fitimage will not | 9590 | class. If :term:`UBOOT_MKIMAGE_DTCOPTS` is not set then the |
8470 | pass the ``-D`` option to mkimage. | 9591 | :ref:`ref-classes-kernel-fitimage` class will not pass the ``-D`` option |
9592 | to ``mkimage``. | ||
9593 | |||
9594 | This variable is also used by the :ref:`ref-classes-uboot-sign` class. | ||
9595 | |||
9596 | :term:`UBOOT_MKIMAGE_KERNEL_TYPE` | ||
9597 | Specifies the type argument for the kernel as passed to ``uboot-mkimage``. | ||
9598 | The default value is "kernel". | ||
8471 | 9599 | ||
8472 | :term:`UBOOT_MKIMAGE_SIGN` | 9600 | :term:`UBOOT_MKIMAGE_SIGN` |
8473 | Specifies the name of the mkimage command as used by the | 9601 | Specifies the name of the mkimage command as used by the |
8474 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to sign | 9602 | :ref:`ref-classes-kernel-fitimage` class to sign |
8475 | the FIT image after it has been assembled (if enabled). This can be used | 9603 | the FIT image after it has been assembled (if enabled). This can be used |
8476 | to substitute an alternative command, wrapper script or function if | 9604 | to substitute an alternative command, wrapper script or function if |
8477 | desired. The default is "${:term:`UBOOT_MKIMAGE`}". | 9605 | desired. The default is "${:term:`UBOOT_MKIMAGE`}". |
8478 | 9606 | ||
8479 | :term:`UBOOT_MKIMAGE_SIGN_ARGS` | 9607 | :term:`UBOOT_MKIMAGE_SIGN_ARGS` |
8480 | Optionally specifies additional arguments for the | 9608 | Optionally specifies additional arguments for the |
8481 | :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to pass to the | 9609 | :ref:`ref-classes-kernel-fitimage` class to pass to the |
8482 | mkimage command when signing the FIT image. | 9610 | mkimage command when signing the FIT image. |
8483 | 9611 | ||
8484 | :term:`UBOOT_RD_ENTRYPOINT` | 9612 | :term:`UBOOT_RD_ENTRYPOINT` |
8485 | Specifies the entrypoint for the RAM disk image. | 9613 | Specifies the entrypoint for the RAM disk image. During FIT image |
8486 | During FIT image creation, the | 9614 | creation, the :term:`UBOOT_RD_ENTRYPOINT` variable is used in |
8487 | ``UBOOT_RD_ENTRYPOINT`` variable is used | 9615 | :ref:`ref-classes-kernel-fitimage` class to specify the entrypoint to be |
8488 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | 9616 | used in creating the Image Tree Source for the FIT image. |
8489 | entrypoint to be used in creating the Image Tree Source for | ||
8490 | the FIT image. | ||
8491 | 9617 | ||
8492 | :term:`UBOOT_RD_LOADADDRESS` | 9618 | :term:`UBOOT_RD_LOADADDRESS` |
8493 | Specifies the load address for the RAM disk image. | 9619 | Specifies the load address for the RAM disk image. During FIT image |
8494 | During FIT image creation, the | 9620 | creation, the :term:`UBOOT_RD_LOADADDRESS` variable is used in |
8495 | ``UBOOT_RD_LOADADDRESS`` variable is used | 9621 | :ref:`ref-classes-kernel-fitimage` class to specify the load address to |
8496 | in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the | 9622 | be used in creating the Image Tree Source for the FIT image. |
8497 | load address to be used in creating the Image Tree Source for | ||
8498 | the FIT image. | ||
8499 | 9623 | ||
8500 | :term:`UBOOT_SIGN_ENABLE` | 9624 | :term:`UBOOT_SIGN_ENABLE` |
8501 | Enable signing of FIT image. The default value is "0". | 9625 | Enable signing of FIT image. The default value is "0". |
8502 | 9626 | ||
9627 | This variable is used by the :ref:`ref-classes-kernel-fitimage`, | ||
9628 | :ref:`ref-classes-uboot-config` and :ref:`ref-classes-uboot-sign` | ||
9629 | classes. | ||
9630 | |||
8503 | :term:`UBOOT_SIGN_KEYDIR` | 9631 | :term:`UBOOT_SIGN_KEYDIR` |
8504 | Location of the directory containing the RSA key and | 9632 | Location of the directory containing the RSA key and certificate used for |
8505 | certificate used for signing FIT image. | 9633 | signing FIT image, used by the :ref:`ref-classes-kernel-fitimage` and |
9634 | :ref:`ref-classes-uboot-sign` classes. | ||
8506 | 9635 | ||
8507 | :term:`UBOOT_SIGN_KEYNAME` | 9636 | :term:`UBOOT_SIGN_KEYNAME` |
8508 | The name of keys used for signing U-Boot FIT image stored in | 9637 | The name of keys used by the :ref:`ref-classes-kernel-fitimage` class |
8509 | :term:`UBOOT_SIGN_KEYDIR` directory. For e.g. dev.key key and dev.crt | 9638 | for signing U-Boot FIT image stored in the :term:`UBOOT_SIGN_KEYDIR` |
8510 | certificate stored in :term:`UBOOT_SIGN_KEYDIR` directory will have | 9639 | directory. If we have for example a ``dev.key`` key and a ``dev.crt`` |
8511 | :term:`UBOOT_SIGN_KEYNAME` set to "dev". | 9640 | certificate stored in the :term:`UBOOT_SIGN_KEYDIR` directory, you will |
9641 | have to set :term:`UBOOT_SIGN_KEYNAME` to ``dev``. | ||
8512 | 9642 | ||
8513 | :term:`UBOOT_SUFFIX` | 9643 | :term:`UBOOT_SUFFIX` |
8514 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` | 9644 | Points to the generated U-Boot extension. For example, ``u-boot.sb`` |
@@ -8523,104 +9653,129 @@ system and gives an overview of their function and contents. | |||
8523 | passes and uses "all" for the target during the U-Boot building | 9653 | passes and uses "all" for the target during the U-Boot building |
8524 | process. | 9654 | process. |
8525 | 9655 | ||
8526 | :term:`UNKNOWN_CONFIGURE_WHITELIST` | 9656 | :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` |
8527 | Specifies a list of options that, if reported by the configure script | 9657 | Specifies a list of options that, if reported by the configure script |
8528 | as being invalid, should not generate a warning during the | 9658 | as being invalid, should not generate a warning during the |
8529 | :ref:`ref-tasks-configure` task. Normally, invalid | 9659 | :ref:`ref-tasks-configure` task. Normally, invalid |
8530 | configure options are simply not passed to the configure script (e.g. | 9660 | configure options are simply not passed to the configure script (e.g. |
8531 | should be removed from :term:`EXTRA_OECONF` or | 9661 | should be removed from :term:`EXTRA_OECONF` or |
8532 | :term:`PACKAGECONFIG_CONFARGS`). | 9662 | :term:`PACKAGECONFIG_CONFARGS`). |
8533 | However, common options, for example, exist that are passed to all | 9663 | However, there are common options that are passed to all |
8534 | configure scripts at a class level that might not be valid for some | 9664 | configure scripts at a class level, but might not be valid for some |
8535 | configure scripts. It follows that no benefit exists in seeing a | 9665 | configure scripts. Therefore warnings about these options are useless. |
8536 | warning about these options. For these cases, the options are added | 9666 | For these cases, the options are added to :term:`UNKNOWN_CONFIGURE_OPT_IGNORE`. |
8537 | to ``UNKNOWN_CONFIGURE_WHITELIST``. | ||
8538 | 9667 | ||
8539 | The configure arguments check that uses | 9668 | The configure arguments check that uses |
8540 | ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the | 9669 | :term:`UNKNOWN_CONFIGURE_OPT_IGNORE` is part of the |
8541 | :ref:`insane <ref-classes-insane>` class and is only enabled if the | 9670 | :ref:`ref-classes-insane` class and is only enabled if the |
8542 | recipe inherits the :ref:`autotools <ref-classes-autotools>` class. | 9671 | recipe inherits the :ref:`ref-classes-autotools` class. |
8543 | 9672 | ||
8544 | :term:`UPDATERCPN` | 9673 | :term:`UPDATERCPN` |
8545 | For recipes inheriting the | 9674 | For recipes inheriting the |
8546 | :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` | 9675 | :ref:`ref-classes-update-rc.d` class, :term:`UPDATERCPN` |
8547 | specifies the package that contains the initscript that is enabled. | 9676 | specifies the package that contains the initscript that is enabled. |
8548 | 9677 | ||
8549 | The default value is "${PN}". Given that almost all recipes that | 9678 | The default value is "${PN}". Given that almost all recipes that |
8550 | install initscripts package them in the main package for the recipe, | 9679 | install initscripts package them in the main package for the recipe, |
8551 | you rarely need to set this variable in individual recipes. | 9680 | you rarely need to set this variable in individual recipes. |
8552 | 9681 | ||
9682 | :term:`UPSTREAM_CHECK_COMMITS` | ||
9683 | You can perform a per-recipe check for what the latest upstream | ||
9684 | source code version is by calling ``devtool latest-version recipe``. If | ||
9685 | the recipe source code is provided from Git repositories, but | ||
9686 | releases are not identified by Git tags, set :term:`UPSTREAM_CHECK_COMMITS` | ||
9687 | to ``1`` in the recipe, and the OpenEmbedded build system | ||
9688 | will compare the latest commit with the one currently specified | ||
9689 | by the recipe (:term:`SRCREV`):: | ||
9690 | |||
9691 | UPSTREAM_CHECK_COMMITS = "1" | ||
9692 | |||
8553 | :term:`UPSTREAM_CHECK_GITTAGREGEX` | 9693 | :term:`UPSTREAM_CHECK_GITTAGREGEX` |
8554 | You can perform a per-recipe check for what the latest upstream | 9694 | You can perform a per-recipe check for what the latest upstream |
8555 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | 9695 | source code version is by calling ``devtool latest-version recipe``. If |
8556 | the recipe source code is provided from Git repositories, the | 9696 | the recipe source code is provided from Git repositories, the |
8557 | OpenEmbedded build system determines the latest upstream version by | 9697 | OpenEmbedded build system determines the latest upstream version by |
8558 | picking the latest tag from the list of all repository tags. | 9698 | picking the latest tag from the list of all repository tags. |
8559 | 9699 | ||
8560 | You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a | 9700 | You can use the :term:`UPSTREAM_CHECK_GITTAGREGEX` variable to provide a |
8561 | regular expression to filter only the relevant tags should the | 9701 | regular expression to filter only the relevant tags should the |
8562 | default filter not work correctly. | 9702 | default filter not work correctly:: |
8563 | :: | ||
8564 | 9703 | ||
8565 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" | 9704 | UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex" |
8566 | 9705 | ||
8567 | :term:`UPSTREAM_CHECK_REGEX` | 9706 | :term:`UPSTREAM_CHECK_REGEX` |
8568 | Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different | 9707 | Use the :term:`UPSTREAM_CHECK_REGEX` variable to specify a different |
8569 | regular expression instead of the default one when the package | 9708 | regular expression instead of the default one when the package |
8570 | checking system is parsing the page found using | 9709 | checking system is parsing the page found using |
8571 | :term:`UPSTREAM_CHECK_URI`. | 9710 | :term:`UPSTREAM_CHECK_URI`:: |
8572 | :: | ||
8573 | 9711 | ||
8574 | UPSTREAM_CHECK_REGEX = "package_regex" | 9712 | UPSTREAM_CHECK_REGEX = "package_regex" |
8575 | 9713 | ||
8576 | :term:`UPSTREAM_CHECK_URI` | 9714 | :term:`UPSTREAM_CHECK_URI` |
8577 | You can perform a per-recipe check for what the latest upstream | 9715 | You can perform a per-recipe check for what the latest upstream |
8578 | source code version is by calling ``bitbake -c checkpkg`` recipe. If | 9716 | source code version is by calling ``devtool latest-version recipe``. If |
8579 | the source code is provided from tarballs, the latest version is | 9717 | the source code is provided from tarballs, the latest version is |
8580 | determined by fetching the directory listing where the tarball is and | 9718 | determined by fetching the directory listing where the tarball is and |
8581 | attempting to find a later tarball. When this approach does not work, | 9719 | attempting to find a later tarball. When this approach does not work, |
8582 | you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that | 9720 | you can use :term:`UPSTREAM_CHECK_URI` to provide a different URI that |
8583 | contains the link to the latest tarball. | 9721 | contains the link to the latest tarball:: |
8584 | :: | ||
8585 | 9722 | ||
8586 | UPSTREAM_CHECK_URI = "recipe_url" | 9723 | UPSTREAM_CHECK_URI = "recipe_url" |
8587 | 9724 | ||
9725 | :term:`UPSTREAM_VERSION_UNKNOWN` | ||
9726 | You can perform a per-recipe check for what the latest upstream | ||
9727 | source code version is by calling ``devtool latest-version recipe``. | ||
9728 | If no combination of the :term:`UPSTREAM_CHECK_URI`, :term:`UPSTREAM_CHECK_REGEX`, | ||
9729 | :term:`UPSTREAM_CHECK_GITTAGREGEX` and :term:`UPSTREAM_CHECK_COMMITS` variables in | ||
9730 | the recipe allows to determine what the latest upstream version is, | ||
9731 | you can set :term:`UPSTREAM_VERSION_UNKNOWN` to ``1`` in the recipe | ||
9732 | to acknowledge that the check cannot be performed:: | ||
9733 | |||
9734 | UPSTREAM_VERSION_UNKNOWN = "1" | ||
9735 | |||
8588 | :term:`USE_DEVFS` | 9736 | :term:`USE_DEVFS` |
8589 | Determines if ``devtmpfs`` is used for ``/dev`` population. The | 9737 | Determines if ``devtmpfs`` is used for ``/dev`` population. The |
8590 | default value used for ``USE_DEVFS`` is "1" when no value is | 9738 | default value used for :term:`USE_DEVFS` is "1" when no value is |
8591 | specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a | 9739 | specifically set. Typically, you would set :term:`USE_DEVFS` to "0" for a |
8592 | statically populated ``/dev`` directory. | 9740 | statically populated ``/dev`` directory. |
8593 | 9741 | ||
8594 | See the ":ref:`dev-manual/common-tasks:selecting a device manager`" section in | 9742 | See the ":ref:`dev-manual/device-manager:selecting a device manager`" section in |
8595 | the Yocto Project Development Tasks Manual for information on how to | 9743 | the Yocto Project Development Tasks Manual for information on how to |
8596 | use this variable. | 9744 | use this variable. |
8597 | 9745 | ||
8598 | :term:`USE_VT` | 9746 | :term:`USE_VT` |
8599 | When using | 9747 | When using |
8600 | :ref:`SysVinit <dev-manual/common-tasks:enabling system services>`, | 9748 | :ref:`SysVinit <dev-manual/new-recipe:enabling system services>`, |
8601 | determines whether or not to run a | 9749 | determines whether or not to run a :wikipedia:`getty <Getty_(Unix)>` |
8602 | `getty <https://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any | 9750 | on any virtual terminals in order to enable logging in through those |
8603 | virtual terminals in order to enable logging in through those | ||
8604 | terminals. | 9751 | terminals. |
8605 | 9752 | ||
8606 | The default value used for ``USE_VT`` is "1" when no default value is | 9753 | The default value used for :term:`USE_VT` is "1" when no default value is |
8607 | specifically set. Typically, you would set ``USE_VT`` to "0" in the | 9754 | specifically set. Typically, you would set :term:`USE_VT` to "0" in the |
8608 | machine configuration file for machines that do not have a graphical | 9755 | machine configuration file for machines that do not have a graphical |
8609 | display attached and therefore do not need virtual terminal | 9756 | display attached and therefore do not need virtual terminal |
8610 | functionality. | 9757 | functionality. |
8611 | 9758 | ||
8612 | :term:`USER_CLASSES` | 9759 | :term:`USER_CLASSES` |
8613 | A list of classes to globally inherit. These classes are used by the | 9760 | A list of classes to globally inherit. These classes are used by the |
8614 | OpenEmbedded build system to enable extra features (e.g. | 9761 | OpenEmbedded build system to enable extra features. |
8615 | ``buildstats``, ``image-mklibs``, and so forth). | ||
8616 | 9762 | ||
8617 | The default list is set in your ``local.conf`` file: | 9763 | Classes inherited using :term:`USER_CLASSES` must be located in the |
8618 | :: | 9764 | ``classes-global/`` or ``classes/`` subdirectories. |
8619 | 9765 | ||
8620 | USER_CLASSES ?= "buildstats image-mklibs image-prelink" | 9766 | The default list is set in your ``local.conf`` file:: |
9767 | |||
9768 | USER_CLASSES ?= "buildstats" | ||
8621 | 9769 | ||
8622 | For more information, see | 9770 | For more information, see |
8623 | ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. | 9771 | ``meta-poky/conf/templates/default/local.conf.sample`` in the |
9772 | :term:`Source Directory`. | ||
9773 | |||
9774 | :term:`USERADD_DEPENDS` | ||
9775 | Specifies a list of recipes that create users / groups (via | ||
9776 | :term:`USERADD_PARAM` / :term:`GROUPADD_PARAM`) which a recipe | ||
9777 | depends upon. This ensures that those users / groups are available | ||
9778 | when building a recipe. | ||
8624 | 9779 | ||
8625 | :term:`USERADD_ERROR_DYNAMIC` | 9780 | :term:`USERADD_ERROR_DYNAMIC` |
8626 | If set to ``error``, forces the OpenEmbedded build system to produce | 9781 | If set to ``error``, forces the OpenEmbedded build system to produce |
@@ -8632,11 +9787,10 @@ system and gives an overview of their function and contents. | |||
8632 | 9787 | ||
8633 | The default behavior for the build system is to dynamically apply | 9788 | The default behavior for the build system is to dynamically apply |
8634 | ``uid`` and ``gid`` values. Consequently, the | 9789 | ``uid`` and ``gid`` values. Consequently, the |
8635 | ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan | 9790 | :term:`USERADD_ERROR_DYNAMIC` variable is by default not set. If you plan |
8636 | on using statically assigned ``gid`` and ``uid`` values, you should | 9791 | on using statically assigned ``gid`` and ``uid`` values, you should |
8637 | set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` | 9792 | set the :term:`USERADD_ERROR_DYNAMIC` variable in your ``local.conf`` |
8638 | file as follows: | 9793 | file as follows:: |
8639 | :: | ||
8640 | 9794 | ||
8641 | USERADD_ERROR_DYNAMIC = "error" | 9795 | USERADD_ERROR_DYNAMIC = "error" |
8642 | 9796 | ||
@@ -8650,7 +9804,7 @@ system and gives an overview of their function and contents. | |||
8650 | .. note:: | 9804 | .. note:: |
8651 | 9805 | ||
8652 | There is a difference in behavior between setting | 9806 | There is a difference in behavior between setting |
8653 | ``USERADD_ERROR_DYNAMIC`` to ``error`` and setting it to ``warn``. | 9807 | :term:`USERADD_ERROR_DYNAMIC` to ``error`` and setting it to ``warn``. |
8654 | When it is set to ``warn``, the build system will report a warning for | 9808 | When it is set to ``warn``, the build system will report a warning for |
8655 | every undefined ``uid`` and ``gid`` in any recipe. But when it is set | 9809 | every undefined ``uid`` and ``gid`` in any recipe. But when it is set |
8656 | to ``error``, it will only report errors for recipes that are actually | 9810 | to ``error``, it will only report errors for recipes that are actually |
@@ -8666,8 +9820,7 @@ system and gives an overview of their function and contents. | |||
8666 | When applying static group identification (``gid``) values, the | 9820 | When applying static group identification (``gid``) values, the |
8667 | OpenEmbedded build system looks in :term:`BBPATH` for a | 9821 | OpenEmbedded build system looks in :term:`BBPATH` for a |
8668 | ``files/group`` file and then applies those ``uid`` values. Set the | 9822 | ``files/group`` file and then applies those ``uid`` values. Set the |
8669 | variable as follows in your ``local.conf`` file: | 9823 | variable as follows in your ``local.conf`` file:: |
8670 | :: | ||
8671 | 9824 | ||
8672 | 9825 | ||
8673 | USERADD_GID_TABLES = "files/group" | 9826 | USERADD_GID_TABLES = "files/group" |
@@ -8678,33 +9831,31 @@ system and gives an overview of their function and contents. | |||
8678 | causes the build system to use static ``gid`` values. | 9831 | causes the build system to use static ``gid`` values. |
8679 | 9832 | ||
8680 | :term:`USERADD_PACKAGES` | 9833 | :term:`USERADD_PACKAGES` |
8681 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 9834 | When inheriting the :ref:`ref-classes-useradd` class, |
8682 | this variable specifies the individual packages within the recipe | 9835 | this variable specifies the individual packages within the recipe |
8683 | that require users and/or groups to be added. | 9836 | that require users and/or groups to be added. |
8684 | 9837 | ||
8685 | You must set this variable if the recipe inherits the class. For | 9838 | You must set this variable if the recipe inherits the class. For |
8686 | example, the following enables adding a user for the main package in | 9839 | example, the following enables adding a user for the main package in |
8687 | a recipe: | 9840 | a recipe:: |
8688 | :: | ||
8689 | 9841 | ||
8690 | USERADD_PACKAGES = "${PN}" | 9842 | USERADD_PACKAGES = "${PN}" |
8691 | 9843 | ||
8692 | .. note:: | 9844 | .. note:: |
8693 | 9845 | ||
8694 | It follows that if you are going to use the ``USERADD_PACKAGES`` | 9846 | It follows that if you are going to use the :term:`USERADD_PACKAGES` |
8695 | variable, you need to set one or more of the :term:`USERADD_PARAM`, | 9847 | variable, you need to set one or more of the :term:`USERADD_PARAM`, |
8696 | :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. | 9848 | :term:`GROUPADD_PARAM`, or :term:`GROUPMEMS_PARAM` variables. |
8697 | 9849 | ||
8698 | :term:`USERADD_PARAM` | 9850 | :term:`USERADD_PARAM` |
8699 | When inheriting the :ref:`useradd <ref-classes-useradd>` class, | 9851 | When inheriting the :ref:`ref-classes-useradd` class, |
8700 | this variable specifies for a package what parameters should pass to | 9852 | this variable specifies for a package what parameters should pass to |
8701 | the ``useradd`` command if you add a user to the system when the | 9853 | the ``useradd`` command if you add a user to the system when the |
8702 | package is installed. | 9854 | package is installed. |
8703 | 9855 | ||
8704 | Here is an example from the ``dbus`` recipe: | 9856 | Here is an example from the ``dbus`` recipe:: |
8705 | :: | ||
8706 | 9857 | ||
8707 | USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \ | 9858 | USERADD_PARAM:${PN} = "--system --home ${localstatedir}/lib/dbus \ |
8708 | --no-create-home --shell /bin/false \ | 9859 | --no-create-home --shell /bin/false \ |
8709 | --user-group messagebus" | 9860 | --user-group messagebus" |
8710 | 9861 | ||
@@ -8720,8 +9871,7 @@ system and gives an overview of their function and contents. | |||
8720 | When applying static user identification (``uid``) values, the | 9871 | When applying static user identification (``uid``) values, the |
8721 | OpenEmbedded build system looks in :term:`BBPATH` for a | 9872 | OpenEmbedded build system looks in :term:`BBPATH` for a |
8722 | ``files/passwd`` file and then applies those ``uid`` values. Set the | 9873 | ``files/passwd`` file and then applies those ``uid`` values. Set the |
8723 | variable as follows in your ``local.conf`` file: | 9874 | variable as follows in your ``local.conf`` file:: |
8724 | :: | ||
8725 | 9875 | ||
8726 | USERADD_UID_TABLES = "files/passwd" | 9876 | USERADD_UID_TABLES = "files/passwd" |
8727 | 9877 | ||
@@ -8752,48 +9902,95 @@ system and gives an overview of their function and contents. | |||
8752 | Additionally, you should also set the | 9902 | Additionally, you should also set the |
8753 | :term:`USERADD_ERROR_DYNAMIC` variable. | 9903 | :term:`USERADD_ERROR_DYNAMIC` variable. |
8754 | 9904 | ||
9905 | :term:`VIRTUAL-RUNTIME` | ||
9906 | :term:`VIRTUAL-RUNTIME` is a commonly used prefix for defining virtual | ||
9907 | packages for runtime usage, typically for use in :term:`RDEPENDS` | ||
9908 | or in image definitions. | ||
9909 | |||
9910 | An example is ``VIRTUAL-RUNTIME_base-utils`` that makes it possible | ||
9911 | to either use BusyBox based utilities:: | ||
9912 | |||
9913 | VIRTUAL-RUNTIME_base-utils = "busybox" | ||
9914 | |||
9915 | or their full featured implementations from GNU Coreutils | ||
9916 | and other projects:: | ||
9917 | |||
9918 | VIRTUAL-RUNTIME_base-utils = "packagegroup-core-base-utils" | ||
9919 | |||
9920 | Here are two examples using this virtual runtime package. The | ||
9921 | first one is in :yocto_git:`initramfs-framework_1.0.bb | ||
9922 | </poky/tree/meta/recipes-core/initrdscripts/initramfs-framework_1.0.bb?h=scarthgap>`:: | ||
9923 | |||
9924 | RDEPENDS:${PN} += "${VIRTUAL-RUNTIME_base-utils}" | ||
9925 | |||
9926 | The second example is in the :yocto_git:`core-image-initramfs-boot | ||
9927 | </poky/tree/meta/recipes-core/images/core-image-initramfs-boot.bb?h=scarthgap>` | ||
9928 | image definition:: | ||
9929 | |||
9930 | PACKAGE_INSTALL = "${INITRAMFS_SCRIPTS} ${VIRTUAL-RUNTIME_base-utils} base-passwd" | ||
9931 | |||
8755 | :term:`VOLATILE_LOG_DIR` | 9932 | :term:`VOLATILE_LOG_DIR` |
8756 | Specifies the persistence of the target's ``/var/log`` directory, | 9933 | Specifies the persistence of the target's ``/var/log`` directory, |
8757 | which is used to house postinstall target log files. | 9934 | which is used to house postinstall target log files. |
8758 | 9935 | ||
8759 | By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the | 9936 | By default, :term:`VOLATILE_LOG_DIR` is set to "yes", which means the |
8760 | file is not persistent. You can override this setting by setting the | 9937 | file is not persistent. You can override this setting by setting the |
8761 | variable to "no" to make the log directory persistent. | 9938 | variable to "no" to make the log directory persistent. |
8762 | 9939 | ||
9940 | :term:`VOLATILE_TMP_DIR` | ||
9941 | Specifies the persistence of the target's ``/tmp`` directory. | ||
9942 | |||
9943 | By default, :term:`VOLATILE_TMP_DIR` is set to "yes", in which case | ||
9944 | ``/tmp`` links to a directory which resides in RAM in a ``tmpfs`` | ||
9945 | filesystem. | ||
9946 | |||
9947 | If instead, you want the ``/tmp`` directory to be persistent, set the | ||
9948 | variable to "no" to make it a regular directory in the root filesystem. | ||
9949 | |||
9950 | This supports both sysvinit and systemd based systems. | ||
9951 | |||
8763 | :term:`WARN_QA` | 9952 | :term:`WARN_QA` |
8764 | Specifies the quality assurance checks whose failures are reported as | 9953 | Specifies the quality assurance checks whose failures are reported as |
8765 | warnings by the OpenEmbedded build system. You set this variable in | 9954 | warnings by the OpenEmbedded build system. You set this variable in |
8766 | your distribution configuration file. For a list of the checks you | 9955 | your distribution configuration file. For a list of the checks you |
8767 | can control with this variable, see the | 9956 | can control with this variable, see the |
8768 | ":ref:`insane.bbclass <ref-classes-insane>`" section. | 9957 | ":ref:`ref-classes-insane`" section. |
9958 | |||
9959 | :term:`WATCHDOG_TIMEOUT` | ||
9960 | Specifies the timeout in seconds used by the ``watchdog`` recipe and | ||
9961 | also by ``systemd`` during reboot. The default is 60 seconds. | ||
9962 | |||
9963 | :term:`WIRELESS_DAEMON` | ||
9964 | For ``connman`` and ``packagegroup-base``, specifies the wireless | ||
9965 | daemon to use. The default is "wpa-supplicant" (note that the value | ||
9966 | uses a dash and not an underscore). | ||
8769 | 9967 | ||
8770 | :term:`WKS_FILE` | 9968 | :term:`WKS_FILE` |
8771 | Specifies the location of the Wic kickstart file that is used by the | 9969 | Specifies the location of the Wic kickstart file that is used by the |
8772 | OpenEmbedded build system to create a partitioned image | 9970 | OpenEmbedded build system to create a partitioned image |
8773 | (image\ ``.wic``). For information on how to create a partitioned | 9971 | (``image.wic``). For information on how to create a partitioned |
8774 | image, see the | 9972 | image, see the |
8775 | ":ref:`dev-manual/common-tasks:creating partitioned images using wic`" | 9973 | ":ref:`dev-manual/wic:creating partitioned images using wic`" |
8776 | section in the Yocto Project Development Tasks Manual. For details on | 9974 | section in the Yocto Project Development Tasks Manual. For details on |
8777 | the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. | 9975 | the kickstart file format, see the ":doc:`/ref-manual/kickstart`" Chapter. |
8778 | 9976 | ||
8779 | :term:`WKS_FILE_DEPENDS` | 9977 | :term:`WKS_FILE_DEPENDS` |
8780 | When placed in the recipe that builds your image, this variable lists | 9978 | When placed in the recipe that builds your image, this variable lists |
8781 | build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only | 9979 | build-time dependencies. The :term:`WKS_FILE_DEPENDS` variable is only |
8782 | applicable when Wic images are active (i.e. when | 9980 | applicable when Wic images are active (i.e. when |
8783 | :term:`IMAGE_FSTYPES` contains entries related | 9981 | :term:`IMAGE_FSTYPES` contains entries related |
8784 | to Wic). If your recipe does not create Wic images, the variable has | 9982 | to Wic). If your recipe does not create Wic images, the variable has |
8785 | no effect. | 9983 | no effect. |
8786 | 9984 | ||
8787 | The ``WKS_FILE_DEPENDS`` variable is similar to the | 9985 | The :term:`WKS_FILE_DEPENDS` variable is similar to the |
8788 | :term:`DEPENDS` variable. When you use the variable in | 9986 | :term:`DEPENDS` variable. When you use the variable in |
8789 | your recipe that builds the Wic image, dependencies you list in the | 9987 | your recipe that builds the Wic image, dependencies you list in the |
8790 | ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. | 9988 | :term:`WKS_FILE_DEPENDS` variable are added to the :term:`DEPENDS` variable. |
8791 | 9989 | ||
8792 | With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to | 9990 | With the :term:`WKS_FILE_DEPENDS` variable, you have the possibility to |
8793 | specify a list of additional dependencies (e.g. native tools, | 9991 | specify a list of additional dependencies (e.g. native tools, |
8794 | bootloaders, and so forth), that are required to build Wic images. | 9992 | bootloaders, and so forth), that are required to build Wic images. |
8795 | Following is an example: | 9993 | Here is an example:: |
8796 | :: | ||
8797 | 9994 | ||
8798 | WKS_FILE_DEPENDS = "some-native-tool" | 9995 | WKS_FILE_DEPENDS = "some-native-tool" |
8799 | 9996 | ||
@@ -8801,14 +9998,26 @@ system and gives an overview of their function and contents. | |||
8801 | previous example, some-native-tool would be replaced with an actual | 9998 | previous example, some-native-tool would be replaced with an actual |
8802 | native tool on which the build would depend. | 9999 | native tool on which the build would depend. |
8803 | 10000 | ||
10001 | :term:`WKS_FILES` | ||
10002 | Specifies a list of candidate Wic kickstart files to be used by the | ||
10003 | OpenEmbedded build system to create a partitioned image. Only the | ||
10004 | first one that is found, from left to right, will be used. | ||
10005 | |||
10006 | This is only useful when there are multiple ``.wks`` files that can be | ||
10007 | used to produce an image. A typical case is when multiple layers are | ||
10008 | used for different hardware platforms, each supplying a different | ||
10009 | ``.wks`` file. In this case, you specify all possible ones through | ||
10010 | :term:`WKS_FILES`. | ||
10011 | |||
10012 | If only one ``.wks`` file is used, set :term:`WKS_FILE` instead. | ||
10013 | |||
8804 | :term:`WORKDIR` | 10014 | :term:`WORKDIR` |
8805 | The pathname of the work directory in which the OpenEmbedded build | 10015 | The pathname of the work directory in which the OpenEmbedded build |
8806 | system builds a recipe. This directory is located within the | 10016 | system builds a recipe. This directory is located within the |
8807 | :term:`TMPDIR` directory structure and is specific to | 10017 | :term:`TMPDIR` directory structure and is specific to |
8808 | the recipe being built and the system for which it is being built. | 10018 | the recipe being built and the system for which it is being built. |
8809 | 10019 | ||
8810 | The ``WORKDIR`` directory is defined as follows: | 10020 | The :term:`WORKDIR` directory is defined as follows:: |
8811 | :: | ||
8812 | 10021 | ||
8813 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} | 10022 | ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} |
8814 | 10023 | ||
@@ -8817,18 +10026,17 @@ system and gives an overview of their function and contents. | |||
8817 | - :term:`TMPDIR`: The top-level build output directory | 10026 | - :term:`TMPDIR`: The top-level build output directory |
8818 | - :term:`MULTIMACH_TARGET_SYS`: The target system identifier | 10027 | - :term:`MULTIMACH_TARGET_SYS`: The target system identifier |
8819 | - :term:`PN`: The recipe name | 10028 | - :term:`PN`: The recipe name |
8820 | - :term:`EXTENDPE`: The epoch - (if :term:`PE` is not specified, which | 10029 | - :term:`EXTENDPE`: The epoch --- if :term:`PE` is not specified, which |
8821 | is usually the case for most recipes, then `EXTENDPE` is blank) | 10030 | is usually the case for most recipes, then :term:`EXTENDPE` is blank. |
8822 | - :term:`PV`: The recipe version | 10031 | - :term:`PV`: The recipe version |
8823 | - :term:`PR`: The recipe revision | 10032 | - :term:`PR`: The recipe revision |
8824 | 10033 | ||
8825 | As an example, assume a Source Directory top-level folder name | 10034 | As an example, assume a Source Directory top-level folder name |
8826 | ``poky``, a default Build Directory at ``poky/build``, and a | 10035 | ``poky``, a default :term:`Build Directory` at ``poky/build``, and a |
8827 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose | 10036 | ``qemux86-poky-linux`` machine target system. Furthermore, suppose |
8828 | your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work | 10037 | your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work |
8829 | directory the build system uses to build the package would be as | 10038 | directory the build system uses to build the package would be as |
8830 | follows: | 10039 | follows:: |
8831 | :: | ||
8832 | 10040 | ||
8833 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 | 10041 | poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 |
8834 | 10042 | ||
@@ -8839,6 +10047,37 @@ system and gives an overview of their function and contents. | |||
8839 | indirectly, includes "x11-base" in | 10047 | indirectly, includes "x11-base" in |
8840 | :term:`IMAGE_FEATURES`. | 10048 | :term:`IMAGE_FEATURES`. |
8841 | 10049 | ||
8842 | The default value of ``XSERVER``, if not specified in the machine | 10050 | The default value of :term:`XSERVER`, if not specified in the machine |
8843 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". | 10051 | configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". |
8844 | 10052 | ||
10053 | :term:`XZ_THREADS` | ||
10054 | Specifies the number of parallel threads that should be used when | ||
10055 | using xz compression. | ||
10056 | |||
10057 | By default this scales with core count, but is never set less than 2 | ||
10058 | to ensure that multi-threaded mode is always used so that the output | ||
10059 | file contents are deterministic. Builds will work with a value of 1 | ||
10060 | but the output will differ compared to the output from the compression | ||
10061 | generated when more than one thread is used. | ||
10062 | |||
10063 | On systems where many tasks run in parallel, setting a limit to this | ||
10064 | can be helpful in controlling system resource usage. | ||
10065 | |||
10066 | :term:`XZ_MEMLIMIT` | ||
10067 | Specifies the maximum memory the xz compression should use as a percentage | ||
10068 | of system memory. If unconstrained the xz compressor can use large amounts of | ||
10069 | memory and become problematic with parallelism elsewhere in the build. | ||
10070 | "50%" has been found to be a good value. | ||
10071 | |||
10072 | :term:`ZSTD_THREADS` | ||
10073 | Specifies the number of parallel threads that should be used when | ||
10074 | using ZStandard compression. | ||
10075 | |||
10076 | By default this scales with core count, but is never set less than 2 | ||
10077 | to ensure that multi-threaded mode is always used so that the output | ||
10078 | file contents are deterministic. Builds will work with a value of 1 | ||
10079 | but the output will differ compared to the output from the compression | ||
10080 | generated when more than one thread is used. | ||
10081 | |||
10082 | On systems where many tasks run in parallel, setting a limit to this | ||
10083 | can be helpful in controlling system resource usage. | ||