summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/ref-manual/faq.rst129
-rw-r--r--documentation/ref-manual/migration.rst937
-rw-r--r--documentation/ref-manual/ref-classes.rst436
-rw-r--r--documentation/ref-manual/ref-devtool-reference.rst404
-rw-r--r--documentation/ref-manual/ref-features.rst28
-rw-r--r--documentation/ref-manual/ref-images.rst16
-rw-r--r--documentation/ref-manual/ref-kickstart.rst57
-rw-r--r--documentation/ref-manual/ref-qa-checks.rst17
-rw-r--r--documentation/ref-manual/ref-release-process.rst33
-rw-r--r--documentation/ref-manual/ref-structure.rst110
-rw-r--r--documentation/ref-manual/ref-system-requirements.rst181
-rw-r--r--documentation/ref-manual/ref-tasks.rst192
-rw-r--r--documentation/ref-manual/ref-terms.rst28
-rw-r--r--documentation/ref-manual/ref-variables.rst5621
-rw-r--r--documentation/ref-manual/ref-varlocality.rst88
-rw-r--r--documentation/ref-manual/resources.rst48
16 files changed, 4886 insertions, 3439 deletions
diff --git a/documentation/ref-manual/faq.rst b/documentation/ref-manual/faq.rst
index e25f0b278c..04066e9202 100644
--- a/documentation/ref-manual/faq.rst
+++ b/documentation/ref-manual/faq.rst
@@ -4,9 +4,9 @@
4FAQ 4FAQ
5*** 5***
6 6
7**Q:** How does Poky differ from `OpenEmbedded <&OE_HOME_URL;>`__? 7**Q:** How does Poky differ from `OpenEmbedded <http://www.openembedded.org/>`__?
8 8
9**A:** The term "`Poky <#>`__" refers to the specific reference build 9**A:** The term ``Poky`` refers to the specific reference build
10system that the Yocto Project provides. Poky is based on 10system that the Yocto Project provides. Poky is based on
11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the 11:term:`OpenEmbedded-Core (OE-Core)` and :term:`BitBake`. Thus, the
12generic term used here for the build system is the "OpenEmbedded build 12generic term used here for the build system is the "OpenEmbedded build
@@ -44,11 +44,10 @@ steps on how to update your build tools.
44 44
45**A:** Support for an additional board is added by creating a Board 45**A:** Support for an additional board is added by creating a Board
46Support Package (BSP) layer for it. For more information on how to 46Support Package (BSP) layer for it. For more information on how to
47create a BSP layer, see the "`Understanding and Creating 47create a BSP layer, see the
48Layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__" 48":ref:`dev-manual/dev-manual-common-tasks:understanding and creating layers`"
49section in the Yocto Project Development Tasks Manual and the `Yocto 49section in the Yocto Project Development Tasks Manual and the
50Project Board Support Package (BSP) Developer's 50:doc:`../bsp-guide/bsp-guide`.
51Guide <&YOCTO_DOCS_BSP_URL;>`__.
52 51
53Usually, if the board is not completely exotic, adding support in the 52Usually, if the board is not completely exotic, adding support in the
54Yocto Project is fairly straightforward. 53Yocto Project is fairly straightforward.
@@ -73,8 +72,8 @@ device.
73**Q:** How do I add my package to the Yocto Project? 72**Q:** How do I add my package to the Yocto Project?
74 73
75**A:** To add a package, you need to create a BitBake recipe. For 74**A:** To add a package, you need to create a BitBake recipe. For
76information on how to create a BitBake recipe, see the "`Writing a New 75information on how to create a BitBake recipe, see the
77Recipe <&YOCTO_DOCS_DEV_URL;#new-recipe-writing-a-new-recipe>`__" 76":ref:`dev-manual/dev-manual-common-tasks:writing a new recipe`"
78section in the Yocto Project Development Tasks Manual. 77section in the Yocto Project Development Tasks Manual.
79 78
80**Q:** Do I have to reflash my entire board with a new Yocto Project 79**Q:** Do I have to reflash my entire board with a new Yocto Project
@@ -126,12 +125,18 @@ file.
126 125
127Following is the applicable code for setting various proxy types in the 126Following is the applicable code for setting various proxy types in the
128``.wgetrc`` file. By default, these settings are disabled with comments. 127``.wgetrc`` file. By default, these settings are disabled with comments.
129To use them, remove the comments: # You can set the default proxies for 128To use them, remove the comments: ::
130Wget to use for http, https, and ftp. # They will override the value in 129
131the environment. #https_proxy = http://proxy.yoyodyne.com:18023/ 130 # You can set the default proxies for Wget to use for http, https, and ftp.
132#http_proxy = http://proxy.yoyodyne.com:18023/ #ftp_proxy = 131 # They will override the value in the environment.
133http://proxy.yoyodyne.com:18023/ # If you do not want to use proxy at 132 #https_proxy = http://proxy.yoyodyne.com:18023/
134all, set this to off. #use_proxy = on The Yocto Project also includes a 133 #http_proxy = http://proxy.yoyodyne.com:18023/
134 #ftp_proxy = http://proxy.yoyodyne.com:18023/
135
136 # If you do not want to use proxy at all, set this to off.
137 #use_proxy = on
138
139The Yocto Project also includes a
135``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS 140``meta-poky/conf/site.conf.sample`` file that shows how to configure CVS
136and Git proxy servers if needed. For more information on setting up 141and Git proxy servers if needed. For more information on setting up
137various proxy types and configuring proxy servers, see the 142various proxy types and configuring proxy servers, see the
@@ -167,8 +172,12 @@ always been traced back to hardware or virtualization issues.
167**A:** If you get an error message that indicates GNU ``libiconv`` is 172**A:** If you get an error message that indicates GNU ``libiconv`` is
168not in use but ``iconv.h`` has been included from ``libiconv``, you need 173not in use but ``iconv.h`` has been included from ``libiconv``, you need
169to check to see if you have a previously installed version of the header 174to check to see if you have a previously installed version of the header
170file in ``/usr/local/include``. #error GNU libiconv not in use but 175file in ``/usr/local/include``.
171included iconv.h is from libiconv If you find a previously installed 176::
177
178 #error GNU libiconv not in use but included iconv.h is from libiconv
179
180If you find a previously installed
172file, you should either uninstall it or temporarily rename it and try 181file, you should either uninstall it or temporarily rename it and try
173the build again. 182the build again.
174 183
@@ -189,20 +198,21 @@ and also any configuration information about how that package was
189configured and built. 198configured and built.
190 199
191You can find more information on licensing in the 200You can find more information on licensing in the
192"`Licensing <&YOCTO_DOCS_OM_URL;#licensing>`__" section in the Yocto 201":ref:`overview-manual/overview-manual-development-environment:licensing`"
193Project Overview and Concepts Manual and also in the "`Maintaining Open 202section in the Yocto
194Source License Compliance During Your Product's 203Project Overview and Concepts Manual and also in the
195Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__" 204":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
196section in the Yocto Project Development Tasks Manual. 205section in the Yocto Project Development Tasks Manual.
197 206
198**Q:** How do I disable the cursor on my touchscreen device? 207**Q:** How do I disable the cursor on my touchscreen device?
199 208
200**A:** You need to create a form factor file as described in the 209**A:** You need to create a form factor file as described in the
201"`Miscellaneous BSP-Specific Recipe 210":ref:`bsp-filelayout-misc-recipes`" section in
202Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
203the Yocto Project Board Support Packages (BSP) Developer's Guide. Set 211the Yocto Project Board Support Packages (BSP) Developer's Guide. Set
204the ``HAVE_TOUCHSCREEN`` variable equal to one as follows: 212the ``HAVE_TOUCHSCREEN`` variable equal to one as follows:
205HAVE_TOUCHSCREEN=1 213::
214
215 HAVE_TOUCHSCREEN=1
206 216
207**Q:** How do I make sure connected network interfaces are brought up by 217**Q:** How do I make sure connected network interfaces are brought up by
208default? 218default?
@@ -210,14 +220,14 @@ default?
210**A:** The default interfaces file provided by the netbase recipe does 220**A:** The default interfaces file provided by the netbase recipe does
211not automatically bring up network interfaces. Therefore, you will need 221not automatically bring up network interfaces. Therefore, you will need
212to add a BSP-specific netbase that includes an interfaces file. See the 222to add a BSP-specific netbase that includes an interfaces file. See the
213"`Miscellaneous BSP-Specific Recipe 223":ref:`bsp-filelayout-misc-recipes`" section in
214Files <&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes>`__" section in
215the Yocto Project Board Support Packages (BSP) Developer's Guide for 224the Yocto Project Board Support Packages (BSP) Developer's Guide for
216information on creating these types of miscellaneous recipe files. 225information on creating these types of miscellaneous recipe files.
217 226
218For example, add the following files to your layer: 227For example, add the following files to your layer: ::
219meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces 228
220meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend 229 meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
230 meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
221 231
222**Q:** How do I create images with more free space? 232**Q:** How do I create images with more free space?
223 233
@@ -260,7 +270,7 @@ controls which ``tcmode-*.inc`` file to include from the
260The default value of ``TCMODE`` is "default", which tells the 270The default value of ``TCMODE`` is "default", which tells the
261OpenEmbedded build system to use its internally built toolchain (i.e. 271OpenEmbedded build system to use its internally built toolchain (i.e.
262``tcmode-default.inc``). However, other patterns are accepted. In 272``tcmode-default.inc``). However, other patterns are accepted. In
263particular, "external-*" refers to external toolchains. One example is 273particular, "external-\*" refers to external toolchains. One example is
264the Sourcery G++ Toolchain. The support for this toolchain resides in 274the Sourcery G++ Toolchain. The support for this toolchain resides in
265the separate ``meta-sourcery`` layer at 275the separate ``meta-sourcery`` layer at
266http://github.com/MentorEmbedded/meta-sourcery/. 276http://github.com/MentorEmbedded/meta-sourcery/.
@@ -290,11 +300,13 @@ fail.
290 300
291As an example, you could add a specific server for the build system to 301As an example, you could add a specific server for the build system to
292attempt before any others by adding something like the following to the 302attempt before any others by adding something like the following to the
293``local.conf`` configuration file: PREMIRRORS_prepend = "\\ git://.*/.\* 303``local.conf`` configuration file: ::
294http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* 304
295http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* 305 PREMIRRORS_prepend = "\
296http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 306 git://.*/.* http://www.yoctoproject.org/sources/ \n \
297http://www.yoctoproject.org/sources/ \\n" 307 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
308 http://.*/.* http://www.yoctoproject.org/sources/ \n \
309 https://.*/.* http://www.yoctoproject.org/sources/ \n"
298 310
299These changes cause the build system to intercept Git, FTP, HTTP, and 311These changes cause the build system to intercept Git, FTP, HTTP, and
300HTTPS requests and direct them to the ``http://`` sources mirror. You 312HTTPS requests and direct them to the ``http://`` sources mirror. You
@@ -302,25 +314,43 @@ can use ``file://`` URLs to point to local directories or network shares
302as well. 314as well.
303 315
304Aside from the previous technique, these options also exist: 316Aside from the previous technique, these options also exist:
305BB_NO_NETWORK = "1" This statement tells BitBake to issue an error 317::
318
319 BB_NO_NETWORK = "1"
320
321This statement tells BitBake to issue an error
306instead of trying to access the Internet. This technique is useful if 322instead of trying to access the Internet. This technique is useful if
307you want to ensure code builds only from local sources. 323you want to ensure code builds only from local sources.
308 324
309Here is another technique: BB_FETCH_PREMIRRORONLY = "1" This statement 325Here is another technique:
326::
327
328 BB_FETCH_PREMIRRORONLY = "1"
329
330This statement
310limits the build system to pulling source from the ``PREMIRRORS`` only. 331limits the build system to pulling source from the ``PREMIRRORS`` only.
311Again, this technique is useful for reproducing builds. 332Again, this technique is useful for reproducing builds.
312 333
313Here is another technique: BB_GENERATE_MIRROR_TARBALLS = "1" This 334Here is another technique:
335::
336
337 BB_GENERATE_MIRROR_TARBALLS = "1"
338
339This
314statement tells the build system to generate mirror tarballs. This 340statement tells the build system to generate mirror tarballs. This
315technique is useful if you want to create a mirror server. If not, 341technique is useful if you want to create a mirror server. If not,
316however, the technique can simply waste time during the build. 342however, the technique can simply waste time during the build.
317 343
318Finally, consider an example where you are behind an HTTP-only firewall. 344Finally, consider an example where you are behind an HTTP-only firewall.
319You could make the following changes to the ``local.conf`` configuration 345You could make the following changes to the ``local.conf`` configuration
320file as long as the ``PREMIRRORS`` server is current: PREMIRRORS_prepend 346file as long as the ``PREMIRRORS`` server is current: ::
321= "\\ ftp://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ 347
322http://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 348 PREMIRRORS_prepend = "\
323http://www.yoctoproject.org/sources/ \\n" BB_FETCH_PREMIRRORONLY = "1" 349 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
350 http://.*/.* http://www.yoctoproject.org/sources/ \n \
351 https://.*/.* http://www.yoctoproject.org/sources/ \n"
352 BB_FETCH_PREMIRRORONLY = "1"
353
324These changes would cause the build system to successfully fetch source 354These changes would cause the build system to successfully fetch source
325over HTTP and any network accesses to anything other than the 355over HTTP and any network accesses to anything other than the
326``PREMIRRORS`` would fail. 356``PREMIRRORS`` would fail.
@@ -384,18 +414,21 @@ that program is never installed directly to the build machine's root
384file system. Consequently, the build system uses paths within the Build 414file system. Consequently, the build system uses paths within the Build
385Directory for ``DESTDIR``, ``bindir`` and related variables. To better 415Directory for ``DESTDIR``, ``bindir`` and related variables. To better
386understand this, consider the following two paths where the first is 416understand this, consider the following two paths where the first is
387relatively normal and the second is not: 417relatively normal and the second is not: ::
418
419 /home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/
420 1.2.8-r0/sysroot-destdir/usr/bin
421
422 /home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
423 zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
424 build/tmp/sysroots/x86_64-linux/usr/bin
388 425
389.. note:: 426.. note::
390 427
391 Due to these lengthy examples, the paths are artificially broken 428 Due to these lengthy examples, the paths are artificially broken
392 across lines for readability. 429 across lines for readability.
393 430
394/home/maxtothemax/poky-bootchart2/build/tmp/work/i586-poky-linux/zlib/ 431Even if the paths look unusual,
3951.2.8-r0/sysroot-destdir/usr/bin
396/home/maxtothemax/poky-bootchart2/build/tmp/work/x86_64-linux/
397zlib-native/1.2.8-r0/sysroot-destdir/home/maxtothemax/poky-bootchart2/
398build/tmp/sysroots/x86_64-linux/usr/bin Even if the paths look unusual,
399they both are correct - the first for a target and the second for a 432they both are correct - the first for a target and the second for a
400native recipe. These paths are a consequence of the ``DESTDIR`` 433native recipe. These paths are a consequence of the ``DESTDIR``
401mechanism and while they appear strange, they are correct and in 434mechanism and while they appear strange, they are correct and in
diff --git a/documentation/ref-manual/migration.rst b/documentation/ref-manual/migration.rst
index f834ba7004..d0d8f47932 100644
--- a/documentation/ref-manual/migration.rst
+++ b/documentation/ref-manual/migration.rst
@@ -15,7 +15,9 @@ Some considerations are not tied to a specific Yocto Project release.
15This section presents information you should consider when migrating to 15This section presents information you should consider when migrating to
16any new Yocto Project release. 16any new Yocto Project release.
17 17
18- *Dealing with Customized Recipes*: Issues could arise if you take 18- *Dealing with Customized Recipes*:
19
20 Issues could arise if you take
19 older recipes that contain customizations and simply copy them 21 older recipes that contain customizations and simply copy them
20 forward expecting them to work after you migrate to new Yocto Project 22 forward expecting them to work after you migrate to new Yocto Project
21 metadata. For example, suppose you have a recipe in your layer that 23 metadata. For example, suppose you have a recipe in your layer that
@@ -39,7 +41,9 @@ any new Yocto Project release.
39 use an append file. A good example of this is when introducing a 41 use an append file. A good example of this is when introducing a
40 newer or older version of a recipe in another layer. 42 newer or older version of a recipe in another layer.
41 43
42- *Updating Append Files*: Since append files generally only contain 44- *Updating Append Files*:
45
46 Since append files generally only contain
43 your customizations, they often do not need to be adjusted for new 47 your customizations, they often do not need to be adjusted for new
44 releases. However, if the ``.bbappend`` file is specific to a 48 releases. However, if the ``.bbappend`` file is specific to a
45 particular version of the recipe (i.e. its name does not use the % 49 particular version of the recipe (i.e. its name does not use the %
@@ -85,8 +89,9 @@ location (either local or remote) and then point to it in
85:term:`SSTATE_MIRRORS`, you need to append "PATH" 89:term:`SSTATE_MIRRORS`, you need to append "PATH"
86to the end of the mirror URL so that the path used by BitBake before the 90to the end of the mirror URL so that the path used by BitBake before the
87mirror substitution is appended to the path used to access the mirror. 91mirror substitution is appended to the path used to access the mirror.
88Here is an example: SSTATE_MIRRORS = "file://.\* 92Here is an example: ::
89http://someserver.tld/share/sstate/PATH" 93
94 SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
90 95
91.. _migration-1.3-bblayers-conf: 96.. _migration-1.3-bblayers-conf:
92 97
@@ -107,18 +112,6 @@ Recipes
107 112
108Differences include changes for the following: 113Differences include changes for the following:
109 114
110- Python function whitespace
111
112- ``proto=`` in ``SRC_URI``
113
114- ``nativesdk``
115
116- Task recipes
117
118- ``IMAGE_FEATURES``
119
120- Removed recipes
121
122.. _migration-1.3-python-function-whitespace: 115.. _migration-1.3-python-function-whitespace:
123 116
124Python Function Whitespace 117Python Function Whitespace
@@ -205,26 +198,26 @@ unlikely that you would have any references to them in your own
205:term:`Metadata`. However, you should check your metadata 198:term:`Metadata`. However, you should check your metadata
206against this list to be sure: 199against this list to be sure:
207 200
208- *``libx11-trim``*: Replaced by ``libx11``, which has a negligible 201- ``libx11-trim``: Replaced by ``libx11``, which has a negligible
209 size difference with modern Xorg. 202 size difference with modern Xorg.
210 203
211- *``xserver-xorg-lite``*: Use ``xserver-xorg``, which has a negligible 204- ``xserver-xorg-lite``: Use ``xserver-xorg``, which has a negligible
212 size difference when DRI and GLX modules are not installed. 205 size difference when DRI and GLX modules are not installed.
213 206
214- *``xserver-kdrive``*: Effectively unmaintained for many years. 207- ``xserver-kdrive``: Effectively unmaintained for many years.
215 208
216- *``mesa-xlib``*: No longer serves any purpose. 209- ``mesa-xlib``: No longer serves any purpose.
217 210
218- *``galago``*: Replaced by telepathy. 211- ``galago``: Replaced by telepathy.
219 212
220- *``gail``*: Functionality was integrated into GTK+ 2.13. 213- ``gail``: Functionality was integrated into GTK+ 2.13.
221 214
222- *``eggdbus``*: No longer needed. 215- ``eggdbus``: No longer needed.
223 216
224- *``gcc-*-intermediate``*: The build has been restructured to avoid 217- ``gcc-*-intermediate``: The build has been restructured to avoid
225 the need for this step. 218 the need for this step.
226 219
227- *``libgsmd``*: Unmaintained for many years. Functionality now 220- ``libgsmd``: Unmaintained for many years. Functionality now
228 provided by ``ofono`` instead. 221 provided by ``ofono`` instead.
229 222
230- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM 223- *contacts, dates, tasks, eds-tools*: Largely unmaintained PIM
@@ -238,8 +231,9 @@ recipes were not parsed in the default configuration. Many of these
238recipes are already provided in an updated and maintained form within 231recipes are already provided in an updated and maintained form within
239the OpenEmbedded community layers such as ``meta-oe`` and 232the OpenEmbedded community layers such as ``meta-oe`` and
240``meta-gnome``. For the remainder, you can now find them in the 233``meta-gnome``. For the remainder, you can now find them in the
241``meta-extras`` repository, which is in the Yocto Project `Source 234``meta-extras`` repository, which is in the
242Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__. 235:yocto_git:`Source Repositories <>` at
236http://git.yoctoproject.org/cgit/cgit.cgi/meta-extras/.
243 237
244.. _1.3-linux-kernel-naming: 238.. _1.3-linux-kernel-naming:
245 239
@@ -248,13 +242,15 @@ Linux Kernel Naming
248 242
249The naming scheme for kernel output binaries has been changed to now 243The naming scheme for kernel output binaries has been changed to now
250include :term:`PE` as part of the filename: 244include :term:`PE` as part of the filename:
251KERNEL_IMAGE_BASE_NAME ?= 245::
252"${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}" 246
247 KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
253 248
254Because the ``PE`` variable is not set by default, these binary files 249Because the ``PE`` variable is not set by default, these binary files
255could result with names that include two dash characters. Here is an 250could result with names that include two dash characters. Here is an
256example: 251example: ::
257bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin 252
253 bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
258 254
259Moving to the Yocto Project 1.4 Release 255Moving to the Yocto Project 1.4 Release
260======================================= 256=======================================
@@ -298,8 +294,12 @@ Differences include the following:
298 294
299- *Shared State Code:* The shared state code has been optimized to 295- *Shared State Code:* The shared state code has been optimized to
300 avoid running unnecessary tasks. For example, the following no longer 296 avoid running unnecessary tasks. For example, the following no longer
301 populates the target sysroot since that is not necessary: $ bitbake 297 populates the target sysroot since that is not necessary:
302 -c rootfs some-image Instead, the system just needs to extract the 298 ::
299
300 $ bitbake -c rootfs some-image
301
302 Instead, the system just needs to extract the
303 output package contents, re-create the packages, and construct the 303 output package contents, re-create the packages, and construct the
304 root filesystem. This change is unlikely to cause any problems unless 304 root filesystem. This change is unlikely to cause any problems unless
305 you have missing declared dependencies. 305 you have missing declared dependencies.
@@ -337,9 +337,9 @@ creating an append file for the ``netbase`` recipe, you now need to
337create an append file for the ``init-ifupdown`` recipe instead, which 337create an append file for the ``init-ifupdown`` recipe instead, which
338you can find in the :term:`Source Directory` at 338you can find in the :term:`Source Directory` at
339``meta/recipes-core/init-ifupdown``. For information on how to use 339``meta/recipes-core/init-ifupdown``. For information on how to use
340append files, see the "`Using .bbappend 340append files, see the
341Files <&YOCTO_DOCS_DEV_URL;#using-bbappend-files>`__" section in the 341":ref:`dev-manual/dev-manual-common-tasks:using .bbappend files in your layer`"
342Yocto Project Development Tasks Manual. 342section in the Yocto Project Development Tasks Manual.
343 343
344.. _migration-1.4-remote-debugging: 344.. _migration-1.4-remote-debugging:
345 345
@@ -360,7 +360,7 @@ Variables
360 360
361The following variables have changed: 361The following variables have changed:
362 362
363- *``SANITY_TESTED_DISTROS``:* This variable now uses a distribution 363- ``SANITY_TESTED_DISTROS``: This variable now uses a distribution
364 ID, which is composed of the host distributor ID followed by the 364 ID, which is composed of the host distributor ID followed by the
365 release. Previously, 365 release. Previously,
366 :term:`SANITY_TESTED_DISTROS` was 366 :term:`SANITY_TESTED_DISTROS` was
@@ -369,7 +369,7 @@ The following variables have changed:
369 you are not specifically setting this variable, or if you are 369 you are not specifically setting this variable, or if you are
370 specifically setting it to "". 370 specifically setting it to "".
371 371
372- *``SRC_URI``:* The ``${``\ :term:`PN`\ ``}``, 372- ``SRC_URI``: The ``${``\ :term:`PN`\ ``}``,
373 ``${``\ :term:`PF`\ ``}``, 373 ``${``\ :term:`PF`\ ``}``,
374 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories 374 ``${``\ :term:`P`\ ``}``, and ``FILE_DIRNAME`` directories
375 have been dropped from the default value of the 375 have been dropped from the default value of the
@@ -390,7 +390,10 @@ Target Package Management with RPM
390If runtime package management is enabled and the RPM backend is 390If runtime package management is enabled and the RPM backend is
391selected, Smart is now installed for package download, dependency 391selected, Smart is now installed for package download, dependency
392resolution, and upgrades instead of Zypper. For more information on how 392resolution, and upgrades instead of Zypper. For more information on how
393to use Smart, run the following command on the target: smart --help 393to use Smart, run the following command on the target:
394::
395
396 smart --help
394 397
395.. _migration-1.4-recipes-moved: 398.. _migration-1.4-recipes-moved:
396 399
@@ -400,29 +403,29 @@ Recipes Moved
400The following recipes were moved from their previous locations because 403The following recipes were moved from their previous locations because
401they are no longer used by anything in the OpenEmbedded-Core: 404they are no longer used by anything in the OpenEmbedded-Core:
402 405
403- *``clutter-box2d``:* Now resides in the ``meta-oe`` layer. 406- ``clutter-box2d``: Now resides in the ``meta-oe`` layer.
404 407
405- *``evolution-data-server``:* Now resides in the ``meta-gnome`` layer. 408- ``evolution-data-server``: Now resides in the ``meta-gnome`` layer.
406 409
407- *``gthumb``:* Now resides in the ``meta-gnome`` layer. 410- ``gthumb``: Now resides in the ``meta-gnome`` layer.
408 411
409- *``gtkhtml2``:* Now resides in the ``meta-oe`` layer. 412- ``gtkhtml2``: Now resides in the ``meta-oe`` layer.
410 413
411- *``gupnp``:* Now resides in the ``meta-multimedia`` layer. 414- ``gupnp``: Now resides in the ``meta-multimedia`` layer.
412 415
413- *``gypsy``:* Now resides in the ``meta-oe`` layer. 416- ``gypsy``: Now resides in the ``meta-oe`` layer.
414 417
415- *``libcanberra``:* Now resides in the ``meta-gnome`` layer. 418- ``libcanberra``: Now resides in the ``meta-gnome`` layer.
416 419
417- *``libgdata``:* Now resides in the ``meta-gnome`` layer. 420- ``libgdata``: Now resides in the ``meta-gnome`` layer.
418 421
419- *``libmusicbrainz``:* Now resides in the ``meta-multimedia`` layer. 422- ``libmusicbrainz``: Now resides in the ``meta-multimedia`` layer.
420 423
421- *``metacity``:* Now resides in the ``meta-gnome`` layer. 424- ``metacity``: Now resides in the ``meta-gnome`` layer.
422 425
423- *``polkit``:* Now resides in the ``meta-oe`` layer. 426- ``polkit``: Now resides in the ``meta-oe`` layer.
424 427
425- *``zeroconf``:* Now resides in the ``meta-networking`` layer. 428- ``zeroconf``: Now resides in the ``meta-networking`` layer.
426 429
427.. _migration-1.4-removals-and-renames: 430.. _migration-1.4-removals-and-renames:
428 431
@@ -431,58 +434,58 @@ Removals and Renames
431 434
432The following list shows what has been removed or renamed: 435The following list shows what has been removed or renamed:
433 436
434- *``evieext``:* Removed because it has been removed from ``xserver`` 437- ``evieext``: Removed because it has been removed from ``xserver``
435 since 2008. 438 since 2008.
436 439
437- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer 440- *Gtk+ DirectFB:* Removed support because upstream Gtk+ no longer
438 supports it as of version 2.18. 441 supports it as of version 2.18.
439 442
440- *``libxfontcache / xfontcacheproto``:* Removed because they were 443- ``libxfontcache / xfontcacheproto``: Removed because they were
441 removed from the Xorg server in 2008. 444 removed from the Xorg server in 2008.
442 445
443- *``libxp / libxprintapputil / libxprintutil / printproto``:* Removed 446- ``libxp / libxprintapputil / libxprintutil / printproto``: Removed
444 because the XPrint server was removed from Xorg in 2008. 447 because the XPrint server was removed from Xorg in 2008.
445 448
446- *``libxtrap / xtrapproto``:* Removed because their functionality was 449- ``libxtrap / xtrapproto``: Removed because their functionality was
447 broken upstream. 450 broken upstream.
448 451
449- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being 452- *linux-yocto 3.0 kernel:* Removed with linux-yocto 3.8 kernel being
450 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part 453 added. The linux-yocto 3.2 and linux-yocto 3.4 kernels remain as part
451 of the release. 454 of the release.
452 455
453- *``lsbsetup``:* Removed with functionality now provided by 456- ``lsbsetup``: Removed with functionality now provided by
454 ``lsbtest``. 457 ``lsbtest``.
455 458
456- *``matchbox-stroke``:* Removed because it was never more than a 459- ``matchbox-stroke``: Removed because it was never more than a
457 proof-of-concept. 460 proof-of-concept.
458 461
459- *``matchbox-wm-2 / matchbox-theme-sato-2``:* Removed because they are 462- ``matchbox-wm-2 / matchbox-theme-sato-2``: Removed because they are
460 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato`` 463 not maintained. However, ``matchbox-wm`` and ``matchbox-theme-sato``
461 are still provided. 464 are still provided.
462 465
463- *``mesa-dri``:* Renamed to ``mesa``. 466- ``mesa-dri``: Renamed to ``mesa``.
464 467
465- *``mesa-xlib``:* Removed because it was no longer useful. 468- ``mesa-xlib``: Removed because it was no longer useful.
466 469
467- *``mutter``:* Removed because nothing ever uses it and the recipe is 470- ``mutter``: Removed because nothing ever uses it and the recipe is
468 very old. 471 very old.
469 472
470- *``orinoco-conf``:* Removed because it has become obsolete. 473- ``orinoco-conf``: Removed because it has become obsolete.
471 474
472- *``update-modules``:* Removed because it is no longer used. The 475- ``update-modules``: Removed because it is no longer used. The
473 kernel module ``postinstall`` and ``postrm`` scripts can now do the 476 kernel module ``postinstall`` and ``postrm`` scripts can now do the
474 same task without the use of this script. 477 same task without the use of this script.
475 478
476- *``web``:* Removed because it is not maintained. Superseded by 479- ``web``: Removed because it is not maintained. Superseded by
477 ``web-webkit``. 480 ``web-webkit``.
478 481
479- *``xf86bigfontproto``:* Removed because upstream it has been disabled 482- ``xf86bigfontproto``: Removed because upstream it has been disabled
480 by default since 2007. Nothing uses ``xf86bigfontproto``. 483 by default since 2007. Nothing uses ``xf86bigfontproto``.
481 484
482- *``xf86rushproto``:* Removed because its dependency in ``xserver`` 485- ``xf86rushproto``: Removed because its dependency in ``xserver``
483 was spurious and it was removed in 2005. 486 was spurious and it was removed in 2005.
484 487
485- *``zypper / libzypp / sat-solver``:* Removed and been functionally 488- ``zypper / libzypp / sat-solver``: Removed and been functionally
486 replaced with Smart (``python-smartpm``) when RPM packaging is used 489 replaced with Smart (``python-smartpm``) when RPM packaging is used
487 and package management is enabled on the target. 490 and package management is enabled on the target.
488 491
@@ -735,8 +738,7 @@ A new automated image testing framework has been added through the
735framework replaces the older ``imagetest-qemu`` framework. 738framework replaces the older ``imagetest-qemu`` framework.
736 739
737You can learn more about performing automated image tests in the 740You can learn more about performing automated image tests in the
738"`Performing Automated Runtime 741":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
739Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
740section in the Yocto Project Development Tasks Manual. 742section in the Yocto Project Development Tasks Manual.
741 743
742.. _migration-1.5-build-history: 744.. _migration-1.5-build-history:
@@ -758,9 +760,8 @@ Following are changes to Build History:
758 utilities have improved command-line handling. Use the ``--help`` 760 utilities have improved command-line handling. Use the ``--help``
759 option for each utility for more information on the new syntax. 761 option for each utility for more information on the new syntax.
760 762
761For more information on Build History, see the "`Maintaining Build 763For more information on Build History, see the
762Output 764":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
763Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
764section in the Yocto Project Development Tasks Manual. 765section in the Yocto Project Development Tasks Manual.
765 766
766.. _migration-1.5-udev: 767.. _migration-1.5-udev:
@@ -836,7 +837,7 @@ Following is a list of short entries describing other changes:
836 837
837- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict 838- ``image.bbclass``: Move ``runtime_mapping_rename`` to avoid conflict
838 with ``multilib``. See 839 with ``multilib``. See
839 ```YOCTO #4993`https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993 840 `YOCTO #4993 <https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993>`_
840 in Bugzilla for more information. 841 in Bugzilla for more information.
841 842
842- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files. 843- ``linux-dtb``: Use kernel build system to generate the ``dtb`` files.
@@ -856,9 +857,8 @@ Project 1.6 Release from the prior release.
856 857
857The :ref:`archiver <ref-classes-archiver>` class has been rewritten 858The :ref:`archiver <ref-classes-archiver>` class has been rewritten
858and its configuration has been simplified. For more details on the 859and its configuration has been simplified. For more details on the
859source archiver, see the "`Maintaining Open Source License Compliance 860source archiver, see the
860During Your Product's 861":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
861Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
862section in the Yocto Project Development Tasks Manual. 862section in the Yocto Project Development Tasks Manual.
863 863
864.. _migration-1.6-packaging-changes: 864.. _migration-1.6-packaging-changes:
@@ -992,9 +992,8 @@ NFS mount, an error occurs.
992The ``PRINC`` variable has been deprecated and triggers a warning if 992The ``PRINC`` variable has been deprecated and triggers a warning if
993detected during a build. For :term:`PR` increments on changes, 993detected during a build. For :term:`PR` increments on changes,
994use the PR service instead. You can find out more about this service in 994use the PR service instead. You can find out more about this service in
995the "`Working With a PR 995the ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`"
996Service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__" section in 996section in the Yocto Project Development Tasks Manual.
997the Yocto Project Development Tasks Manual.
998 997
999.. _migration-1.6-variable-changes-IMAGE_TYPES: 998.. _migration-1.6-variable-changes-IMAGE_TYPES:
1000 999
@@ -1039,19 +1038,25 @@ Preprocess and Post Process Command Variable Behavior
1039 1038
1040The following variables now expect a semicolon separated list of 1039The following variables now expect a semicolon separated list of
1041functions to call and not arbitrary shell commands: 1040functions to call and not arbitrary shell commands:
1042:term:`ROOTFS_PREPROCESS_COMMAND` 1041
1043:term:`ROOTFS_POSTPROCESS_COMMAND` 1042 - :term:`ROOTFS_PREPROCESS_COMMAND`
1044:term:`SDK_POSTPROCESS_COMMAND` 1043 - :term:`ROOTFS_POSTPROCESS_COMMAND`
1045:term:`POPULATE_SDK_POST_TARGET_COMMAND` 1044 - :term:`SDK_POSTPROCESS_COMMAND`
1046:term:`POPULATE_SDK_POST_HOST_COMMAND` 1045 - :term:`POPULATE_SDK_POST_TARGET_COMMAND`
1047:term:`IMAGE_POSTPROCESS_COMMAND` 1046 - :term:`POPULATE_SDK_POST_HOST_COMMAND`
1048:term:`IMAGE_PREPROCESS_COMMAND` 1047 - :term:`IMAGE_POSTPROCESS_COMMAND`
1049:term:`ROOTFS_POSTUNINSTALL_COMMAND` 1048 - :term:`IMAGE_PREPROCESS_COMMAND`
1050:term:`ROOTFS_POSTINSTALL_COMMAND` For 1049 - :term:`ROOTFS_POSTUNINSTALL_COMMAND`
1050 - :term:`ROOTFS_POSTINSTALL_COMMAND`
1051
1052For
1051migration purposes, you can simply wrap shell commands in a shell 1053migration purposes, you can simply wrap shell commands in a shell
1052function and then call the function. Here is an example: 1054function and then call the function. Here is an example: ::
1053my_postprocess_function() { echo "hello" > ${IMAGE_ROOTFS}/hello.txt } 1055
1054ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; " 1056 my_postprocess_function() {
1057 echo "hello" > ${IMAGE_ROOTFS}/hello.txt
1058 }
1059 ROOTFS_POSTPROCESS_COMMAND += "my_postprocess_function; "
1055 1060
1056.. _migration-1.6-package-test-ptest: 1061.. _migration-1.6-package-test-ptest:
1057 1062
@@ -1059,9 +1064,9 @@ Package Test (ptest)
1059-------------------- 1064--------------------
1060 1065
1061Package Tests (ptest) are built but not installed by default. For 1066Package Tests (ptest) are built but not installed by default. For
1062information on using Package Tests, see the "`Testing Packages with 1067information on using Package Tests, see the
1063ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in 1068":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
1064the Yocto Project Development Tasks Manual. For information on the 1069section in the Yocto Project Development Tasks Manual. For information on the
1065``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`" 1070``ptest`` class, see the ":ref:`ptest.bbclass <ref-classes-ptest>`"
1066section. 1071section.
1067 1072
@@ -1087,8 +1092,11 @@ the ``autotools`` or ``autotools_stage``\ classes.
1087 1092
1088``qemu-native`` now builds without SDL-based graphical output support by 1093``qemu-native`` now builds without SDL-based graphical output support by
1089default. The following additional lines are needed in your 1094default. The following additional lines are needed in your
1090``local.conf`` to enable it: PACKAGECONFIG_pn-qemu-native = "sdl" 1095``local.conf`` to enable it:
1091ASSUME_PROVIDED += "libsdl-native" 1096::
1097
1098 PACKAGECONFIG_pn-qemu-native = "sdl"
1099 ASSUME_PROVIDED += "libsdl-native"
1092 1100
1093.. note:: 1101.. note::
1094 1102
@@ -1270,15 +1278,18 @@ means that existing ``local.conf`` files will need to be be modified to
1270append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu`` 1278append to ``PACKAGECONFIG`` for ``qemu-native`` and ``nativesdk-qemu``
1271instead of setting it. In other words, to enable graphical output for 1279instead of setting it. In other words, to enable graphical output for
1272QEMU, you should now have these lines in ``local.conf``: 1280QEMU, you should now have these lines in ``local.conf``:
1273PACKAGECONFIG_append_pn-qemu-native = " sdl" 1281::
1274PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl" 1282
1283 PACKAGECONFIG_append_pn-qemu-native = " sdl"
1284 PACKAGECONFIG_append_pn-nativesdk-qemu = " sdl"
1275 1285
1276.. _migration-1.7-minimum-git-version: 1286.. _migration-1.7-minimum-git-version:
1277 1287
1278Minimum Git version 1288Minimum Git version
1279------------------- 1289-------------------
1280 1290
1281The minimum `Git <&YOCTO_DOCS_OM_URL;#git>`__ version required on the 1291The minimum :ref:`overview-manual/overview-manual-development-environment:git`
1292version required on the
1282build host is now 1.7.8 because the ``--list`` option is now required by 1293build host is now 1.7.8 because the ``--list`` option is now required by
1283BitBake's Git fetcher. As always, if your host distribution does not 1294BitBake's Git fetcher. As always, if your host distribution does not
1284provide a version of Git that meets this requirement, you can use the 1295provide a version of Git that meets this requirement, you can use the
@@ -1308,8 +1319,8 @@ occurred:
1308 the :ref:`autotools-brokensep <ref-classes-autotools>` class 1319 the :ref:`autotools-brokensep <ref-classes-autotools>` class
1309 instead of the ``autotools`` or ``autotools_stage`` classes. 1320 instead of the ``autotools`` or ``autotools_stage`` classes.
1310 1321
1311- *The ``--foreign`` option is no longer passed to ``automake`` when 1322- The ``--foreign`` option is no longer passed to ``automake`` when
1312 running ``autoconf``:* This option tells ``automake`` that a 1323 running ``autoconf``: This option tells ``automake`` that a
1313 particular software package does not follow the GNU standards and 1324 particular software package does not follow the GNU standards and
1314 therefore should not be expected to distribute certain files such as 1325 therefore should not be expected to distribute certain files such as
1315 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of 1326 ``ChangeLog``, ``AUTHORS``, and so forth. Because the majority of
@@ -1331,15 +1342,31 @@ disable the scripts due to the scripts previously requiring error-prone
1331path substitution. Software that links against these libraries using 1342path substitution. Software that links against these libraries using
1332these scripts should use the much more robust ``pkg-config`` instead. 1343these scripts should use the much more robust ``pkg-config`` instead.
1333The list of recipes changed in this version (and their configuration 1344The list of recipes changed in this version (and their configuration
1334scripts) is as follows: directfb (directfb-config) freetype 1345scripts) is as follows:
1335(freetype-config) gpgme (gpgme-config) libassuan (libassuan-config) 1346::
1336libcroco (croco-6.0-config) libgcrypt (libgcrypt-config) libgpg-error 1347
1337(gpg-error-config) libksba (ksba-config) libpcap (pcap-config) libpcre 1348 directfb (directfb-config)
1338(pcre-config) libpng (libpng-config, libpng16-config) libsdl 1349 freetype (freetype-config)
1339(sdl-config) libusb-compat (libusb-config) libxml2 (xml2-config) libxslt 1350 gpgme (gpgme-config)
1340(xslt-config) ncurses (ncurses-config) neon (neon-config) npth 1351 libassuan (libassuan-config)
1341(npth-config) pth (pth-config) taglib (taglib-config) Additionally, 1352 libcroco (croco-6.0-config)
1342support for ``pkg-config`` has been added to some recipes in the 1353 libgcrypt (libgcrypt-config)
1354 libgpg-error (gpg-error-config)
1355 libksba (ksba-config)
1356 libpcap (pcap-config)
1357 libpcre (pcre-config)
1358 libpng (libpng-config, libpng16-config)
1359 libsdl (sdl-config)
1360 libusb-compat (libusb-config)
1361 libxml2 (xml2-config)
1362 libxslt (xslt-config)
1363 ncurses (ncurses-config)
1364 neon (neon-config)
1365 npth (npth-config)
1366 pth (pth-config)
1367 taglib (taglib-config)
1368
1369Additionally, support for ``pkg-config`` has been added to some recipes in the
1343previous list in the rare cases where the upstream software package does 1370previous list in the rare cases where the upstream software package does
1344not already provide it. 1371not already provide it.
1345 1372
@@ -1453,8 +1480,8 @@ The following miscellaneous change occurred:
1453 build header as printed by BitBake upon starting the build. You 1480 build header as printed by BitBake upon starting the build. You
1454 should manually remove old "build-id" files from your existing build 1481 should manually remove old "build-id" files from your existing build
1455 history repositories to avoid confusion. For information on the build 1482 history repositories to avoid confusion. For information on the build
1456 history feature, see the "`Maintaining Build Output 1483 history feature, see the
1457 Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__" 1484 ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
1458 section in the Yocto Project Development Tasks Manual. 1485 section in the Yocto Project Development Tasks Manual.
1459 1486
1460Moving to the Yocto Project 1.8 Release 1487Moving to the Yocto Project 1.8 Release
@@ -1515,11 +1542,12 @@ you can now remove them.
1515Additionally, a ``bluetooth`` class has been added to make selection of 1542Additionally, a ``bluetooth`` class has been added to make selection of
1516the appropriate bluetooth support within a recipe a little easier. If 1543the appropriate bluetooth support within a recipe a little easier. If
1517you wish to make use of this class in a recipe, add something such as 1544you wish to make use of this class in a recipe, add something such as
1518the following: inherit bluetooth PACKAGECONFIG ??= 1545the following: ::
1519"${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', 1546
1520d)}" PACKAGECONFIG[bluez4] = 1547 inherit bluetooth
1521"--enable-bluetooth,--disable-bluetooth,bluez4" PACKAGECONFIG[bluez5] = 1548 PACKAGECONFIG ??= "${@bb.utils.contains('DISTRO_FEATURES', 'bluetooth', '${BLUEZ}', '', d)}"
1522"--enable-bluez5,--disable-bluez5,bluez5" 1549 PACKAGECONFIG[bluez4] = "--enable-bluetooth,--disable-bluetooth,bluez4"
1550 PACKAGECONFIG[bluez5] = "--enable-bluez5,--disable-bluez5,bluez5"
1523 1551
1524.. _migration-1.8-kernel-build-changes: 1552.. _migration-1.8-kernel-build-changes:
1525 1553
@@ -1542,8 +1570,9 @@ where the ``linux.inc`` file in ``meta-oe`` was updated.
1542 1570
1543Recipes that rely on the kernel source code and do not inherit the 1571Recipes that rely on the kernel source code and do not inherit the
1544module classes might need to add explicit dependencies on the 1572module classes might need to add explicit dependencies on the
1545``do_shared_workdir`` kernel task, for example: do_configure[depends] += 1573``do_shared_workdir`` kernel task, for example: ::
1546"virtual/kernel:do_shared_workdir" 1574
1575 do_configure[depends] += "virtual/kernel:do_shared_workdir"
1547 1576
1548.. _migration-1.8-ssl: 1577.. _migration-1.8-ssl:
1549 1578
@@ -1588,8 +1617,9 @@ One of the improvements is to attempt to run "make clean" during the
1588``do_configure`` task if a ``Makefile`` exists. Some software packages 1617``do_configure`` task if a ``Makefile`` exists. Some software packages
1589do not provide a working clean target within their make files. If you 1618do not provide a working clean target within their make files. If you
1590have such recipes, you need to set 1619have such recipes, you need to set
1591:term:`CLEANBROKEN` to "1" within the recipe, for 1620:term:`CLEANBROKEN` to "1" within the recipe, for example: ::
1592example: CLEANBROKEN = "1" 1621
1622 CLEANBROKEN = "1"
1593 1623
1594.. _migration-1.8-qa-check-and-validation-changes: 1624.. _migration-1.8-qa-check-and-validation-changes:
1595 1625
@@ -1663,7 +1693,10 @@ and the porting guide at
1663https://gcc.gnu.org/gcc-5/porting_to.html. 1693https://gcc.gnu.org/gcc-5/porting_to.html.
1664 1694
1665Alternatively, you can switch back to GCC 4.9 or 4.8 by setting 1695Alternatively, you can switch back to GCC 4.9 or 4.8 by setting
1666``GCCVERSION`` in your configuration, as follows: GCCVERSION = "4.9%" 1696``GCCVERSION`` in your configuration, as follows:
1697::
1698
1699 GCCVERSION = "4.9%"
1667 1700
1668.. _migration-2.0-Gstreamer-0.10-removed: 1701.. _migration-2.0-Gstreamer-0.10-removed:
1669 1702
@@ -1726,7 +1759,10 @@ unlikely to require any changes to Metadata. However, these minor
1726changes in behavior exist: 1759changes in behavior exist:
1727 1760
1728- All potential overrides are now visible in the variable history as 1761- All potential overrides are now visible in the variable history as
1729 seen when you run the following: $ bitbake -e 1762 seen when you run the following:
1763 ::
1764
1765 $ bitbake -e
1730 1766
1731- ``d.delVar('``\ VARNAME\ ``')`` and 1767- ``d.delVar('``\ VARNAME\ ``')`` and
1732 ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all 1768 ``d.setVar('``\ VARNAME\ ``', None)`` result in the variable and all
@@ -1833,7 +1869,9 @@ changes.
1833Additionally, work directories for old versions of recipes are now 1869Additionally, work directories for old versions of recipes are now
1834pruned. If you wish to disable pruning old work directories, you can set 1870pruned. If you wish to disable pruning old work directories, you can set
1835the following variable in your configuration: 1871the following variable in your configuration:
1836SSTATE_PRUNE_OBSOLETEWORKDIR = "0" 1872::
1873
1874 SSTATE_PRUNE_OBSOLETEWORKDIR = "0"
1837 1875
1838.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source: 1876.. _migration-2.0-linux-yocto-kernel-metadata-repository-now-split-from-source:
1839 1877
@@ -1952,9 +1990,11 @@ defaulted to False if not specified. Now, however, no default exists so
1952one must be specified. You must change any ``getVar()`` calls that do 1990one must be specified. You must change any ``getVar()`` calls that do
1953not specify the final expand parameter to calls that do specify the 1991not specify the final expand parameter to calls that do specify the
1954parameter. You can run the following ``sed`` command at the base of a 1992parameter. You can run the following ``sed`` command at the base of a
1955layer to make this change: sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' 1993layer to make this change:
1956-i \`grep -ril getVar \*\` sed -e 's:\(\.getVarFlag([^,()]*, 1994::
1957[^,()]*\)):\1, False):g' -i \`grep -ril getVarFlag \*\` 1995
1996 sed -e 's:\(\.getVar([^,()]*\)):\1, False):g' -i `grep -ril getVar *`
1997 sed -e 's:\(\.getVarFlag([^,()]*,[^,()]*\)):\1, False):g' -i `grep -ril getVarFlag *`
1958 1998
1959.. note:: 1999.. note::
1960 2000
@@ -2124,8 +2164,8 @@ The following changes have been made to the build system user interface:
2124 2164
2125- *Hob GTK+-based UI*: Removed because it is unmaintained and based on 2165- *Hob GTK+-based UI*: Removed because it is unmaintained and based on
2126 the outdated GTK+ 2 library. The Toaster web-based UI is much more 2166 the outdated GTK+ 2 library. The Toaster web-based UI is much more
2127 capable and is actively maintained. See the "`Using the Toaster Web 2167 capable and is actively maintained. See the
2128 Interface <&YOCTO_DOCS_TOAST_URL;#using-the-toaster-web-interface>`__" 2168 ":ref:`toaster-manual/toaster-manual-setup-and-use:using the toaster web interface`"
2129 section in the Toaster User Manual for more information on this 2169 section in the Toaster User Manual for more information on this
2130 interface. 2170 interface.
2131 2171
@@ -2138,12 +2178,11 @@ ADT Removed
2138----------- 2178-----------
2139 2179
2140The Application Development Toolkit (ADT) has been removed because its 2180The Application Development Toolkit (ADT) has been removed because its
2141functionality almost completely overlapped with the `standard 2181functionality almost completely overlapped with the :ref:`standard
2142SDK <&YOCTO_DOCS_SDK_URL;#sdk-using-the-standard-sdk>`__ and the 2182SDK <sdk-manual/sdk-using:using the standard sdk>` and the
2143`extensible SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__. For 2183:ref:`extensible SDK <sdk-manual/sdk-extensible:using the extensible sdk>`. For
2144information on these SDKs and how to build and use them, see the `Yocto 2184information on these SDKs and how to build and use them, see the
2145Project Application Development and the Extensible Software Development 2185:doc:`../sdk-manual/sdk-manual` manual.
2146Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
2147 2186
2148.. note:: 2187.. note::
2149 2188
@@ -2253,8 +2292,7 @@ This release supports generation of GLib Introspective Repository (GIR)
2253files through GObject introspection, which is the standard mechanism for 2292files through GObject introspection, which is the standard mechanism for
2254accessing GObject-based software from runtime environments. You can 2293accessing GObject-based software from runtime environments. You can
2255enable, disable, and test the generation of this data. See the 2294enable, disable, and test the generation of this data. See the
2256"`Enabling GObject Introspection 2295":ref:`dev-manual/dev-manual-common-tasks:enabling gobject introspection support`"
2257Support <&YOCTO_DOCS_DEV_URL;#enabling-gobject-introspection-support>`__"
2258section in the Yocto Project Development Tasks Manual for more 2296section in the Yocto Project Development Tasks Manual for more
2259information. 2297information.
2260 2298
@@ -2279,7 +2317,14 @@ These additional changes exist:
2279- Previously, the following list of packages were removed if 2317- Previously, the following list of packages were removed if
2280 package-management was not in 2318 package-management was not in
2281 :term:`IMAGE_FEATURES`, regardless of any 2319 :term:`IMAGE_FEATURES`, regardless of any
2282 dependencies: update-rc.d base-passwd shadow update-alternatives 2320 dependencies:
2321 ::
2322
2323 update-rc.d
2324 base-passwd
2325 shadow
2326 update-alternatives
2327
2283 run-postinsts With the Yocto Project 2.1 release, these packages are 2328 run-postinsts With the Yocto Project 2.1 release, these packages are
2284 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since 2329 only removed if "read-only-rootfs" is in ``IMAGE_FEATURES``, since
2285 they might still be needed for a read-write image even in the absence 2330 they might still be needed for a read-write image even in the absence
@@ -2287,7 +2332,7 @@ These additional changes exist:
2287 removed at runtime). 2332 removed at runtime).
2288 2333
2289- The 2334- The
2290 ```devtool modify`` <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-modify-to-modify-the-source-of-an-existing-component>`__ 2335 :ref:`devtool modify <sdk-manual/sdk-extensible:use \`\`devtool modify\`\` to modify the source of an existing component>`
2291 command now defaults to extracting the source since that is most 2336 command now defaults to extracting the source since that is most
2292 commonly expected. The "-x" or "--extract" options are now no-ops. If 2337 commonly expected. The "-x" or "--extract" options are now no-ops. If
2293 you wish to provide your own existing source tree, you will now need 2338 you wish to provide your own existing source tree, you will now need
@@ -2409,10 +2454,15 @@ The metadata is now required to use Python 3 syntax. For help preparing
2409metadata, see any of the many Python 3 porting guides available. 2454metadata, see any of the many Python 3 porting guides available.
2410Alternatively, you can reference the conversion commits for Bitbake and 2455Alternatively, you can reference the conversion commits for Bitbake and
2411you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are 2456you can use :term:`OpenEmbedded-Core (OE-Core)` as a guide for changes. Following are
2412particular areas of interest: \* subprocess command-line pipes needing 2457particular areas of interest:
2413locale decoding \* the syntax for octal values changed \* the 2458
2414``iter*()`` functions changed name \* iterators now return views, not 2459 - subprocess command-line pipes needing locale decoding
2415lists \* changed names for Python modules 2460
2461 - the syntax for octal values changed
2462
2463 - the ``iter*()`` functions changed name \* iterators now return views, not lists
2464
2465 - changed names for Python modules
2416 2466
2417.. _migration-2.2-target-python-recipes-switched-to-python-3: 2467.. _migration-2.2-target-python-recipes-switched-to-python-3:
2418 2468
@@ -2474,7 +2524,12 @@ The new ``runqemu`` is a Python script. Machine knowledge is no longer
2474hardcoded into ``runqemu``. You can choose to use the ``qemuboot`` 2524hardcoded into ``runqemu``. You can choose to use the ``qemuboot``
2475configuration file to define the BSP's own arguments and to make it 2525configuration file to define the BSP's own arguments and to make it
2476bootable with ``runqemu``. If you use a configuration file, use the 2526bootable with ``runqemu``. If you use a configuration file, use the
2477following form: image-name-machine.qemuboot.conf The configuration file 2527following form:
2528::
2529
2530 image-name-machine.qemuboot.conf
2531
2532The configuration file
2478enables fine-grained tuning of options passed to QEMU without the 2533enables fine-grained tuning of options passed to QEMU without the
2479``runqemu`` script hard-coding any knowledge about different machines. 2534``runqemu`` script hard-coding any knowledge about different machines.
2480Using a configuration file is particularly convenient when trying to use 2535Using a configuration file is particularly convenient when trying to use
@@ -2485,14 +2540,28 @@ rootfs). QEMU boot arguments can be set in BSP's configuration file and
2485the ``qemuboot`` class will save them to ``qemuboot.conf``. 2540the ``qemuboot`` class will save them to ``qemuboot.conf``.
2486 2541
2487If you want to use ``runqemu`` without a configuration file, use the 2542If you want to use ``runqemu`` without a configuration file, use the
2488following command form: $ runqemu machine rootfs kernel [options] 2543following command form:
2489Supported machines are as follows: qemuarm qemuarm64 qemux86 qemux86-64 2544::
2490qemuppc qemumips qemumips64 qemumipsel qemumips64el Consider the 2545
2546 $ runqemu machine rootfs kernel [options]
2547
2548Supported machines are as follows:
2549
2550 - qemuarm
2551 - qemuarm64
2552 - qemux86
2553 - qemux86-64
2554 - qemuppc
2555 - qemumips
2556 - qemumips64
2557 - qemumipsel
2558 - qemumips64el
2559
2560Consider the
2491following example, which uses the ``qemux86-64`` machine, provides a 2561following example, which uses the ``qemux86-64`` machine, provides a
2492root filesystem, provides an image, and uses the ``nographic`` option: $ 2562root filesystem, provides an image, and uses the ``nographic`` option: ::
2493runqemu qemux86-64 2563
2494tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 2564 $ runqemu qemux86-64 tmp/deploy/images/qemux86-64/core-image-minimal-qemux86-64.ext4 tmp/deploy/images/qemux86-64/bzImage nographic
2495tmp/deploy/images/qemux86-64/bzImage nographic
2496 2565
2497Following is a list of variables that can be set in configuration files 2566Following is a list of variables that can be set in configuration files
2498such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``: 2567such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
@@ -2501,31 +2570,35 @@ such as ``bsp.conf`` to enable the BSP to be booted by ``runqemu``:
2501 2570
2502 "QB" means "QEMU Boot". 2571 "QB" means "QEMU Boot".
2503 2572
2504QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386") QB_OPT_APPEND: 2573::
2505Options to append to QEMU (e.g. "-show-cursor") QB_DEFAULT_KERNEL: 2574
2506Default kernel to boot (e.g. "bzImage") QB_DEFAULT_FSTYPE: Default 2575 QB_SYSTEM_NAME: QEMU name (e.g. "qemu-system-i386")
2507FSTYPE to boot (e.g. "ext4") QB_MEM: Memory (e.g. "-m 512") QB_MACHINE: 2576 QB_OPT_APPEND: Options to append to QEMU (e.g. "-show-cursor")
2508QEMU machine (e.g. "-machine virt") QB_CPU: QEMU cpu (e.g. "-cpu 2577 QB_DEFAULT_KERNEL: Default kernel to boot (e.g. "bzImage")
2509qemu32") QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. 2578 QB_DEFAULT_FSTYPE: Default FSTYPE to boot (e.g. "ext4")
2510"-cpu kvm64") QB_KERNEL_CMDLINE_APPEND: Options to append to the 2579 QB_MEM: Memory (e.g. "-m 512")
2511kernel's -append option (e.g. "console=ttyS0 console=tty") QB_DTB: QEMU 2580 QB_MACHINE: QEMU machine (e.g. "-machine virt")
2512dtb name QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when 2581 QB_CPU: QEMU cpu (e.g. "-cpu qemu32")
2513support audio) QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw 2582 QB_CPU_KVM: Similar to QB_CPU except used for kvm support (e.g. "-cpu kvm64")
2514ac97,es1370"), which is used when QB_AUDIO_DRV is set. QB_KERNEL_ROOT: 2583 QB_KERNEL_CMDLINE_APPEND: Options to append to the kernel's -append
2515Kernel's root (e.g. /dev/vda) QB_TAP_OPT: Network option for 'tap' mode 2584 option (e.g. "console=ttyS0 console=tty")
2516(e.g. "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device 2585 QB_DTB: QEMU dtb name
2517virtio-net-device,netdev=net0"). runqemu will replace "@TAP@" with the 2586 QB_AUDIO_DRV: QEMU audio driver (e.g. "alsa", set it when support audio)
2518one that is used, such as tap0, tap1 ... QB_SLIRP_OPT: Network option 2587 QB_AUDIO_OPT: QEMU audio option (e.g. "-soundhw ac97,es1370"), which is used
2519for SLIRP mode (e.g. "-netdev user,id=net0 -device 2588 when QB_AUDIO_DRV is set.
2520virtio-net-device,netdev=net0") QB_ROOTFS_OPT: Used as rootfs (e.g. 2589 QB_KERNEL_ROOT: Kernel's root (e.g. /dev/vda)
2521"-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device 2590 QB_TAP_OPT: Network option for 'tap' mode (e.g.
2522virtio-blk-device,drive=disk0"). runqemu will replace "@ROOTFS@" with 2591 "-netdev tap,id=net0,ifname=@TAP@,script=no,downscript=no -device virtio-net-device,netdev=net0").
2523the one which is used, such as core-image-minimal-qemuarm64.ext4. 2592 runqemu will replace "@TAP@" with the one that is used, such as tap0, tap1 ...
2524QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio") QB_TCPSERIAL_OPT: 2593 QB_SLIRP_OPT: Network option for SLIRP mode (e.g. "-netdev user,id=net0 -device virtio-net-device,netdev=net0")
2525tcp serial port option (e.g. " -device virtio-serial-device -chardev 2594 QB_ROOTFS_OPT: Used as rootfs (e.g.
2526socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device 2595 "-drive id=disk0,file=@ROOTFS@,if=none,format=raw -device virtio-blk-device,drive=disk0").
2527virtconsole,chardev=virtcon" runqemu will replace "@PORT@" with the port 2596 runqemu will replace "@ROOTFS@" with the one which is used, such as
2528number which is used. 2597 core-image-minimal-qemuarm64.ext4.
2598 QB_SERIAL_OPT: Serial port (e.g. "-serial mon:stdio")
2599 QB_TCPSERIAL_OPT: tcp serial port option (e.g.
2600 " -device virtio-serial-device -chardev socket,id=virtcon,port=@PORT@,host=127.0.0.1 -device virtconsole,chardev=virtcon"
2601 runqemu will replace "@PORT@" with the port number which is used.
2529 2602
2530To use ``runqemu``, set :term:`IMAGE_CLASSES` as 2603To use ``runqemu``, set :term:`IMAGE_CLASSES` as
2531follows and run ``runqemu``: 2604follows and run ``runqemu``:
@@ -2536,7 +2609,9 @@ follows and run ``runqemu``:
2536 runqemu help 2609 runqemu help
2537 . 2610 .
2538 2611
2539IMAGE_CLASSES += "qemuboot" 2612::
2613
2614 IMAGE_CLASSES += "qemuboot"
2540 2615
2541.. _migration-2.2-default-linker-hash-style-changed: 2616.. _migration-2.2-default-linker-hash-style-changed:
2542 2617
@@ -2551,7 +2626,10 @@ recipes. You need to fix these recipes so that they use the expected
2551``LDFLAGS``. Depending on how the software is built, the build system 2626``LDFLAGS``. Depending on how the software is built, the build system
2552used by the software (e.g. a Makefile) might need to be patched. 2627used by the software (e.g. a Makefile) might need to be patched.
2553However, sometimes making this fix is as simple as adding the following 2628However, sometimes making this fix is as simple as adding the following
2554to the recipe: TARGET_CC_ARCH += "${LDFLAGS}" 2629to the recipe:
2630::
2631
2632 TARGET_CC_ARCH += "${LDFLAGS}"
2555 2633
2556.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype: 2634.. _migration-2.2-kernel-image-base-name-no-longer-uses-kernel-imagetype:
2557 2635
@@ -2562,8 +2640,12 @@ The ``KERNEL_IMAGE_BASE_NAME`` variable no longer uses the
2562:term:`KERNEL_IMAGETYPE` variable to create the 2640:term:`KERNEL_IMAGETYPE` variable to create the
2563image's base name. Because the OpenEmbedded build system can now build 2641image's base name. Because the OpenEmbedded build system can now build
2564multiple kernel image types, this part of the kernel image base name as 2642multiple kernel image types, this part of the kernel image base name as
2565been removed leaving only the following: KERNEL_IMAGE_BASE_NAME ?= 2643been removed leaving only the following:
2566"${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}" If you have recipes or 2644::
2645
2646 KERNEL_IMAGE_BASE_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}-${DATETIME}"
2647
2648If you have recipes or
2567classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to 2649classes that use ``KERNEL_IMAGE_BASE_NAME`` directly, you might need to
2568update the references to ensure they continue to work. 2650update the references to ensure they continue to work.
2569 2651
@@ -2787,7 +2869,7 @@ Consider the following:
2787 ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``, 2869 ``systemd-systemctl-native`` is added to ``PACKAGE_WRITE_DEPS``,
2788 which is also conditional on "systemd" being in ``DISTRO_FEATURES``. 2870 which is also conditional on "systemd" being in ``DISTRO_FEATURES``.
2789 2871
2790- *Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``:* You need to 2872- Examine Recipes that Use ``SSTATEPOSTINSTFUNCS``: You need to
2791 examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine 2873 examine any recipe that uses ``SSTATEPOSTINSTFUNCS`` and determine
2792 steps to take. 2874 steps to take.
2793 2875
@@ -2800,8 +2882,7 @@ Consider the following:
2800 :term:`SYSROOT_PREPROCESS_FUNCS`. 2882 :term:`SYSROOT_PREPROCESS_FUNCS`.
2801 2883
2802 For an example, see the ``pixbufcache`` class in ``meta/classes/`` in 2884 For an example, see the ``pixbufcache`` class in ``meta/classes/`` in
2803 the Yocto Project `Source 2885 the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`.
2804 Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__.
2805 2886
2806 .. note:: 2887 .. note::
2807 2888
@@ -2866,26 +2947,35 @@ Changes to Scripts
2866 2947
2867The following changes to scripts took place: 2948The following changes to scripts took place:
2868 2949
2869- *``oe-find-native-sysroot``:* The usage for the 2950- ``oe-find-native-sysroot``: The usage for the
2870 ``oe-find-native-sysroot`` script has changed to the following: $ . 2951 ``oe-find-native-sysroot`` script has changed to the following:
2871 oe-find-native-sysroot recipe You must now supply a recipe for recipe 2952 ::
2872 as part of the command. Prior to the Yocto Project DISTRO release, it 2953
2954 $ . oe-find-native-sysroot recipe
2955
2956 You must now supply a recipe for recipe
2957 as part of the command. Prior to the Yocto Project &DISTRO; release, it
2873 was not necessary to provide the script with the command. 2958 was not necessary to provide the script with the command.
2874 2959
2875- *``oe-run-native``:* The usage for the ``oe-run-native`` script has 2960- ``oe-run-native``: The usage for the ``oe-run-native`` script has
2876 changed to the following: $ oe-run-native native_recipe tool You must 2961 changed to the following:
2962 ::
2963
2964 $ oe-run-native native_recipe tool
2965
2966 You must
2877 supply the name of the native recipe and the tool you want to run as 2967 supply the name of the native recipe and the tool you want to run as
2878 part of the command. Prior to the Yocto Project DISTRO release, it 2968 part of the command. Prior to the Yocto Project DISTRO release, it
2879 was not necessary to provide the native recipe with the command. 2969 was not necessary to provide the native recipe with the command.
2880 2970
2881- *``cleanup-workdir``:* The ``cleanup-workdir`` script has been 2971- ``cleanup-workdir``: The ``cleanup-workdir`` script has been
2882 removed because the script was found to be deleting files it should 2972 removed because the script was found to be deleting files it should
2883 not have, which lead to broken build trees. Rather than trying to 2973 not have, which lead to broken build trees. Rather than trying to
2884 delete portions of :term:`TMPDIR` and getting it wrong, 2974 delete portions of :term:`TMPDIR` and getting it wrong,
2885 it is recommended that you delete ``TMPDIR`` and have it restored 2975 it is recommended that you delete ``TMPDIR`` and have it restored
2886 from shared state (sstate) on subsequent builds. 2976 from shared state (sstate) on subsequent builds.
2887 2977
2888- *``wipe-sysroot``:* The ``wipe-sysroot`` script has been removed as 2978- ``wipe-sysroot``: The ``wipe-sysroot`` script has been removed as
2889 it is no longer needed with recipe-specific sysroots. 2979 it is no longer needed with recipe-specific sysroots.
2890 2980
2891.. _migration-2.3-functions: 2981.. _migration-2.3-functions:
@@ -2946,8 +3036,8 @@ The following changes took place for BitBake:
2946 section in the BitBake 3036 section in the BitBake
2947 User Manual for additional information. 3037 User Manual for additional information.
2948 3038
2949- *``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` 3039- ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
2950 Removed:* Because the mechanism they were part of is no longer 3040 Removed: Because the mechanism they were part of is no longer
2951 necessary with recipe-specific sysroots, the 3041 necessary with recipe-specific sysroots, the
2952 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2`` 3042 ``BB_SETSCENE_VERIFY_FUNCTION`` and ``BB_SETSCENE_VERIFY_FUNCTION2``
2953 variables have been removed. 3043 variables have been removed.
@@ -3080,29 +3170,29 @@ Removed Recipes
3080 3170
3081The following recipes have been removed: 3171The following recipes have been removed:
3082 3172
3083- *``linux-yocto 4.8:``* Version 4.8 has been removed. Versions 4.1 3173- ``linux-yocto 4.8``: Version 4.8 has been removed. Versions 4.1
3084 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present. 3174 (LTSI), 4.4 (LTS), 4.9 (LTS/LTSI) and 4.10 are now present.
3085 3175
3086- *``python-smartpm:``* Functionally replaced by ``dnf``. 3176- ``python-smartpm``: Functionally replaced by ``dnf``.
3087 3177
3088- *``createrepo:``* Replaced by the ``createrepo-c`` recipe. 3178- ``createrepo``: Replaced by the ``createrepo-c`` recipe.
3089 3179
3090- *``rpmresolve:``* No longer needed with the move to RPM 4 as RPM 3180- ``rpmresolve``: No longer needed with the move to RPM 4 as RPM
3091 itself is used instead. 3181 itself is used instead.
3092 3182
3093- *``gstreamer:``* Removed the GStreamer Git version recipes as they 3183- ``gstreamer``: Removed the GStreamer Git version recipes as they
3094 have been stale. ``1.10.``\ x recipes are still present. 3184 have been stale. ``1.10.``\ x recipes are still present.
3095 3185
3096- *``alsa-conf-base:``* Merged into ``alsa-conf`` since ``libasound`` 3186- ``alsa-conf-base``: Merged into ``alsa-conf`` since ``libasound``
3097 depended on both. Essentially, no way existed to install only one of 3187 depended on both. Essentially, no way existed to install only one of
3098 these. 3188 these.
3099 3189
3100- *``tremor:``* Moved to ``meta-multimedia``. Fixed-integer Vorbis 3190- ``tremor``: Moved to ``meta-multimedia``. Fixed-integer Vorbis
3101 decoding is not needed by current hardware. Thus, GStreamer's ivorbis 3191 decoding is not needed by current hardware. Thus, GStreamer's ivorbis
3102 plugin has been disabled by default eliminating the need for the 3192 plugin has been disabled by default eliminating the need for the
3103 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`. 3193 ``tremor`` recipe in :term:`OpenEmbedded-Core (OE-Core)`.
3104 3194
3105- *``gummiboot:``* Replaced by ``systemd-boot``. 3195- ``gummiboot``: Replaced by ``systemd-boot``.
3106 3196
3107.. _migration-2.3-wic-changes: 3197.. _migration-2.3-wic-changes:
3108 3198
@@ -3135,7 +3225,7 @@ QA Changes
3135 3225
3136The following QA checks have changed: 3226The following QA checks have changed:
3137 3227
3138- *``unsafe-references-in-binaries``:* The 3228- ``unsafe-references-in-binaries``: The
3139 ``unsafe-references-in-binaries`` QA check, which was disabled by 3229 ``unsafe-references-in-binaries`` QA check, which was disabled by
3140 default, has now been removed. This check was intended to detect 3230 default, has now been removed. This check was intended to detect
3141 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have 3231 binaries in ``/bin`` that link to libraries in ``/usr/lib`` and have
@@ -3146,7 +3236,7 @@ The following QA checks have changed:
3146 separate partition from ``/`` is now a rare configuration. 3236 separate partition from ``/`` is now a rare configuration.
3147 Consequently, ``unsafe-references-in-binaries`` was removed. 3237 Consequently, ``unsafe-references-in-binaries`` was removed.
3148 3238
3149- *``file-rdeps``:* The ``file-rdeps`` QA check is now an error by 3239- ``file-rdeps``: The ``file-rdeps`` QA check is now an error by
3150 default instead of a warning. Because it is an error instead of a 3240 default instead of a warning. Because it is an error instead of a
3151 warning, you need to address missing runtime dependencies. 3241 warning, you need to address missing runtime dependencies.
3152 3242
@@ -3202,8 +3292,15 @@ The following miscellaneous changes have occurred:
3202 3292
3203- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig" 3293- The ``USE_LDCONFIG`` variable has been replaced with the "ldconfig"
3204 ``DISTRO_FEATURES`` feature. Distributions that previously set: 3294 ``DISTRO_FEATURES`` feature. Distributions that previously set:
3205 USE_LDCONFIG = "0" should now instead use the following: 3295 ::
3206 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig" 3296
3297 USE_LDCONFIG = "0"
3298
3299 should now instead use the following:
3300
3301 ::
3302
3303 DISTRO_FEATURES_BACKFILL_CONSIDERED_append = " ldconfig"
3207 3304
3208- The default value of 3305- The default value of
3209 :term:`COPYLEFT_LICENSE_INCLUDE` now 3306 :term:`COPYLEFT_LICENSE_INCLUDE` now
@@ -3219,7 +3316,10 @@ The following miscellaneous changes have occurred:
3219 order to allow module packages from multiple kernel versions to 3316 order to allow module packages from multiple kernel versions to
3220 co-exist on a target system. If you wish to return to the previous 3317 co-exist on a target system. If you wish to return to the previous
3221 naming scheme that does not include the version suffix, use the 3318 naming scheme that does not include the version suffix, use the
3222 following: KERNEL_MODULE_PACKAGE_SUFFIX to "" 3319 following:
3320 ::
3321
3322 KERNEL_MODULE_PACKAGE_SUFFIX to ""
3223 3323
3224- Removal of ``libtool`` ``*.la`` files is now enabled by default. The 3324- Removal of ``libtool`` ``*.la`` files is now enabled by default. The
3225 ``*.la`` files are not actually needed on Linux and relocating them 3325 ``*.la`` files are not actually needed on Linux and relocating them
@@ -3285,7 +3385,7 @@ Packaging Changes
3285This section provides information about packaging changes that have 3385This section provides information about packaging changes that have
3286occurred: 3386occurred:
3287 3387
3288- *``python3`` Changes:* 3388- ``python3`` Changes:
3289 3389
3290 - The main "python3" package now brings in all of the standard 3390 - The main "python3" package now brings in all of the standard
3291 Python 3 distribution rather than a subset. This behavior matches 3391 Python 3 distribution rather than a subset. This behavior matches
@@ -3293,16 +3393,16 @@ occurred:
3293 wish to install a subset of Python 3, specify ``python-core`` plus 3393 wish to install a subset of Python 3, specify ``python-core`` plus
3294 one or more of the individual packages that are still produced. 3394 one or more of the individual packages that are still produced.
3295 3395
3296 - *``python3``:* The ``bz2.py``, ``lzma.py``, and 3396 - ``python3``: The ``bz2.py``, ``lzma.py``, and
3297 ``_compression.py`` scripts have been moved from the 3397 ``_compression.py`` scripts have been moved from the
3298 ``python3-misc`` package to the ``python3-compression`` package. 3398 ``python3-misc`` package to the ``python3-compression`` package.
3299 3399
3300- *``binutils``:* The ``libbfd`` library is now packaged in a separate 3400- ``binutils``: The ``libbfd`` library is now packaged in a separate
3301 "libbfd" package. This packaging saves space when certain tools (e.g. 3401 "libbfd" package. This packaging saves space when certain tools (e.g.
3302 ``perf``) are installed. In such cases, the tools only need 3402 ``perf``) are installed. In such cases, the tools only need
3303 ``libbfd`` rather than all the packages in ``binutils``. 3403 ``libbfd`` rather than all the packages in ``binutils``.
3304 3404
3305- *``util-linux`` Changes:* 3405- ``util-linux`` Changes:
3306 3406
3307 - The ``su`` program is now packaged in a separate "util-linux-su" 3407 - The ``su`` program is now packaged in a separate "util-linux-su"
3308 package, which is only built when "pam" is listed in the 3408 package, which is only built when "pam" is listed in the
@@ -3326,7 +3426,7 @@ occurred:
3326 recommended runtime dependency (i.e. ``RRECOMMENDS``) on the 3426 recommended runtime dependency (i.e. ``RRECOMMENDS``) on the
3327 ``util-linux-ionice`` package. 3427 ``util-linux-ionice`` package.
3328 3428
3329- *``initscripts``:* The ``sushell`` program is now packaged in a 3429- ``initscripts``: The ``sushell`` program is now packaged in a
3330 separate "initscripts-sushell" package. This packaging change allows 3430 separate "initscripts-sushell" package. This packaging change allows
3331 systems to pull ``sushell`` in when ``selinux`` is enabled. The 3431 systems to pull ``sushell`` in when ``selinux`` is enabled. The
3332 change also eliminates needing to pull in the entire ``initscripts`` 3432 change also eliminates needing to pull in the entire ``initscripts``
@@ -3334,7 +3434,7 @@ occurred:
3334 (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in 3434 (i.e. ``RDEPENDS``) on the ``sushell`` package when "selinux" is in
3335 ``DISTRO_FEATURES``. 3435 ``DISTRO_FEATURES``.
3336 3436
3337- *``glib-2.0``:* The ``glib-2.0`` package now has a recommended 3437- ``glib-2.0``: The ``glib-2.0`` package now has a recommended
3338 runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info`` 3438 runtime dependency (i.e. ``RRECOMMENDS``) on the ``shared-mime-info``
3339 package, since large portions of GIO are not useful without the MIME 3439 package, since large portions of GIO are not useful without the MIME
3340 database. You can remove the dependency by using the 3440 database. You can remove the dependency by using the
@@ -3351,102 +3451,102 @@ Removed Recipes
3351 3451
3352The following recipes have been removed: 3452The following recipes have been removed:
3353 3453
3354- *``acpitests``:* This recipe is not maintained. 3454- ``acpitests``: This recipe is not maintained.
3355 3455
3356- *``autogen-native``:* No longer required by Grub, oe-core, or 3456- ``autogen-native``: No longer required by Grub, oe-core, or
3357 meta-oe. 3457 meta-oe.
3358 3458
3359- *``bdwgc``:* Nothing in OpenEmbedded-Core requires this recipe. It 3459- ``bdwgc``: Nothing in OpenEmbedded-Core requires this recipe. It
3360 has moved to meta-oe. 3460 has moved to meta-oe.
3361 3461
3362- *``byacc``:* This recipe was only needed by rpm 5.x and has moved to 3462- ``byacc``: This recipe was only needed by rpm 5.x and has moved to
3363 meta-oe. 3463 meta-oe.
3364 3464
3365- *``gcc (5.4)``:* The 5.4 series dropped the recipe in favor of 6.3 / 3465- ``gcc (5.4)``: The 5.4 series dropped the recipe in favor of 6.3 /
3366 7.2. 3466 7.2.
3367 3467
3368- *``gnome-common``:* Deprecated upstream and no longer needed. 3468- ``gnome-common``: Deprecated upstream and no longer needed.
3369 3469
3370- *``go-bootstrap-native``:* Go 1.9 does its own bootstrapping so this 3470- ``go-bootstrap-native``: Go 1.9 does its own bootstrapping so this
3371 recipe has been removed. 3471 recipe has been removed.
3372 3472
3373- *``guile``:* This recipe was only needed by ``autogen-native`` and 3473- ``guile``: This recipe was only needed by ``autogen-native`` and
3374 ``remake``. The recipe is no longer needed by either of these 3474 ``remake``. The recipe is no longer needed by either of these
3375 programs. 3475 programs.
3376 3476
3377- *``libclass-isa-perl``:* This recipe was previously needed for LSB 4, 3477- ``libclass-isa-perl``: This recipe was previously needed for LSB 4,
3378 no longer needed. 3478 no longer needed.
3379 3479
3380- *``libdumpvalue-perl``:* This recipe was previously needed for LSB 4, 3480- ``libdumpvalue-perl``: This recipe was previously needed for LSB 4,
3381 no longer needed. 3481 no longer needed.
3382 3482
3383- *``libenv-perl``:* This recipe was previously needed for LSB 4, no 3483- ``libenv-perl``: This recipe was previously needed for LSB 4, no
3384 longer needed. 3484 longer needed.
3385 3485
3386- *``libfile-checktree-perl``:* This recipe was previously needed for 3486- ``libfile-checktree-perl``: This recipe was previously needed for
3387 LSB 4, no longer needed. 3487 LSB 4, no longer needed.
3388 3488
3389- *``libi18n-collate-perl``:* This recipe was previously needed for LSB 3489- ``libi18n-collate-perl``: This recipe was previously needed for LSB
3390 4, no longer needed. 3490 4, no longer needed.
3391 3491
3392- *``libiconv``:* This recipe was only needed for ``uclibc``, which was 3492- ``libiconv``: This recipe was only needed for ``uclibc``, which was
3393 removed in the previous release. ``glibc`` and ``musl`` have their 3493 removed in the previous release. ``glibc`` and ``musl`` have their
3394 own implementations. ``meta-mingw`` still needs ``libiconv``, so it 3494 own implementations. ``meta-mingw`` still needs ``libiconv``, so it
3395 has been moved to ``meta-mingw``. 3495 has been moved to ``meta-mingw``.
3396 3496
3397- *``libpng12``:* This recipe was previously needed for LSB. The 3497- ``libpng12``: This recipe was previously needed for LSB. The
3398 current ``libpng`` is 1.6.x. 3498 current ``libpng`` is 1.6.x.
3399 3499
3400- *``libpod-plainer-perl``:* This recipe was previously needed for LSB 3500- ``libpod-plainer-perl``: This recipe was previously needed for LSB
3401 4, no longer needed. 3501 4, no longer needed.
3402 3502
3403- *``linux-yocto (4.1)``:* This recipe was removed in favor of 4.4, 3503- ``linux-yocto (4.1)``: This recipe was removed in favor of 4.4,
3404 4.9, 4.10 and 4.12. 3504 4.9, 4.10 and 4.12.
3405 3505
3406- *``mailx``:* This recipe was previously only needed for LSB 3506- ``mailx``: This recipe was previously only needed for LSB
3407 compatibility, and upstream is defunct. 3507 compatibility, and upstream is defunct.
3408 3508
3409- *``mesa (git version only)``:* The git version recipe was stale with 3509- ``mesa (git version only)``: The git version recipe was stale with
3410 respect to the release version. 3510 respect to the release version.
3411 3511
3412- *``ofono (git version only)``:* The git version recipe was stale with 3512- ``ofono (git version only)``: The git version recipe was stale with
3413 respect to the release version. 3513 respect to the release version.
3414 3514
3415- *``portmap``:* This recipe is obsolete and is superseded by 3515- ``portmap``: This recipe is obsolete and is superseded by
3416 ``rpcbind``. 3516 ``rpcbind``.
3417 3517
3418- *``python3-pygpgme``:* This recipe is old and unmaintained. It was 3518- ``python3-pygpgme``: This recipe is old and unmaintained. It was
3419 previously required by ``dnf``, which has switched to official 3519 previously required by ``dnf``, which has switched to official
3420 ``gpgme`` Python bindings. 3520 ``gpgme`` Python bindings.
3421 3521
3422- *``python-async``:* This recipe has been removed in favor of the 3522- ``python-async``: This recipe has been removed in favor of the
3423 Python 3 version. 3523 Python 3 version.
3424 3524
3425- *``python-gitdb``:* This recipe has been removed in favor of the 3525- ``python-gitdb``: This recipe has been removed in favor of the
3426 Python 3 version. 3526 Python 3 version.
3427 3527
3428- *``python-git``:* This recipe was removed in favor of the Python 3 3528- ``python-git``: This recipe was removed in favor of the Python 3
3429 version. 3529 version.
3430 3530
3431- *``python-mako``:* This recipe was removed in favor of the Python 3 3531- ``python-mako``: This recipe was removed in favor of the Python 3
3432 version. 3532 version.
3433 3533
3434- *``python-pexpect``:* This recipe was removed in favor of the Python 3534- ``python-pexpect``: This recipe was removed in favor of the Python
3435 3 version. 3535 3 version.
3436 3536
3437- *``python-ptyprocess``:* This recipe was removed in favor of Python 3537- ``python-ptyprocess``: This recipe was removed in favor of Python
3438 the 3 version. 3538 the 3 version.
3439 3539
3440- *``python-pycurl``:* Nothing is using this recipe in 3540- ``python-pycurl``: Nothing is using this recipe in
3441 OpenEmbedded-Core (i.e. ``meta-oe``). 3541 OpenEmbedded-Core (i.e. ``meta-oe``).
3442 3542
3443- *``python-six``:* This recipe was removed in favor of the Python 3 3543- ``python-six``: This recipe was removed in favor of the Python 3
3444 version. 3544 version.
3445 3545
3446- *``python-smmap``:* This recipe was removed in favor of the Python 3 3546- ``python-smmap``: This recipe was removed in favor of the Python 3
3447 version. 3547 version.
3448 3548
3449- *``remake``:* Using ``remake`` as the provider of ``virtual/make`` is 3549- ``remake``: Using ``remake`` as the provider of ``virtual/make`` is
3450 broken. Consequently, this recipe is not needed in OpenEmbedded-Core. 3550 broken. Consequently, this recipe is not needed in OpenEmbedded-Core.
3451 3551
3452.. _migration-2.4-kernel-device-tree-move: 3552.. _migration-2.4-kernel-device-tree-move:
@@ -3598,17 +3698,17 @@ Packaging Changes
3598This section provides information about packaging changes that have 3698This section provides information about packaging changes that have
3599occurred: 3699occurred:
3600 3700
3601- *``bind-libs``:* The libraries packaged by the bind recipe are in a 3701- ``bind-libs``: The libraries packaged by the bind recipe are in a
3602 separate ``bind-libs`` package. 3702 separate ``bind-libs`` package.
3603 3703
3604- *``libfm-gtk``:* The ``libfm`` GTK+ bindings are split into a 3704- ``libfm-gtk``: The ``libfm`` GTK+ bindings are split into a
3605 separate ``libfm-gtk`` package. 3705 separate ``libfm-gtk`` package.
3606 3706
3607- *``flex-libfl``:* The flex recipe splits out libfl into a separate 3707- ``flex-libfl``: The flex recipe splits out libfl into a separate
3608 ``flex-libfl`` package to avoid too many dependencies being pulled in 3708 ``flex-libfl`` package to avoid too many dependencies being pulled in
3609 where only the library is needed. 3709 where only the library is needed.
3610 3710
3611- *``grub-efi``:* The ``grub-efi`` configuration is split into a 3711- ``grub-efi``: The ``grub-efi`` configuration is split into a
3612 separate ``grub-bootconf`` recipe. However, the dependency 3712 separate ``grub-bootconf`` recipe. However, the dependency
3613 relationship from ``grub-efi`` is through a virtual/grub-bootconf 3713 relationship from ``grub-efi`` is through a virtual/grub-bootconf
3614 provider making it possible to have your own recipe provide the 3714 provider making it possible to have your own recipe provide the
@@ -3628,42 +3728,42 @@ Removed Recipes
3628 3728
3629The following recipes have been removed: 3729The following recipes have been removed:
3630 3730
3631- *``gcc``:* The version 6.4 recipes are replaced by 7.x. 3731- ``gcc``: The version 6.4 recipes are replaced by 7.x.
3632 3732
3633- *``gst-player``:* Renamed to ``gst-examples`` as per upstream. 3733- ``gst-player``: Renamed to ``gst-examples`` as per upstream.
3634 3734
3635- *``hostap-utils``:* This software package is obsolete. 3735- ``hostap-utils``: This software package is obsolete.
3636 3736
3637- *``latencytop``:* This recipe is no longer maintained upstream. The 3737- ``latencytop``: This recipe is no longer maintained upstream. The
3638 last release was in 2009. 3738 last release was in 2009.
3639 3739
3640- *``libpfm4``:* The only file that requires this recipe is 3740- ``libpfm4``: The only file that requires this recipe is
3641 ``oprofile``, which has been removed. 3741 ``oprofile``, which has been removed.
3642 3742
3643- *``linux-yocto``:* The version 4.4, 4.9, and 4.10 recipes have been 3743- ``linux-yocto``: The version 4.4, 4.9, and 4.10 recipes have been
3644 removed. Versions 4.12, 4.14, and 4.15 remain. 3744 removed. Versions 4.12, 4.14, and 4.15 remain.
3645 3745
3646- *``man``:* This recipe has been replaced by modern ``man-db`` 3746- ``man``: This recipe has been replaced by modern ``man-db``
3647 3747
3648- *``mkelfimage``:* This tool has been removed in the upstream coreboot 3748- ``mkelfimage``: This tool has been removed in the upstream coreboot
3649 project, and is no longer needed with the removal of the ELF image 3749 project, and is no longer needed with the removal of the ELF image
3650 type. 3750 type.
3651 3751
3652- *``nativesdk-postinst-intercept``:* This recipe is not maintained. 3752- ``nativesdk-postinst-intercept``: This recipe is not maintained.
3653 3753
3654- *``neon``:* This software package is no longer maintained upstream 3754- ``neon``: This software package is no longer maintained upstream
3655 and is no longer needed by anything in OpenEmbedded-Core. 3755 and is no longer needed by anything in OpenEmbedded-Core.
3656 3756
3657- *``oprofile``:* The functionality of this recipe is replaced by 3757- ``oprofile``: The functionality of this recipe is replaced by
3658 ``perf`` and keeping compatibility on an ongoing basis with ``musl`` 3758 ``perf`` and keeping compatibility on an ongoing basis with ``musl``
3659 is difficult. 3759 is difficult.
3660 3760
3661- *``pax``:* This software package is obsolete. 3761- ``pax``: This software package is obsolete.
3662 3762
3663- *``stat``:* This software package is not maintained upstream. 3763- ``stat``: This software package is not maintained upstream.
3664 ``coreutils`` provides a modern stat binary. 3764 ``coreutils`` provides a modern stat binary.
3665 3765
3666- *``zisofs-tools-native``:* This recipe is no longer needed because 3766- ``zisofs-tools-native``: This recipe is no longer needed because
3667 the compressed ISO image feature has been removed. 3767 the compressed ISO image feature has been removed.
3668 3768
3669.. _migration-2.5-scripts-and-tools-changes: 3769.. _migration-2.5-scripts-and-tools-changes:
@@ -3673,17 +3773,16 @@ Scripts and Tools Changes
3673 3773
3674The following are changes to scripts and tools: 3774The following are changes to scripts and tools:
3675 3775
3676- *``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``*: The 3776- ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer``: The
3677 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts 3777 ``yocto-bsp``, ``yocto-kernel``, and ``yocto-layer`` scripts
3678 previously shipped with poky but not in OpenEmbedded-Core have been 3778 previously shipped with poky but not in OpenEmbedded-Core have been
3679 removed. These scripts are not maintained and are outdated. In many 3779 removed. These scripts are not maintained and are outdated. In many
3680 cases, they are also limited in scope. The 3780 cases, they are also limited in scope. The
3681 ``bitbake-layers create-layer`` command is a direct replacement for 3781 ``bitbake-layers create-layer`` command is a direct replacement for
3682 ``yocto-layer``. See the documentation to create a BSP or kernel 3782 ``yocto-layer``. See the documentation to create a BSP or kernel
3683 recipe in the "`BSP Kernel Recipe 3783 recipe in the ":ref:`bsp-guide/bsp:bsp kernel recipe example`" section.
3684 Example <&YOCTO_DOCS_BSP_URL;#bsp-kernel-recipe-example>`__" section.
3685 3784
3686- *``devtool finish``:* ``devtool finish`` now exits with an error if 3785- ``devtool finish``: ``devtool finish`` now exits with an error if
3687 there are uncommitted changes or a rebase/am in progress in the 3786 there are uncommitted changes or a rebase/am in progress in the
3688 recipe's source repository. If this error occurs, there might be 3787 recipe's source repository. If this error occurs, there might be
3689 uncommitted changes that will not be included in updates to the 3788 uncommitted changes that will not be included in updates to the
@@ -3691,11 +3790,11 @@ The following are changes to scripts and tools:
3691 situations that the uncommitted changes are inconsequential and you 3790 situations that the uncommitted changes are inconsequential and you
3692 want to proceed regardless. 3791 want to proceed regardless.
3693 3792
3694- *``scripts/oe-setup-rpmrepo`` script:* The functionality of 3793- ``scripts/oe-setup-rpmrepo`` script: The functionality of
3695 ``scripts/oe-setup-rpmrepo`` is replaced by 3794 ``scripts/oe-setup-rpmrepo`` is replaced by
3696 ``bitbake package-index``. 3795 ``bitbake package-index``.
3697 3796
3698- *``scripts/test-dependencies.sh`` script:* The script is largely made 3797- ``scripts/test-dependencies.sh`` script: The script is largely made
3699 obsolete by the recipe-specific sysroots functionality introduced in 3798 obsolete by the recipe-specific sysroots functionality introduced in
3700 the previous release. 3799 the previous release.
3701 3800
@@ -3725,8 +3824,15 @@ The following are BitBake changes:
3725 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``, 3824 tree" tasks have been removed (e.g. ``fetchall``, ``checkuriall``,
3726 and the ``*all`` tasks provided by the ``distrodata`` and 3825 and the ``*all`` tasks provided by the ``distrodata`` and
3727 ``archiver`` classes). There is a BitBake option to complete this for 3826 ``archiver`` classes). There is a BitBake option to complete this for
3728 any arbitrary task. For example: bitbake <target> -c fetchall should 3827 any arbitrary task. For example:
3729 now be replaced with: bitbake <target> --runall=fetch 3828 ::
3829
3830 bitbake <target> -c fetchall
3831
3832 should now be replaced with:
3833 ::
3834
3835 bitbake <target> --runall=fetch
3730 3836
3731.. _migration-2.5-python-and-python3-changes: 3837.. _migration-2.5-python-and-python3-changes:
3732 3838
@@ -3749,8 +3855,15 @@ one of the packages provided by the Python recipe. You can no longer run
3749``bitbake python-foo`` or have a 3855``bitbake python-foo`` or have a
3750:term:`DEPENDS` on ``python-foo``, 3856:term:`DEPENDS` on ``python-foo``,
3751but doing either of the following causes the package to work as 3857but doing either of the following causes the package to work as
3752expected: IMAGE_INSTALL_append = " python-foo" or RDEPENDS_${PN} = 3858expected: ::
3753"python-foo" The earlier build-time provides behavior was a quirk of the 3859
3860 IMAGE_INSTALL_append = " python-foo"
3861
3862or ::
3863
3864 RDEPENDS_${PN} = "python-foo"
3865
3866The earlier build-time provides behavior was a quirk of the
3754way the Python manifest file was created. For more information on this 3867way the Python manifest file was created. For more information on this
3755change please see `this 3868change please see `this
3756commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__. 3869commit <http://git.yoctoproject.org/cgit/cgit.cgi/poky/commit/?id=8d94b9db221d1def42f091b991903faa2d1651ce>`__.
@@ -3798,17 +3911,36 @@ The following are additional changes:
3798 ``bitbake/lib/bb``. These are typically used from recipes and 3911 ``bitbake/lib/bb``. These are typically used from recipes and
3799 classes. Any references to the old functions must be updated. The 3912 classes. Any references to the old functions must be updated. The
3800 following table shows the removed functions and their replacements: 3913 following table shows the removed functions and their replacements:
3801 *Removed* *Replacement* ============================ 3914
3802 ============================ base_path_join() oe.path.join() 3915 +------------------------------+----------------------------------------------------------+
3803 base_path_relative() oe.path.relative() base_path_out() 3916 | *Removed* | *Replacement* |
3804 oe.path.format_display() base_read_file() oe.utils.read_file() 3917 +==============================+==========================================================+
3805 base_ifelse() oe.utils.ifelse() base_conditional() 3918 | base_path_join() | oe.path.join() |
3806 oe.utils.conditional() base_less_or_equal() oe.utils.less_or_equal() 3919 +------------------------------+----------------------------------------------------------+
3807 base_version_less_or_equal() oe.utils.version_less_or_equal() 3920 | base_path_relative() | oe.path.relative() |
3808 base_contains() bb.utils.contains() base_both_contain() 3921 +------------------------------+----------------------------------------------------------+
3809 oe.utils.both_contain() base_prune_suffix() oe.utils.prune_suffix() 3922 | base_path_out() | oe.path.format_display() |
3810 oe_filter() oe.utils.str_filter() oe_filter_out() 3923 +------------------------------+----------------------------------------------------------+
3811 oe.utils.str_filter_out() (or use the \_remove operator). 3924 | base_read_file() | oe.utils.read_file() |
3925 +------------------------------+----------------------------------------------------------+
3926 | base_ifelse() | oe.utils.ifelse() |
3927 +------------------------------+----------------------------------------------------------+
3928 | base_conditional() | oe.utils.conditional() |
3929 +------------------------------+----------------------------------------------------------+
3930 | base_less_or_equal() | oe.utils.less_or_equal() |
3931 +------------------------------+----------------------------------------------------------+
3932 | base_version_less_or_equal() | oe.utils.version_less_or_equal() |
3933 +------------------------------+----------------------------------------------------------+
3934 | base_contains() | bb.utils.contains() |
3935 +------------------------------+----------------------------------------------------------+
3936 | base_both_contain() | oe.utils.both_contain() |
3937 +------------------------------+----------------------------------------------------------+
3938 | base_prune_suffix() | oe.utils.prune_suffix() |
3939 +------------------------------+----------------------------------------------------------+
3940 | oe_filter() | oe.utils.str_filter() |
3941 +------------------------------+----------------------------------------------------------+
3942 | oe_filter_out() | oe.utils.str_filter_out() (or use the \_remove operator) |
3943 +------------------------------+----------------------------------------------------------+
3812 3944
3813- Using ``exit 1`` to explicitly defer a postinstall script until first 3945- Using ``exit 1`` to explicitly defer a postinstall script until first
3814 boot is now deprecated since it is not an obvious mechanism and can 3946 boot is now deprecated since it is not an obvious mechanism and can
@@ -3819,8 +3951,8 @@ The following are additional changes:
3819 Any failure of a ``pkg_postinst()`` script (including ``exit 1``) 3951 Any failure of a ``pkg_postinst()`` script (including ``exit 1``)
3820 will trigger a warning during ``do_rootfs``. 3952 will trigger a warning during ``do_rootfs``.
3821 3953
3822 For more information, see the "`Post-Installation 3954 For more information, see the
3823 Scripts <&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts>`__" 3955 ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
3824 section in the Yocto Project Development Tasks Manual. 3956 section in the Yocto Project Development Tasks Manual.
3825 3957
3826- The ``elf`` image type has been removed. This image type was removed 3958- The ``elf`` image type has been removed. This image type was removed
@@ -3886,46 +4018,55 @@ your configuration.
3886Removed Recipes 4018Removed Recipes
3887--------------- 4019---------------
3888 4020
3889The following recipes have been removed: *``beecrypt``:* No longer 4021The following recipes have been removed:
3890needed since moving to RPM 4. *``bigreqsproto``:* Replaced by 4022
3891``xorgproto``. *``calibrateproto``:* Removed in favor of ``xinput``. 4023- *beecrypt*: No longer needed since moving to RPM 4.
3892*``compositeproto``:* Replaced by ``xorgproto``. *``damageproto``:* 4024- *bigreqsproto*: Replaced by ``xorgproto``.
3893Replaced by ``xorgproto``. *``dmxproto``:* Replaced by ``xorgproto``. 4025- *calibrateproto*: Removed in favor of ``xinput``.
3894*``dri2proto``:* Replaced by ``xorgproto``. *``dri3proto``:* Replaced by 4026- *compositeproto*: Replaced by ``xorgproto``.
3895``xorgproto``. *``eee-acpi-scripts``:* Became obsolete. 4027- *damageproto*: Replaced by ``xorgproto``.
3896*``fixesproto``:* Replaced by ``xorgproto``. *``fontsproto``:* Replaced 4028- *dmxproto*: Replaced by ``xorgproto``.
3897by ``xorgproto``. *``fstests``:* Became obsolete. *``gccmakedep``:* No 4029- *dri2proto*: Replaced by ``xorgproto``.
3898longer used. *``glproto``:* Replaced by ``xorgproto``. 4030- *dri3proto*: Replaced by ``xorgproto``.
3899*``gnome-desktop3``:* No longer needed. This recipe has moved to 4031- *eee-acpi-scripts*: Became obsolete.
3900``meta-oe``. *``icon-naming-utils``:* No longer used since the Sato 4032- *fixesproto*: Replaced by ``xorgproto``.
3901theme was removed in 2016. *``inputproto``:* Replaced by ``xorgproto``. 4033- *fontsproto*: Replaced by ``xorgproto``.
3902*``kbproto``:* Replaced by ``xorgproto``. *``libusb-compat``:* Became 4034- *fstests*: Became obsolete.
3903obsolete. *``libuser``:* Became obsolete. *``libnfsidmap``:* No longer 4035- *gccmakedep*: No longer used.
3904an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is 4036- *glproto*: Replaced by ``xorgproto``.
3905now integrated. *``libxcalibrate``:* No longer needed with ``xinput`` 4037- *gnome-desktop3*: No longer needed. This recipe has moved to ``meta-oe``.
3906*``mktemp``:* Became obsolete. The ``mktemp`` command is provided by 4038- *icon-naming-utils*: No longer used since the Sato theme was removed in 2016.
3907both ``busybox`` and ``coreutils``. *``ossp-uuid``:* Is not being 4039- *inputproto*: Replaced by ``xorgproto``.
3908maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``. 4040- *kbproto*: Replaced by ``xorgproto``.
3909*``pax-utils``:* No longer needed. Previous QA tests that did use this 4041- *libusb-compat*: Became obsolete.
3910recipe are now done at build time. *``pcmciautils``:* Became obsolete. 4042- *libuser*: Became obsolete.
3911*``pixz``:* No longer needed. ``xz`` now supports multi-threaded 4043- *libnfsidmap*: No longer an external requirement since ``nfs-utils`` 2.2.1. ``libnfsidmap`` is now integrated.
3912compression. *``presentproto``:* Replaced by ``xorgproto``. 4044- *libxcalibrate*: No longer needed with ``xinput``
3913*``randrproto``:* Replaced by ``xorgproto``. *``recordproto``:* Replaced 4045- *mktemp*: Became obsolete. The ``mktemp`` command is provided by both ``busybox`` and ``coreutils``.
3914by ``xorgproto``. *``renderproto``:* Replaced by ``xorgproto``. 4046- *ossp-uuid*: Is not being maintained and has mostly been replaced by ``uuid.h`` in ``util-linux``.
3915*``resourceproto``:* Replaced by ``xorgproto``. *``scrnsaverproto``:* 4047- *pax-utils*: No longer needed. Previous QA tests that did use this recipe are now done at build time.
3916Replaced by ``xorgproto``. *``trace-cmd``:* Became obsolete. ``perf`` 4048- *pcmciautils*: Became obsolete.
3917replaced this recipe's functionally. *``videoproto``:* Replaced by 4049- *pixz*: No longer needed. ``xz`` now supports multi-threaded compression.
3918``xorgproto``. *``wireless-tools``:* Became obsolete. Superseded by 4050- *presentproto*: Replaced by ``xorgproto``.
3919``iw``. *``xcmiscproto``:* Replaced by ``xorgproto``. *``xextproto``:* 4051- *randrproto*: Replaced by ``xorgproto``.
3920Replaced by ``xorgproto``. *``xf86dgaproto``:* Replaced by 4052- *recordproto*: Replaced by ``xorgproto``.
3921``xorgproto``. *``xf86driproto``:* Replaced by ``xorgproto``. 4053- *renderproto*: Replaced by ``xorgproto``.
3922*``xf86miscproto``:* Replaced by ``xorgproto``. *``xf86-video-omapfb``:* 4054- *resourceproto*: Replaced by ``xorgproto``.
3923Became obsolete. Use kernel modesetting driver instead. 4055- *scrnsaverproto*: Replaced by ``xorgproto``.
3924*``xf86-video-omap``:* Became obsolete. Use kernel modesetting driver 4056- *trace-cmd*: Became obsolete. ``perf`` replaced this recipe's functionally.
3925instead. *``xf86vidmodeproto``:* Replaced by ``xorgproto``. 4057- *videoproto*: Replaced by ``xorgproto``.
3926*``xineramaproto``:* Replaced by ``xorgproto``. *``xproto``:* Replaced 4058- *wireless-tools*: Became obsolete. Superseded by ``iw``.
3927by ``xorgproto``. *``yasm``:* No longer needed since previous usages are 4059- *xcmiscproto*: Replaced by ``xorgproto``.
3928now satisfied by ``nasm``. 4060- *xextproto*: Replaced by ``xorgproto``.
4061- *xf86dgaproto*: Replaced by ``xorgproto``.
4062- *xf86driproto*: Replaced by ``xorgproto``.
4063- *xf86miscproto*: Replaced by ``xorgproto``.
4064- *xf86-video-omapfb*: Became obsolete. Use kernel modesetting driver instead.
4065- *xf86-video-omap*: Became obsolete. Use kernel modesetting driver instead.
4066- *xf86vidmodeproto*: Replaced by ``xorgproto``.
4067- *xineramaproto*: Replaced by ``xorgproto``.
4068- *xproto*: Replaced by ``xorgproto``.
4069- *yasm*: No longer needed since previous usages are now satisfied by ``nasm``.
3929 4070
3930.. _migration-2.6-packaging-changes: 4071.. _migration-2.6-packaging-changes:
3931 4072
@@ -3934,30 +4075,30 @@ Packaging Changes
3934 4075
3935The following packaging changes have been made: 4076The following packaging changes have been made:
3936 4077
3937- *``cmake``:* ``cmake.m4`` and ``toolchain`` files have been moved to 4078- *cmake*: ``cmake.m4`` and ``toolchain`` files have been moved to
3938 the main package. 4079 the main package.
3939 4080
3940- *``iptables``:* The ``iptables`` modules have been split into 4081- *iptables*: The ``iptables`` modules have been split into
3941 separate packages. 4082 separate packages.
3942 4083
3943- *``alsa-lib``:* ``libasound`` is now in the main ``alsa-lib`` package 4084- *alsa-lib*: ``libasound`` is now in the main ``alsa-lib`` package
3944 instead of ``libasound``. 4085 instead of ``libasound``.
3945 4086
3946- *``glibc``:* ``libnss-db`` is now in its own package along with a 4087- *glibc*: ``libnss-db`` is now in its own package along with a
3947 ``/var/db/makedbs.sh`` script to update databases. 4088 ``/var/db/makedbs.sh`` script to update databases.
3948 4089
3949- *``python`` and ``python3``:* The main package has been removed from 4090- *python and python3*: The main package has been removed from
3950 the recipe. You must install specific packages or ``python-modules`` 4091 the recipe. You must install specific packages or ``python-modules``
3951 / ``python3-modules`` for everything. 4092 / ``python3-modules`` for everything.
3952 4093
3953- *``systemtap``:* Moved ``systemtap-exporter`` into its own package. 4094- *systemtap*: Moved ``systemtap-exporter`` into its own package.
3954 4095
3955.. _migration-2.6-xorg-protocol-dependencies: 4096.. _migration-2.6-xorg-protocol-dependencies:
3956 4097
3957XOrg Protocol dependencies 4098XOrg Protocol dependencies
3958-------------------------- 4099--------------------------
3959 4100
3960The "*proto" upstream repositories have been combined into one 4101The ``*proto`` upstream repositories have been combined into one
3961"xorgproto" repository. Thus, the corresponding recipes have also been 4102"xorgproto" repository. Thus, the corresponding recipes have also been
3962combined into a single ``xorgproto`` recipe. Any recipes that depend 4103combined into a single ``xorgproto`` recipe. Any recipes that depend
3963upon the older ``*proto`` recipes need to be changed to depend on the 4104upon the older ``*proto`` recipes need to be changed to depend on the
@@ -4024,19 +4165,21 @@ The following changes have been made:
4024 allows easier and more direct changes. 4165 allows easier and more direct changes.
4025 4166
4026 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf`` 4167 The ``IMAGE_VERSION_SUFFIX`` variable is set in the ``bitbake.conf``
4027 configuration file as follows: IMAGE_VERSION_SUFFIX = "-${DATETIME}" 4168 configuration file as follows:
4028 4169 ::
4029- Several variables have changed names for consistency: Old Variable 4170
4030 Name New Variable Name 4171 IMAGE_VERSION_SUFFIX = "-${DATETIME}"
4031 ======================================================== 4172
4032 KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME` 4173- Several variables have changed names for consistency:
4033 KERNEL_IMAGE_SYMLINK_NAME 4174 ::
4034 :term:`KERNEL_IMAGE_LINK_NAME` 4175
4035 MODULE_TARBALL_BASE_NAME 4176 Old Variable Name New Variable Name
4036 :term:`MODULE_TARBALL_NAME` 4177 ========================================================
4037 MODULE_TARBALL_SYMLINK_NAME 4178 KERNEL_IMAGE_BASE_NAME :term:`KERNEL_IMAGE_NAME`
4038 :term:`MODULE_TARBALL_LINK_NAME` 4179 KERNEL_IMAGE_SYMLINK_NAME :term:`KERNEL_IMAGE_LINK_NAME`
4039 INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME` 4180 MODULE_TARBALL_BASE_NAME :term:`MODULE_TARBALL_NAME`
4181 MODULE_TARBALL_SYMLINK_NAME :term:`MODULE_TARBALL_LINK_NAME`
4182 INITRAMFS_BASE_NAME :term:`INITRAMFS_NAME`
4040 4183
4041- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module 4184- The ``MODULE_IMAGE_BASE_NAME`` variable has been removed. The module
4042 tarball name is now controlled directly with the 4185 tarball name is now controlled directly with the
@@ -4107,8 +4250,8 @@ Override Changes
4107 4250
4108The following changes have occurred: 4251The following changes have occurred:
4109 4252
4110- *The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have 4253- The ``virtclass-native`` and ``virtclass-nativesdk`` Overrides Have
4111 Been Removed:* The ``virtclass-native`` and ``virtclass-nativesdk`` 4254 Been Removed: The ``virtclass-native`` and ``virtclass-nativesdk``
4112 overrides have been deprecated since 2012 in favor of 4255 overrides have been deprecated since 2012 in favor of
4113 ``class-native`` and ``class-nativesdk``, respectively. Both 4256 ``class-native`` and ``class-nativesdk``, respectively. Both
4114 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped. 4257 ``virtclass-native`` and ``virtclass-nativesdk`` are now dropped.
@@ -4119,8 +4262,8 @@ The following changes have occurred:
4119 virtclass-multilib- 4262 virtclass-multilib-
4120 overrides for multilib are still valid. 4263 overrides for multilib are still valid.
4121 4264
4122- *The ``forcevariable`` Override Now Has a Higher Priority Than 4265- The ``forcevariable`` Override Now Has a Higher Priority Than
4123 ``libc`` Overrides:* The ``forcevariable`` override is documented to 4266 ``libc`` Overrides: The ``forcevariable`` override is documented to
4124 be the highest priority override. However, due to a long-standing 4267 be the highest priority override. However, due to a long-standing
4125 quirk of how :term:`OVERRIDES` is set, the ``libc`` 4268 quirk of how :term:`OVERRIDES` is set, the ``libc``
4126 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth) 4269 overrides (e.g. ``libc-glibc``, ``libc-musl``, and so forth)
@@ -4132,7 +4275,7 @@ The following changes have occurred:
4132 check how you use ``forcevariable`` and ``libc-*`` overrides in your 4275 check how you use ``forcevariable`` and ``libc-*`` overrides in your
4133 custom layers and configuration files to ensure they make sense. 4276 custom layers and configuration files to ensure they make sense.
4134 4277
4135- *The ``build-${BUILD_OS}`` Override Has Been Removed:* The 4278- The ``build-${BUILD_OS}`` Override Has Been Removed: The
4136 ``build-${BUILD_OS}``, which is typically ``build-linux``, override 4279 ``build-${BUILD_OS}``, which is typically ``build-linux``, override
4137 has been removed because building on a host operating system other 4280 has been removed because building on a host operating system other
4138 than a recent version of Linux is neither supported nor recommended. 4281 than a recent version of Linux is neither supported nor recommended.
@@ -4158,10 +4301,16 @@ where machine-specific configurations need to be applied (e.g. for
4158``qemu*`` machines). 4301``qemu*`` machines).
4159 4302
4160Currently, the new recipe packages the following files: 4303Currently, the new recipe packages the following files:
4161${sysconfdir}/machine-id ${sysconfdir}/systemd/coredump.conf 4304::
4162${sysconfdir}/systemd/journald.conf ${sysconfdir}/systemd/logind.conf 4305
4163${sysconfdir}/systemd/system.conf ${sysconfdir}/systemd/user.conf If you 4306 ${sysconfdir}/machine-id
4164previously used bbappend files to append the ``systemd`` recipe to 4307 ${sysconfdir}/systemd/coredump.conf
4308 ${sysconfdir}/systemd/journald.conf
4309 ${sysconfdir}/systemd/logind.conf
4310 ${sysconfdir}/systemd/system.conf
4311 ${sysconfdir}/systemd/user.conf
4312
4313If you previously used bbappend files to append the ``systemd`` recipe to
4165change any of the listed files, you must do so for the ``systemd-conf`` 4314change any of the listed files, you must do so for the ``systemd-conf``
4166recipe instead. 4315recipe instead.
4167 4316
@@ -4172,13 +4321,13 @@ Automatic Testing Changes
4172 4321
4173This section provides information about automatic testing changes: 4322This section provides information about automatic testing changes:
4174 4323
4175- *``TEST_IMAGE`` Variable Removed:* Prior to this release, you set the 4324- ``TEST_IMAGE`` Variable Removed: Prior to this release, you set the
4176 ``TEST_IMAGE`` variable to "1" to enable automatic testing for 4325 ``TEST_IMAGE`` variable to "1" to enable automatic testing for
4177 successfully built images. The ``TEST_IMAGE`` variable no longer 4326 successfully built images. The ``TEST_IMAGE`` variable no longer
4178 exists and has been replaced by the 4327 exists and has been replaced by the
4179 :term:`TESTIMAGE_AUTO` variable. 4328 :term:`TESTIMAGE_AUTO` variable.
4180 4329
4181- *Inheriting the ``testimage`` and ``testsdk`` Classes:* Best 4330- Inheriting the ``testimage`` and ``testsdk`` Classes: Best
4182 practices now dictate that you use the 4331 practices now dictate that you use the
4183 :term:`IMAGE_CLASSES` variable rather than the 4332 :term:`IMAGE_CLASSES` variable rather than the
4184 :term:`INHERIT` variable when you inherit the 4333 :term:`INHERIT` variable when you inherit the
@@ -4231,8 +4380,7 @@ Any failure of a ``pkg_postinst()`` script (including exit 1) triggers
4231an error during the :ref:`ref-tasks-rootfs` task. 4380an error during the :ref:`ref-tasks-rootfs` task.
4232 4381
4233For more information on post-installation behavior, see the 4382For more information on post-installation behavior, see the
4234"`Post-Installation 4383":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
4235Scripts <&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts>`__"
4236section in the Yocto Project Development Tasks Manual. 4384section in the Yocto Project Development Tasks Manual.
4237 4385
4238.. _migration-2.6-python-3-profile-guided-optimizations: 4386.. _migration-2.6-python-3-profile-guided-optimizations:
@@ -4253,8 +4401,12 @@ If you wish to disable Python profile-guided optimization regardless of
4253the value of ``MACHINE_FEATURES``, then ensure that 4401the value of ``MACHINE_FEATURES``, then ensure that
4254:term:`PACKAGECONFIG` for the ``python3`` recipe 4402:term:`PACKAGECONFIG` for the ``python3`` recipe
4255does not contain "pgo". You could accomplish the latter using the 4403does not contain "pgo". You could accomplish the latter using the
4256following at the configuration level: PACKAGECONFIG_remove_pn-python3 = 4404following at the configuration level:
4257"pgo" Alternatively, you can set ``PACKAGECONFIG`` using an append file 4405::
4406
4407 PACKAGECONFIG_remove_pn-python3 = "pgo"
4408
4409Alternatively, you can set ``PACKAGECONFIG`` using an append file
4258for the ``python3`` recipe. 4410for the ``python3`` recipe.
4259 4411
4260.. _migration-2.6-miscellaneous-changes: 4412.. _migration-2.6-miscellaneous-changes:
@@ -4267,7 +4419,10 @@ The following miscellaneous changes occurred:
4267- Default to using the Thumb-2 instruction set for armv7a and above. If 4419- Default to using the Thumb-2 instruction set for armv7a and above. If
4268 you have any custom recipes that build software that needs to be 4420 you have any custom recipes that build software that needs to be
4269 built with the ARM instruction set, change the recipe to set the 4421 built with the ARM instruction set, change the recipe to set the
4270 instruction set as follows: ARM_INSTRUCTION_SET = "arm" 4422 instruction set as follows:
4423 ::
4424
4425 ARM_INSTRUCTION_SET = "arm"
4271 4426
4272- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for 4427- ``run-postinsts`` no longer uses ``/etc/*-postinsts`` for
4273 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior 4428 ``dpkg/opkg`` in favor of built-in postinst support. RPM behavior
@@ -4385,10 +4540,11 @@ License Value Corrections
4385------------------------- 4540-------------------------
4386 4541
4387The following corrections have been made to the 4542The following corrections have been made to the
4388:term:`LICENSE` values set by recipes: *socat*: Corrected 4543:term:`LICENSE` values set by recipes:
4389``LICENSE`` to be "GPLv2" rather than "GPLv2+". *libgfortran*: Set 4544
4390license to "GPL-3.0-with-GCC-exception". *elfutils*: Removed 4545- *socat*: Corrected ``LICENSE`` to be "GPLv2" rather than "GPLv2+".
4391"Elfutils-Exception" and set to "GPLv2" for shared libraries 4546- *libgfortran*: Set license to "GPL-3.0-with-GCC-exception".
4547- *elfutils*: Removed "Elfutils-Exception" and set to "GPLv2" for shared libraries
4392 4548
4393.. _migration-2.7-packaging-changes: 4549.. _migration-2.7-packaging-changes:
4394 4550
@@ -4439,26 +4595,28 @@ This section provides information about packaging changes.
4439Removed Recipes 4595Removed Recipes
4440--------------- 4596---------------
4441 4597
4442The following recipes have been removed: *gcc*: Drop version 7.3 4598The following recipes have been removed:
4443recipes. Version 8.3 now remains. *linux-yocto*: Drop versions 4.14 and 4599
44444.18 recipes. Versions 4.19 and 5.0 remain. *go*: Drop version 1.9 4600- *gcc*: Drop version 7.3 recipes. Version 8.3 now remains.
4445recipes. Versions 1.11 and 1.12 remain. *xvideo-tests*: Became obsolete. 4601- *linux-yocto*: Drop versions 4.14 and 4.18 recipes. Versions 4.19 and 5.0 remain.
4446*libart-lgpl*: Became obsolete. *gtk-icon-utils-native*: These tools are 4602- *go*: Drop version 1.9 recipes. Versions 1.11 and 1.12 remain.
4447now provided by gtk+3-native *gcc-cross-initial*: No longer needed. 4603- *xvideo-tests*: Became obsolete.
4448gcc-cross/gcc-crosssdk is now used instead. *gcc-crosssdk-initial*: No 4604- *libart-lgpl*: Became obsolete.
4449longer needed. gcc-cross/gcc-crosssdk is now used instead. 4605- *gtk-icon-utils-native*: These tools are now provided by gtk+3-native
4450*glibc-initial*: Removed because the benefits of having it for 4606- *gcc-cross-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
4451site_config are currently outweighed by the cost of building the recipe. 4607- *gcc-crosssdk-initial*: No longer needed. gcc-cross/gcc-crosssdk is now used instead.
4608- *glibc-initial*: Removed because the benefits of having it for site_config are currently outweighed by the cost of building the recipe.
4452 4609
4453.. _migration-2.7-removed-classes: 4610.. _migration-2.7-removed-classes:
4454 4611
4455Removed Classes 4612Removed Classes
4456--------------- 4613---------------
4457 4614
4458The following classes have been removed: *distutils-tools*: This class 4615The following classes have been removed:
4459was never used. *bugzilla.bbclass*: Became obsolete. *distrodata*: This 4616
4460functionally has been replaced by a more modern tinfoil-based 4617- *distutils-tools*: This class was never used.
4461implementation. 4618- *bugzilla.bbclass*: Became obsolete.
4619- *distrodata*: This functionally has been replaced by a more modern tinfoil-based implementation.
4462 4620
4463.. _migration-2.7-miscellaneous-changes: 4621.. _migration-2.7-miscellaneous-changes:
4464 4622
@@ -4471,7 +4629,7 @@ The following miscellaneous changes occurred:
4471 from the top-level ``scripts`` directory. 4629 from the top-level ``scripts`` directory.
4472 4630
4473- Perl now builds for the target using 4631- Perl now builds for the target using
4474 ```perl-cross`http://arsv.github.io/perl-cross/ for better 4632 `perl-cross <http://arsv.github.io/perl-cross/>`_ for better
4475 maintainability and improved build performance. This change should 4633 maintainability and improved build performance. This change should
4476 not present any problems unless you have heavily customized your Perl 4634 not present any problems unless you have heavily customized your Perl
4477 recipe. 4635 recipe.
@@ -4883,7 +5041,9 @@ need runtime tests enabled for core components, then it is recommended
4883that you remove "ptest" from 5041that you remove "ptest" from
4884:term:`DISTRO_FEATURES` to save a significant 5042:term:`DISTRO_FEATURES` to save a significant
4885amount of build time e.g. by adding the following in your configuration: 5043amount of build time e.g. by adding the following in your configuration:
4886DISTRO_FEATURES_remove = "ptest" 5044::
5045
5046 DISTRO_FEATURES_remove = "ptest"
4887 5047
4888.. _migration-3.1-removed-recipes: 5048.. _migration-3.1-removed-recipes:
4889 5049
@@ -4988,12 +5148,15 @@ parameter instead of the earlier ``name`` which overlapped with the
4988generic ``name`` parameter. All recipes using the npm fetcher will need 5148generic ``name`` parameter. All recipes using the npm fetcher will need
4989to be changed as a result. 5149to be changed as a result.
4990 5150
4991An example of the new scheme: SRC_URI = 5151An example of the new scheme: ::
4992"npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \\ 5152
4993npmsw://${THISDIR}/npm-shrinkwrap.json" Another example where the 5153 SRC_URI = "npm://registry.npmjs.org;package=array-flatten;version=1.1.1 \
4994sources are fetched from git rather than an npm repository: SRC_URI = 5154 npmsw://${THISDIR}/npm-shrinkwrap.json"
4995"git://github.com/foo/bar.git;protocol=https \\ 5155
4996npmsw://${THISDIR}/npm-shrinkwrap.json" 5156Another example where the sources are fetched from git rather than an npm repository: ::
5157
5158 SRC_URI = "git://github.com/foo/bar.git;protocol=https \
5159 npmsw://${THISDIR}/npm-shrinkwrap.json"
4997 5160
4998devtool and recipetool have also been updated to match with the npm 5161devtool and recipetool have also been updated to match with the npm
4999fetcher changes. Other than producing working and more complete recipes 5162fetcher changes. Other than producing working and more complete recipes
diff --git a/documentation/ref-manual/ref-classes.rst b/documentation/ref-manual/ref-classes.rst
index ace69e15a7..60ce8efd21 100644
--- a/documentation/ref-manual/ref-classes.rst
+++ b/documentation/ref-manual/ref-classes.rst
@@ -47,7 +47,7 @@ splitting out of debug symbols during packaging).
47 even if the recipes do not produce architecture-specific output. 47 even if the recipes do not produce architecture-specific output.
48 48
49 Configuring such recipes for all architectures causes the 49 Configuring such recipes for all architectures causes the
50 ```do_package_write_*`` <#ref-tasks-package_write_deb>`__ tasks to 50 ```do_package_write_*`` tasks to
51 have different signatures for the machines with different tunings. 51 have different signatures for the machines with different tunings.
52 Additionally, unnecessary rebuilds occur every time an image for a 52 Additionally, unnecessary rebuilds occur every time an image for a
53 different ``MACHINE`` is built even when the recipe never changes. 53 different ``MACHINE`` is built even when the recipe never changes.
@@ -67,9 +67,8 @@ inherit the ``allarch`` class.
67The ``archiver`` class supports releasing source code and other 67The ``archiver`` class supports releasing source code and other
68materials with the binaries. 68materials with the binaries.
69 69
70For more details on the source archiver, see the "`Maintaining Open 70For more details on the source archiver, see the
71Source License Compliance During Your Product's 71":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
72Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
73section in the Yocto Project Development Tasks Manual. You can also see 72section in the Yocto Project Development Tasks Manual. You can also see
74the :term:`ARCHIVER_MODE` variable for information 73the :term:`ARCHIVER_MODE` variable for information
75about the variable flags (varflags) that help control archive creation. 74about the variable flags (varflags) that help control archive creation.
@@ -86,8 +85,8 @@ standardization. This class defines a set of tasks (e.g. ``configure``,
86``compile`` and so forth) that work for all Autotooled packages. It 85``compile`` and so forth) that work for all Autotooled packages. It
87should usually be enough to define a few standard variables and then 86should usually be enough to define a few standard variables and then
88simply ``inherit autotools``. These classes can also work with software 87simply ``inherit autotools``. These classes can also work with software
89that emulates Autotools. For more information, see the "`Autotooled 88that emulates Autotools. For more information, see the
90Package <&YOCTO_DOCS_DEV_URL;#new-recipe-autotooled-package>`__" section 89":ref:`new-recipe-autotooled-package`" section
91in the Yocto Project Development Tasks Manual. 90in the Yocto Project Development Tasks Manual.
92 91
93By default, the ``autotools*`` classes use out-of-tree builds (i.e. 92By default, the ``autotools*`` classes use out-of-tree builds (i.e.
@@ -177,7 +176,7 @@ example use for this class.
177 :: 176 ::
178 177
179 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}" 178 SRC_URI = "git://example.com/downloads/somepackage.rpm;subpath=${BP}"
180 179
181 180
182 See the " 181 See the "
183 Fetchers 182 Fetchers
@@ -229,8 +228,10 @@ value as a variable flag (varflag) and provide a reason, which is
229reported, if the package is requested to be built as the value. For 228reported, if the package is requested to be built as the value. For
230example, if you want to blacklist a recipe called "exoticware", you add 229example, if you want to blacklist a recipe called "exoticware", you add
231the following to your ``local.conf`` or distribution configuration: 230the following to your ``local.conf`` or distribution configuration:
232INHERIT += "blacklist" PNBLACKLIST[exoticware] = "Not supported by our 231::
233organization." 232
233 INHERIT += "blacklist"
234 PNBLACKLIST[exoticware] = "Not supported by our organization."
234 235
235.. _ref-classes-buildhistory: 236.. _ref-classes-buildhistory:
236 237
@@ -240,8 +241,8 @@ organization."
240The ``buildhistory`` class records a history of build output metadata, 241The ``buildhistory`` class records a history of build output metadata,
241which can be used to detect possible regressions as well as used for 242which can be used to detect possible regressions as well as used for
242analysis of the build output. For more information on using Build 243analysis of the build output. For more information on using Build
243History, see the "`Maintaining Build Output 244History, see the
244Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__" 245":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
245section in the Yocto Project Development Tasks Manual. 246section in the Yocto Project Development Tasks Manual.
246 247
247.. _ref-classes-buildstats: 248.. _ref-classes-buildstats:
@@ -411,8 +412,7 @@ cross-compilation tools.
411 412
412The ``cross-canadian`` class provides support for the recipes that build 413The ``cross-canadian`` class provides support for the recipes that build
413the Canadian Cross-compilation tools for SDKs. See the 414the Canadian Cross-compilation tools for SDKs. See the
414"`Cross-Development Toolchain 415":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
415Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
416section in the Yocto Project Overview and Concepts Manual for more 416section in the Yocto Project Overview and Concepts Manual for more
417discussion on these cross-compilation tools. 417discussion on these cross-compilation tools.
418 418
@@ -423,8 +423,7 @@ discussion on these cross-compilation tools.
423 423
424The ``crosssdk`` class provides support for the recipes that build the 424The ``crosssdk`` class provides support for the recipes that build the
425cross-compilation tools used for building SDKs. See the 425cross-compilation tools used for building SDKs. See the
426"`Cross-Development Toolchain 426":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
427Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
428section in the Yocto Project Overview and Concepts Manual for more 427section in the Yocto Project Overview and Concepts Manual for more
429discussion on these cross-compilation tools. 428discussion on these cross-compilation tools.
430 429
@@ -465,8 +464,7 @@ staging the files from ``DEPLOYDIR`` to ``DEPLOY_DIR_IMAGE``.
465==================== 464====================
466 465
467The ``devshell`` class adds the ``do_devshell`` task. Distribution 466The ``devshell`` class adds the ``do_devshell`` task. Distribution
468policy dictates whether to include this class. See the "`Using a 467policy dictates whether to include this class. See the ":ref:`platdev-appdev-devshell`"
469Development Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__"
470section in the Yocto Project Development Tasks Manual for more 468section in the Yocto Project Development Tasks Manual for more
471information about using ``devshell``. 469information about using ``devshell``.
472 470
@@ -478,16 +476,26 @@ information about using ``devshell``.
478The ``devupstream`` class uses 476The ``devupstream`` class uses
479:term:`BBCLASSEXTEND` to add a variant of the 477:term:`BBCLASSEXTEND` to add a variant of the
480recipe that fetches from an alternative URI (e.g. Git) instead of a 478recipe that fetches from an alternative URI (e.g. Git) instead of a
481tarball. Following is an example: BBCLASSEXTEND = "devupstream:target" 479tarball. Following is an example:
482SRC_URI_class-devupstream = "git://git.example.com/example" 480::
483SRCREV_class-devupstream = "abcd1234" Adding the above statements to 481
484your recipe creates a variant that has 482 BBCLASSEXTEND = "devupstream:target"
483 SRC_URI_class-devupstream = "git://git.example.com/example"
484 SRCREV_class-devupstream = "abcd1234"
485
486Adding the above statements to your recipe creates a variant that has
485:term:`DEFAULT_PREFERENCE` set to "-1". 487:term:`DEFAULT_PREFERENCE` set to "-1".
486Consequently, you need to select the variant of the recipe to use it. 488Consequently, you need to select the variant of the recipe to use it.
487Any development-specific adjustments can be done by using the 489Any development-specific adjustments can be done by using the
488``class-devupstream`` override. Here is an example: 490``class-devupstream`` override. Here is an example:
489DEPENDS_append_class-devupstream = " gperf-native" 491::
490do_configure_prepend_class-devupstream() { touch ${S}/README } The class 492
493 DEPENDS_append_class-devupstream = " gperf-native"
494 do_configure_prepend_class-devupstream() {
495 touch ${S}/README
496 }
497
498The class
491currently only supports creating a development variant of the target 499currently only supports creating a development variant of the target
492recipe, not ``native`` or ``nativesdk`` variants. 500recipe, not ``native`` or ``nativesdk`` variants.
493 501
@@ -587,15 +595,19 @@ that use the :term:`B` variable to point to the directory in
587which the OpenEmbedded build system places the generated objects built 595which the OpenEmbedded build system places the generated objects built
588from the recipes. By default, the ``B`` directory is set to the 596from the recipes. By default, the ``B`` directory is set to the
589following, which is separate from the source directory (``S``): 597following, which is separate from the source directory (``S``):
590${WORKDIR}/${BPN}/{PV}/ See these variables for more information: 598::
599
600 ${WORKDIR}/${BPN}/{PV}/
601
602See these variables for more information:
591:term:`WORKDIR`, :term:`BPN`, and 603:term:`WORKDIR`, :term:`BPN`, and
592:term:`PV`, 604:term:`PV`,
593 605
594For more information on the ``externalsrc`` class, see the comments in 606For more information on the ``externalsrc`` class, see the comments in
595``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`. 607``meta/classes/externalsrc.bbclass`` in the :term:`Source Directory`.
596For information on how to use the 608For information on how to use the
597``externalsrc`` class, see the "`Building Software from an External 609``externalsrc`` class, see the
598Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__" 610":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`"
599section in the Yocto Project Development Tasks Manual. 611section in the Yocto Project Development Tasks Manual.
600 612
601.. _ref-classes-extrausers: 613.. _ref-classes-extrausers:
@@ -619,15 +631,36 @@ be performed using the
619 useradd 631 useradd
620 class to add user and group configuration to a specific recipe. 632 class to add user and group configuration to a specific recipe.
621 633
622Here is an example that uses this class in an image recipe: inherit 634Here is an example that uses this class in an image recipe:
623extrausers EXTRA_USERS_PARAMS = "\\ useradd -p '' tester; \\ groupadd 635::
624developers; \\ userdel nobody; \\ groupdel -g video; \\ groupmod -g 1020 636
625developers; \\ usermod -s /bin/sh tester; \\ " Here is an example that 637 inherit extrausers
626adds two users named "tester-jim" and "tester-sue" and assigns 638 EXTRA_USERS_PARAMS = "\
627passwords: inherit extrausers EXTRA_USERS_PARAMS = "\\ useradd -P 639 useradd -p '' tester; \
628tester01 tester-jim; \\ useradd -P tester01 tester-sue; \\ " Finally, 640 groupadd developers; \
629here is an example that sets the root password to "1876*18": inherit 641 userdel nobody; \
630extrausers EXTRA_USERS_PARAMS = "\\ usermod -P 1876*18 root; \\ " 642 groupdel -g video; \
643 groupmod -g 1020 developers; \
644 usermod -s /bin/sh tester; \
645 "
646
647Here is an example that adds two users named "tester-jim" and "tester-sue" and assigns
648passwords:
649::
650
651 inherit extrausers
652 EXTRA_USERS_PARAMS = "\
653 useradd -P tester01 tester-jim; \
654 useradd -P tester01 tester-sue; \
655 "
656
657Finally, here is an example that sets the root password to "1876*18":
658::
659
660 inherit extrausers
661 EXTRA_USERS_PARAMS = "\
662 usermod -P 1876*18 root; \
663 "
631 664
632.. _ref-classes-fontcache: 665.. _ref-classes-fontcache:
633 666
@@ -837,8 +870,7 @@ provided by the recipe ``icecc-create-env-native.bb``.
837.. note:: 870.. note::
838 871
839 This script is a modified version and not the one that comes with 872 This script is a modified version and not the one that comes with
840 icecc 873 icecc.
841 .
842 874
843If you do not want the Icecream distributed compile support to apply to 875If you do not want the Icecream distributed compile support to apply to
844specific recipes or classes, you can effectively "blacklist" them by 876specific recipes or classes, you can effectively "blacklist" them by
@@ -863,10 +895,18 @@ At the distribution level, you can inherit the ``icecc`` class to be
863sure that all builders start with the same sstate signatures. After 895sure that all builders start with the same sstate signatures. After
864inheriting the class, you can then disable the feature by setting the 896inheriting the class, you can then disable the feature by setting the
865:term:`ICECC_DISABLED` variable to "1" as follows: 897:term:`ICECC_DISABLED` variable to "1" as follows:
866INHERIT_DISTRO_append = " icecc" ICECC_DISABLED ??= "1" This practice 898::
899
900 INHERIT_DISTRO_append = " icecc"
901 ICECC_DISABLED ??= "1"
902
903This practice
867makes sure everyone is using the same signatures but also requires 904makes sure everyone is using the same signatures but also requires
868individuals that do want to use Icecream to enable the feature 905individuals that do want to use Icecream to enable the feature
869individually as follows in your ``local.conf`` file: ICECC_DISABLED = "" 906individually as follows in your ``local.conf`` file:
907::
908
909 ICECC_DISABLED = ""
870 910
871.. _ref-classes-image: 911.. _ref-classes-image:
872 912
@@ -884,11 +924,11 @@ then one or more image files are created.
884- The ``IMAGE_INSTALL`` variable controls the list of packages to 924- The ``IMAGE_INSTALL`` variable controls the list of packages to
885 install into the image. 925 install into the image.
886 926
887For information on customizing images, see the "`Customizing 927For information on customizing images, see the
888Images <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage>`__" section 928":ref:`usingpoky-extend-customimage`" section
889in the Yocto Project Development Tasks Manual. For information on how 929in the Yocto Project Development Tasks Manual. For information on how
890images are created, see the 930images are created, see the
891"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" section in the 931":ref:`images-dev-environment`" section in the
892Yocto Project Overview and Concpets Manual. 932Yocto Project Overview and Concpets Manual.
893 933
894.. _ref-classes-image-buildinfo: 934.. _ref-classes-image-buildinfo:
@@ -912,19 +952,19 @@ types.
912 952
913By default, the :ref:`image <ref-classes-image>` class automatically 953By default, the :ref:`image <ref-classes-image>` class automatically
914enables the ``image_types`` class. The ``image`` class uses the 954enables the ``image_types`` class. The ``image`` class uses the
915``IMGCLASSES`` variable as follows: IMGCLASSES = 955``IMGCLASSES`` variable as follows:
916"rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}" IMGCLASSES += 956::
917"${@['populate_sdk_base', 'populate_sdk_ext']['linux' in 957
918d.getVar("SDK_OS")]}" IMGCLASSES += 958 IMGCLASSES = "rootfs_${IMAGE_PKGTYPE} image_types ${IMAGE_CLASSES}"
919"${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 959 IMGCLASSES += "${@['populate_sdk_base', 'populate_sdk_ext']['linux' in d.getVar("SDK_OS")]}"
920'image-live', '', d)}" IMGCLASSES += 960 IMGCLASSES += "${@bb.utils.contains_any('IMAGE_FSTYPES', 'live iso hddimg', 'image-live', '', d)}"
921"${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', 961 IMGCLASSES += "${@bb.utils.contains('IMAGE_FSTYPES', 'container', 'image-container', '', d)}"
922'', d)}" IMGCLASSES += "image_types_wic" IMGCLASSES += 962 IMGCLASSES += "image_types_wic"
923"rootfs-postcommands" IMGCLASSES += "image-postinst-intercepts" inherit 963 IMGCLASSES += "rootfs-postcommands"
924${IMGCLASSES} 964 IMGCLASSES += "image-postinst-intercepts"
925 965 inherit ${IMGCLASSES}
926The ``image_types`` class also handles conversion and compression of 966
927images. 967The ``image_types`` class also handles conversion and compression of images.
928 968
929.. note:: 969.. note::
930 970
@@ -957,7 +997,9 @@ the size of libraries contained in the image.
957 997
958By default, the class is enabled in the ``local.conf.template`` using 998By default, the class is enabled in the ``local.conf.template`` using
959the :term:`USER_CLASSES` variable as follows: 999the :term:`USER_CLASSES` variable as follows:
960USER_CLASSES ?= "buildstats image-mklibs image-prelink" 1000::
1001
1002 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
961 1003
962.. _ref-classes-image-prelink: 1004.. _ref-classes-image-prelink:
963 1005
@@ -971,7 +1013,9 @@ time.
971 1013
972By default, the class is enabled in the ``local.conf.template`` using 1014By default, the class is enabled in the ``local.conf.template`` using
973the :term:`USER_CLASSES` variable as follows: 1015the :term:`USER_CLASSES` variable as follows:
974USER_CLASSES ?= "buildstats image-mklibs image-prelink" 1016::
1017
1018 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
975 1019
976.. _ref-classes-insane: 1020.. _ref-classes-insane:
977 1021
@@ -1000,32 +1044,36 @@ should use :term:`INSANE_SKIP`. For example, to skip
1000the check for symbolic link ``.so`` files in the main package of a 1044the check for symbolic link ``.so`` files in the main package of a
1001recipe, add the following to the recipe. You need to realize that the 1045recipe, add the following to the recipe. You need to realize that the
1002package name override, in this example ``${PN}``, must be used: 1046package name override, in this example ``${PN}``, must be used:
1003INSANE_SKIP_${PN} += "dev-so" Please keep in mind that the QA checks 1047::
1048
1049 INSANE_SKIP_${PN} += "dev-so"
1050
1051Please keep in mind that the QA checks
1004exist in order to detect real or potential problems in the packaged 1052exist in order to detect real or potential problems in the packaged
1005output. So exercise caution when disabling these checks. 1053output. So exercise caution when disabling these checks.
1006 1054
1007The following list shows the tests you can list with the ``WARN_QA`` and 1055The following list shows the tests you can list with the ``WARN_QA`` and
1008``ERROR_QA`` variables: 1056``ERROR_QA`` variables:
1009 1057
1010- *``already-stripped:``* Checks that produced binaries have not 1058- ``already-stripped:`` Checks that produced binaries have not
1011 already been stripped prior to the build system extracting debug 1059 already been stripped prior to the build system extracting debug
1012 symbols. It is common for upstream software projects to default to 1060 symbols. It is common for upstream software projects to default to
1013 stripping debug symbols for output binaries. In order for debugging 1061 stripping debug symbols for output binaries. In order for debugging
1014 to work on the target using ``-dbg`` packages, this stripping must be 1062 to work on the target using ``-dbg`` packages, this stripping must be
1015 disabled. 1063 disabled.
1016 1064
1017- *``arch:``* Checks the Executable and Linkable Format (ELF) type, bit 1065- ``arch:`` Checks the Executable and Linkable Format (ELF) type, bit
1018 size, and endianness of any binaries to ensure they match the target 1066 size, and endianness of any binaries to ensure they match the target
1019 architecture. This test fails if any binaries do not match the type 1067 architecture. This test fails if any binaries do not match the type
1020 since there would be an incompatibility. The test could indicate that 1068 since there would be an incompatibility. The test could indicate that
1021 the wrong compiler or compiler options have been used. Sometimes 1069 the wrong compiler or compiler options have been used. Sometimes
1022 software, like bootloaders, might need to bypass this check. 1070 software, like bootloaders, might need to bypass this check.
1023 1071
1024- *``buildpaths:``* Checks for paths to locations on the build host 1072- ``buildpaths:`` Checks for paths to locations on the build host
1025 inside the output files. Currently, this test triggers too many false 1073 inside the output files. Currently, this test triggers too many false
1026 positives and thus is not normally enabled. 1074 positives and thus is not normally enabled.
1027 1075
1028- *``build-deps:``* Determines if a build-time dependency that is 1076- ``build-deps:`` Determines if a build-time dependency that is
1029 specified through :term:`DEPENDS`, explicit 1077 specified through :term:`DEPENDS`, explicit
1030 :term:`RDEPENDS`, or task-level dependencies exists 1078 :term:`RDEPENDS`, or task-level dependencies exists
1031 to match any runtime dependency. This determination is particularly 1079 to match any runtime dependency. This determination is particularly
@@ -1045,20 +1093,20 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1045 ``initscripts`` recipe is actually built and thus the 1093 ``initscripts`` recipe is actually built and thus the
1046 ``initscripts-functions`` package is made available. 1094 ``initscripts-functions`` package is made available.
1047 1095
1048- *``compile-host-path:``* Checks the 1096- ``compile-host-path:`` Checks the
1049 :ref:`ref-tasks-compile` log for indications that 1097 :ref:`ref-tasks-compile` log for indications that
1050 paths to locations on the build host were used. Using such paths 1098 paths to locations on the build host were used. Using such paths
1051 might result in host contamination of the build output. 1099 might result in host contamination of the build output.
1052 1100
1053- *``debug-deps:``* Checks that all packages except ``-dbg`` packages 1101- ``debug-deps:`` Checks that all packages except ``-dbg`` packages
1054 do not depend on ``-dbg`` packages, which would cause a packaging 1102 do not depend on ``-dbg`` packages, which would cause a packaging
1055 bug. 1103 bug.
1056 1104
1057- *``debug-files:``* Checks for ``.debug`` directories in anything but 1105- ``debug-files:`` Checks for ``.debug`` directories in anything but
1058 the ``-dbg`` package. The debug files should all be in the ``-dbg`` 1106 the ``-dbg`` package. The debug files should all be in the ``-dbg``
1059 package. Thus, anything packaged elsewhere is incorrect packaging. 1107 package. Thus, anything packaged elsewhere is incorrect packaging.
1060 1108
1061- *``dep-cmp:``* Checks for invalid version comparison statements in 1109- ``dep-cmp:`` Checks for invalid version comparison statements in
1062 runtime dependency relationships between packages (i.e. in 1110 runtime dependency relationships between packages (i.e. in
1063 :term:`RDEPENDS`, 1111 :term:`RDEPENDS`,
1064 :term:`RRECOMMENDS`, 1112 :term:`RRECOMMENDS`,
@@ -1069,22 +1117,22 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1069 comparisons might trigger failures or undesirable behavior when 1117 comparisons might trigger failures or undesirable behavior when
1070 passed to the package manager. 1118 passed to the package manager.
1071 1119
1072- *``desktop:``* Runs the ``desktop-file-validate`` program against any 1120- ``desktop:`` Runs the ``desktop-file-validate`` program against any
1073 ``.desktop`` files to validate their contents against the 1121 ``.desktop`` files to validate their contents against the
1074 specification for ``.desktop`` files. 1122 specification for ``.desktop`` files.
1075 1123
1076- *``dev-deps:``* Checks that all packages except ``-dev`` or 1124- ``dev-deps:`` Checks that all packages except ``-dev`` or
1077 ``-staticdev`` packages do not depend on ``-dev`` packages, which 1125 ``-staticdev`` packages do not depend on ``-dev`` packages, which
1078 would be a packaging bug. 1126 would be a packaging bug.
1079 1127
1080- *``dev-so:``* Checks that the ``.so`` symbolic links are in the 1128- ``dev-so:`` Checks that the ``.so`` symbolic links are in the
1081 ``-dev`` package and not in any of the other packages. In general, 1129 ``-dev`` package and not in any of the other packages. In general,
1082 these symlinks are only useful for development purposes. Thus, the 1130 these symlinks are only useful for development purposes. Thus, the
1083 ``-dev`` package is the correct location for them. Some very rare 1131 ``-dev`` package is the correct location for them. Some very rare
1084 cases do exist for dynamically loaded modules where these symlinks 1132 cases do exist for dynamically loaded modules where these symlinks
1085 are needed instead in the main package. 1133 are needed instead in the main package.
1086 1134
1087- *``file-rdeps:``* Checks that file-level dependencies identified by 1135- ``file-rdeps:`` Checks that file-level dependencies identified by
1088 the OpenEmbedded build system at packaging time are satisfied. For 1136 the OpenEmbedded build system at packaging time are satisfied. For
1089 example, a shell script might start with the line ``#!/bin/bash``. 1137 example, a shell script might start with the line ``#!/bin/bash``.
1090 This line would translate to a file dependency on ``/bin/bash``. Of 1138 This line would translate to a file dependency on ``/bin/bash``. Of
@@ -1097,10 +1145,10 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1097 :term:`RDEPENDS` exist to handle any file-level 1145 :term:`RDEPENDS` exist to handle any file-level
1098 dependency detected in packaged files. 1146 dependency detected in packaged files.
1099 1147
1100- *``files-invalid:``* Checks for :term:`FILES` variable 1148- ``files-invalid:`` Checks for :term:`FILES` variable
1101 values that contain "//", which is invalid. 1149 values that contain "//", which is invalid.
1102 1150
1103- *``host-user-contaminated:``* Checks that no package produced by the 1151- ``host-user-contaminated:`` Checks that no package produced by the
1104 recipe contains any files outside of ``/home`` with a user or group 1152 recipe contains any files outside of ``/home`` with a user or group
1105 ID that matches the user running BitBake. A match usually indicates 1153 ID that matches the user running BitBake. A match usually indicates
1106 that the files are being installed with an incorrect UID/GID, since 1154 that the files are being installed with an incorrect UID/GID, since
@@ -1108,16 +1156,16 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1108 see the section describing the 1156 see the section describing the
1109 :ref:`ref-tasks-install` task. 1157 :ref:`ref-tasks-install` task.
1110 1158
1111- *``incompatible-license:``* Report when packages are excluded from 1159- ``incompatible-license:`` Report when packages are excluded from
1112 being created due to being marked with a license that is in 1160 being created due to being marked with a license that is in
1113 :term:`INCOMPATIBLE_LICENSE`. 1161 :term:`INCOMPATIBLE_LICENSE`.
1114 1162
1115- *``install-host-path:``* Checks the 1163- ``install-host-path:`` Checks the
1116 :ref:`ref-tasks-install` log for indications that 1164 :ref:`ref-tasks-install` log for indications that
1117 paths to locations on the build host were used. Using such paths 1165 paths to locations on the build host were used. Using such paths
1118 might result in host contamination of the build output. 1166 might result in host contamination of the build output.
1119 1167
1120- *``installed-vs-shipped:``* Reports when files have been installed 1168- ``installed-vs-shipped:`` Reports when files have been installed
1121 within ``do_install`` but have not been included in any package by 1169 within ``do_install`` but have not been included in any package by
1122 way of the :term:`FILES` variable. Files that do not 1170 way of the :term:`FILES` variable. Files that do not
1123 appear in any package cannot be present in an image later on in the 1171 appear in any package cannot be present in an image later on in the
@@ -1125,67 +1173,69 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1125 installed at all. These files can be deleted at the end of 1173 installed at all. These files can be deleted at the end of
1126 ``do_install`` if the files are not needed in any package. 1174 ``do_install`` if the files are not needed in any package.
1127 1175
1128- *``invalid-chars:``* Checks that the recipe metadata variables 1176- ``invalid-chars:`` Checks that the recipe metadata variables
1129 :term:`DESCRIPTION`, 1177 :term:`DESCRIPTION`,
1130 :term:`SUMMARY`, :term:`LICENSE`, and 1178 :term:`SUMMARY`, :term:`LICENSE`, and
1131 :term:`SECTION` do not contain non-UTF-8 characters. 1179 :term:`SECTION` do not contain non-UTF-8 characters.
1132 Some package managers do not support such characters. 1180 Some package managers do not support such characters.
1133 1181
1134- *``invalid-packageconfig:``* Checks that no undefined features are 1182- ``invalid-packageconfig:`` Checks that no undefined features are
1135 being added to :term:`PACKAGECONFIG`. For 1183 being added to :term:`PACKAGECONFIG`. For
1136 example, any name "foo" for which the following form does not exist: 1184 example, any name "foo" for which the following form does not exist:
1137 PACKAGECONFIG[foo] = "..." 1185 ::
1186
1187 PACKAGECONFIG[foo] = "..."
1138 1188
1139- *``la:``* Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la`` 1189- ``la:`` Checks ``.la`` files for any ``TMPDIR`` paths. Any ``.la``
1140 file containing these paths is incorrect since ``libtool`` adds the 1190 file containing these paths is incorrect since ``libtool`` adds the
1141 correct sysroot prefix when using the files automatically itself. 1191 correct sysroot prefix when using the files automatically itself.
1142 1192
1143- *``ldflags:``* Ensures that the binaries were linked with the 1193- ``ldflags:`` Ensures that the binaries were linked with the
1144 :term:`LDFLAGS` options provided by the build system. 1194 :term:`LDFLAGS` options provided by the build system.
1145 If this test fails, check that the ``LDFLAGS`` variable is being 1195 If this test fails, check that the ``LDFLAGS`` variable is being
1146 passed to the linker command. 1196 passed to the linker command.
1147 1197
1148- *``libdir:``* Checks for libraries being installed into incorrect 1198- ``libdir:`` Checks for libraries being installed into incorrect
1149 (possibly hardcoded) installation paths. For example, this test will 1199 (possibly hardcoded) installation paths. For example, this test will
1150 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is 1200 catch recipes that install ``/lib/bar.so`` when ``${base_libdir}`` is
1151 "lib32". Another example is when recipes install 1201 "lib32". Another example is when recipes install
1152 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib". 1202 ``/usr/lib64/foo.so`` when ``${libdir}`` is "/usr/lib".
1153 1203
1154- *``libexec:``* Checks if a package contains files in 1204- ``libexec:`` Checks if a package contains files in
1155 ``/usr/libexec``. This check is not performed if the ``libexecdir`` 1205 ``/usr/libexec``. This check is not performed if the ``libexecdir``
1156 variable has been set explicitly to ``/usr/libexec``. 1206 variable has been set explicitly to ``/usr/libexec``.
1157 1207
1158- *``packages-list:``* Checks for the same package being listed 1208- ``packages-list:`` Checks for the same package being listed
1159 multiple times through the :term:`PACKAGES` variable 1209 multiple times through the :term:`PACKAGES` variable
1160 value. Installing the package in this manner can cause errors during 1210 value. Installing the package in this manner can cause errors during
1161 packaging. 1211 packaging.
1162 1212
1163- *``perm-config:``* Reports lines in ``fs-perms.txt`` that have an 1213- ``perm-config:`` Reports lines in ``fs-perms.txt`` that have an
1164 invalid format. 1214 invalid format.
1165 1215
1166- *``perm-line:``* Reports lines in ``fs-perms.txt`` that have an 1216- ``perm-line:`` Reports lines in ``fs-perms.txt`` that have an
1167 invalid format. 1217 invalid format.
1168 1218
1169- *``perm-link:``* Reports lines in ``fs-perms.txt`` that specify 1219- ``perm-link:`` Reports lines in ``fs-perms.txt`` that specify
1170 'link' where the specified target already exists. 1220 'link' where the specified target already exists.
1171 1221
1172- *``perms:``* Currently, this check is unused but reserved. 1222- ``perms:`` Currently, this check is unused but reserved.
1173 1223
1174- *``pkgconfig:``* Checks ``.pc`` files for any 1224- ``pkgconfig:`` Checks ``.pc`` files for any
1175 :term:`TMPDIR`/:term:`WORKDIR` paths. 1225 :term:`TMPDIR`/:term:`WORKDIR` paths.
1176 Any ``.pc`` file containing these paths is incorrect since 1226 Any ``.pc`` file containing these paths is incorrect since
1177 ``pkg-config`` itself adds the correct sysroot prefix when the files 1227 ``pkg-config`` itself adds the correct sysroot prefix when the files
1178 are accessed. 1228 are accessed.
1179 1229
1180- *``pkgname:``* Checks that all packages in 1230- ``pkgname:`` Checks that all packages in
1181 :term:`PACKAGES` have names that do not contain 1231 :term:`PACKAGES` have names that do not contain
1182 invalid characters (i.e. characters other than 0-9, a-z, ., +, and 1232 invalid characters (i.e. characters other than 0-9, a-z, ., +, and
1183 -). 1233 -).
1184 1234
1185- *``pkgv-undefined:``* Checks to see if the ``PKGV`` variable is 1235- ``pkgv-undefined:`` Checks to see if the ``PKGV`` variable is
1186 undefined during :ref:`ref-tasks-package`. 1236 undefined during :ref:`ref-tasks-package`.
1187 1237
1188- *``pkgvarcheck:``* Checks through the variables 1238- ``pkgvarcheck:`` Checks through the variables
1189 :term:`RDEPENDS`, 1239 :term:`RDEPENDS`,
1190 :term:`RRECOMMENDS`, 1240 :term:`RRECOMMENDS`,
1191 :term:`RSUGGESTS`, 1241 :term:`RSUGGESTS`,
@@ -1199,7 +1249,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1199 unnecessarily complicate dependencies of other packages within the 1249 unnecessarily complicate dependencies of other packages within the
1200 same recipe or have other unintended consequences. 1250 same recipe or have other unintended consequences.
1201 1251
1202- *``pn-overrides:``* Checks that a recipe does not have a name 1252- ``pn-overrides:`` Checks that a recipe does not have a name
1203 (:term:`PN`) value that appears in 1253 (:term:`PN`) value that appears in
1204 :term:`OVERRIDES`. If a recipe is named such that 1254 :term:`OVERRIDES`. If a recipe is named such that
1205 its ``PN`` value matches something already in ``OVERRIDES`` (e.g. 1255 its ``PN`` value matches something already in ``OVERRIDES`` (e.g.
@@ -1208,43 +1258,43 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1208 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively 1258 For example, assignments such as ``FILES_${PN} = "xyz"`` effectively
1209 turn into ``FILES = "xyz"``. 1259 turn into ``FILES = "xyz"``.
1210 1260
1211- *``rpaths:``* Checks for rpaths in the binaries that contain build 1261- ``rpaths:`` Checks for rpaths in the binaries that contain build
1212 system paths such as ``TMPDIR``. If this test fails, bad ``-rpath`` 1262 system paths such as ``TMPDIR``. If this test fails, bad ``-rpath``
1213 options are being passed to the linker commands and your binaries 1263 options are being passed to the linker commands and your binaries
1214 have potential security issues. 1264 have potential security issues.
1215 1265
1216- *``split-strip:``* Reports that splitting or stripping debug symbols 1266- ``split-strip:`` Reports that splitting or stripping debug symbols
1217 from binaries has failed. 1267 from binaries has failed.
1218 1268
1219- *``staticdev:``* Checks for static library files (``*.a``) in 1269- ``staticdev:`` Checks for static library files (``*.a``) in
1220 non-``staticdev`` packages. 1270 non-``staticdev`` packages.
1221 1271
1222- *``symlink-to-sysroot:``* Checks for symlinks in packages that point 1272- ``symlink-to-sysroot:`` Checks for symlinks in packages that point
1223 into :term:`TMPDIR` on the host. Such symlinks will 1273 into :term:`TMPDIR` on the host. Such symlinks will
1224 work on the host, but are clearly invalid when running on the target. 1274 work on the host, but are clearly invalid when running on the target.
1225 1275
1226- *``textrel:``* Checks for ELF binaries that contain relocations in 1276- ``textrel:`` Checks for ELF binaries that contain relocations in
1227 their ``.text`` sections, which can result in a performance impact at 1277 their ``.text`` sections, which can result in a performance impact at
1228 runtime. See the explanation for the 1278 runtime. See the explanation for the
1229 ```ELF binary`` <#qa-issue-textrel>`__ message for more information 1279 ```ELF binary`` <#qa-issue-textrel>`__ message for more information
1230 regarding runtime performance issues. 1280 regarding runtime performance issues.
1231 1281
1232- *``unlisted-pkg-lics:``* Checks that all declared licenses applying 1282- ``unlisted-pkg-lics:`` Checks that all declared licenses applying
1233 for a package are also declared on the recipe level (i.e. any license 1283 for a package are also declared on the recipe level (i.e. any license
1234 in ``LICENSE_*`` should appear in :term:`LICENSE`). 1284 in ``LICENSE_*`` should appear in :term:`LICENSE`).
1235 1285
1236- *``useless-rpaths:``* Checks for dynamic library load paths (rpaths) 1286- ``useless-rpaths:`` Checks for dynamic library load paths (rpaths)
1237 in the binaries that by default on a standard system are searched by 1287 in the binaries that by default on a standard system are searched by
1238 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will 1288 the linker (e.g. ``/lib`` and ``/usr/lib``). While these paths will
1239 not cause any breakage, they do waste space and are unnecessary. 1289 not cause any breakage, they do waste space and are unnecessary.
1240 1290
1241- *``var-undefined:``* Reports when variables fundamental to packaging 1291- ``var-undefined:`` Reports when variables fundamental to packaging
1242 (i.e. :term:`WORKDIR`, 1292 (i.e. :term:`WORKDIR`,
1243 :term:`DEPLOY_DIR`, :term:`D`, 1293 :term:`DEPLOY_DIR`, :term:`D`,
1244 :term:`PN`, and :term:`PKGD`) are undefined 1294 :term:`PN`, and :term:`PKGD`) are undefined
1245 during :ref:`ref-tasks-package`. 1295 during :ref:`ref-tasks-package`.
1246 1296
1247- *``version-going-backwards:``* If Build History is enabled, reports 1297- ``version-going-backwards:`` If Build History is enabled, reports
1248 when a package being written out has a lower version than the 1298 when a package being written out has a lower version than the
1249 previously written package under the same name. If you are placing 1299 previously written package under the same name. If you are placing
1250 output packages into a feed and upgrading packages on a target system 1300 output packages into a feed and upgrading packages on a target system
@@ -1257,7 +1307,7 @@ The following list shows the tests you can list with the ``WARN_QA`` and
1257 If you are not using runtime package management on your target 1307 If you are not using runtime package management on your target
1258 system, then you do not need to worry about this situation. 1308 system, then you do not need to worry about this situation.
1259 1309
1260- *``xorg-driver-abi:``* Checks that all packages containing Xorg 1310- ``xorg-driver-abi:`` Checks that all packages containing Xorg
1261 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides 1311 drivers have ABI dependencies. The ``xserver-xorg`` recipe provides
1262 driver ABI names. All drivers should depend on the ABI versions that 1312 driver ABI names. All drivers should depend on the ABI versions that
1263 they have been built against. Driver recipes that include 1313 they have been built against. Driver recipes that include
@@ -1293,9 +1343,8 @@ packages such as ``kernel-vmlinux``.
1293 1343
1294The ``kernel`` class contains logic that allows you to embed an initial 1344The ``kernel`` class contains logic that allows you to embed an initial
1295RAM filesystem (initramfs) image when you build the kernel image. For 1345RAM filesystem (initramfs) image when you build the kernel image. For
1296information on how to build an initramfs, see the "`Building an Initial 1346information on how to build an initramfs, see the
1297RAM Filesystem (initramfs) 1347":ref:`building-an-initramfs-image`" section in
1298Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section in
1299the Yocto Project Development Tasks Manual. 1348the Yocto Project Development Tasks Manual.
1300 1349
1301Various other classes are used by the ``kernel`` and ``module`` classes 1350Various other classes are used by the ``kernel`` and ``module`` classes
@@ -1545,8 +1594,7 @@ and implements the :ref:`ref-tasks-compile` and
1545everything needed to build and package a kernel module. 1594everything needed to build and package a kernel module.
1546 1595
1547For general information on out-of-tree Linux kernel modules, see the 1596For general information on out-of-tree Linux kernel modules, see the
1548"`Incorporating Out-of-Tree 1597":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`"
1549Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__"
1550section in the Yocto Project Linux Kernel Development Manual. 1598section in the Yocto Project Linux Kernel Development Manual.
1551 1599
1552.. _ref-classes-module-base: 1600.. _ref-classes-module-base:
@@ -1569,9 +1617,8 @@ The ``multilib*`` classes provide support for building libraries with
1569different target optimizations or target architectures and installing 1617different target optimizations or target architectures and installing
1570them side-by-side in the same image. 1618them side-by-side in the same image.
1571 1619
1572For more information on using the Multilib feature, see the "`Combining 1620For more information on using the Multilib feature, see the
1573Multiple Versions of Library Files into One 1621":ref:`combining-multiple-versions-library-files-into-one-image`"
1574Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__"
1575section in the Yocto Project Development Tasks Manual. 1622section in the Yocto Project Development Tasks Manual.
1576 1623
1577.. _ref-classes-native: 1624.. _ref-classes-native:
@@ -1597,14 +1644,18 @@ a couple different ways:
1597 naming convention: 1644 naming convention:
1598 :: 1645 ::
1599 1646
1600 myrecipe-native.bb 1647 myrecipe-native.bb
1601 1648
1602 1649
1603 Not using this naming convention can lead to subtle problems 1650 Not using this naming convention can lead to subtle problems
1604 caused by existing code that depends on that naming convention. 1651 caused by existing code that depends on that naming convention.
1605 1652
1606- Create or modify a target recipe that contains the following: 1653- Create or modify a target recipe that contains the following:
1607 :term:`BBCLASSEXTEND` = "native" Inside the 1654 ::
1655
1656 BBCLASSEXTEND = "native"
1657
1658 Inside the
1608 recipe, use ``_class-native`` and ``_class-target`` overrides to 1659 recipe, use ``_class-native`` and ``_class-target`` overrides to
1609 specify any functionality specific to the respective native or target 1660 specify any functionality specific to the respective native or target
1610 case. 1661 case.
@@ -1632,7 +1683,11 @@ couple different ways:
1632 that the ``nativesdk`` class is inherited last. 1683 that the ``nativesdk`` class is inherited last.
1633 1684
1634- Create a ``nativesdk`` variant of any recipe by adding the following: 1685- Create a ``nativesdk`` variant of any recipe by adding the following:
1635 :term:`BBCLASSEXTEND` = "nativesdk" Inside the 1686 ::
1687
1688 BBCLASSEXTEND = "nativesdk"
1689
1690 Inside the
1636 recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to 1691 recipe, use ``_class-nativesdk`` and ``_class-target`` overrides to
1637 specify any functionality specific to the respective SDK machine or 1692 specify any functionality specific to the respective SDK machine or
1638 target case. 1693 target case.
@@ -1643,7 +1698,7 @@ couple different ways:
1643 :: 1698 ::
1644 1699
1645 nativesdk-myrecipe.bb 1700 nativesdk-myrecipe.bb
1646 1701
1647 1702
1648 Not doing so can lead to subtle problems because code exists that 1703 Not doing so can lead to subtle problems because code exists that
1649 depends on the naming convention. 1704 depends on the naming convention.
@@ -1675,9 +1730,8 @@ package manager (NPM) <https://en.wikipedia.org/wiki/Npm_(software)>`__.
1675 npm:// 1730 npm://
1676 fetcher to have dependencies fetched and packaged automatically. 1731 fetcher to have dependencies fetched and packaged automatically.
1677 1732
1678For information on how to create NPM packages, see the "`Creating Node 1733For information on how to create NPM packages, see the
1679Package Manager (NPM) 1734":ref:`dev-manual/dev-manual-common-tasks:creating node package manager (npm) packages`"
1680Packages <&YOCTO_DOCS_DEV_URL;#creating-node-package-manager-npm-packages>`__"
1681section in the Yocto Project Development Tasks Manual. 1735section in the Yocto Project Development Tasks Manual.
1682 1736
1683.. _ref-classes-oelint: 1737.. _ref-classes-oelint:
@@ -1706,8 +1760,12 @@ before attempting to fetch it from the upstream specified in
1706 1760
1707To use this class, inherit it globally and specify 1761To use this class, inherit it globally and specify
1708:term:`SOURCE_MIRROR_URL`. Here is an example: 1762:term:`SOURCE_MIRROR_URL`. Here is an example:
1709INHERIT += "own-mirrors" SOURCE_MIRROR_URL = 1763::
1710"http://example.com/my-source-mirror" You can specify only a single URL 1764
1765 INHERIT += "own-mirrors"
1766 SOURCE_MIRROR_URL = "http://example.com/my-source-mirror"
1767
1768You can specify only a single URL
1711in ``SOURCE_MIRROR_URL``. 1769in ``SOURCE_MIRROR_URL``.
1712 1770
1713.. _ref-classes-package: 1771.. _ref-classes-package:
@@ -1742,9 +1800,8 @@ first class listed in this variable is used for image generation.
1742If you take the optional step to set up a repository (package feed) on 1800If you take the optional step to set up a repository (package feed) on
1743the development host that can be used by DNF, you can install packages 1801the development host that can be used by DNF, you can install packages
1744from the feed while you are running the image on the target (i.e. 1802from the feed while you are running the image on the target (i.e.
1745runtime installation of packages). For more information, see the "`Using 1803runtime installation of packages). For more information, see the
1746Runtime Package 1804":ref:`dev-manual/dev-manual-common-tasks:using runtime package management`"
1747Management <&YOCTO_DOCS_DEV_URL;#using-runtime-package-management>`__"
1748section in the Yocto Project Development Tasks Manual. 1805section in the Yocto Project Development Tasks Manual.
1749 1806
1750The package-specific class you choose can affect build-time performance 1807The package-specific class you choose can affect build-time performance
@@ -1774,9 +1831,9 @@ consider some further things about using RPM:
1774You can find additional information on the effects of the package class 1831You can find additional information on the effects of the package class
1775at these two Yocto Project mailing list links: 1832at these two Yocto Project mailing list links:
1776 1833
1777- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html>`__ 1834- https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html
1778 1835
1779- `https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html <&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html>`__ 1836- https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html
1780 1837
1781.. _ref-classes-package_deb: 1838.. _ref-classes-package_deb:
1782 1839
@@ -1870,9 +1927,8 @@ group recipes (e.g. ``PACKAGES``, ``PACKAGE_ARCH``, ``ALLOW_EMPTY``, and
1870so forth). It is highly recommended that all package group recipes 1927so forth). It is highly recommended that all package group recipes
1871inherit this class. 1928inherit this class.
1872 1929
1873For information on how to use this class, see the "`Customizing Images 1930For information on how to use this class, see the
1874Using Custom Package 1931":ref:`usingpoky-extend-customimage-customtasks`"
1875Groups <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks>`__"
1876section in the Yocto Project Development Tasks Manual. 1932section in the Yocto Project Development Tasks Manual.
1877 1933
1878Previously, this class was called the ``task`` class. 1934Previously, this class was called the ``task`` class.
@@ -1937,8 +1993,7 @@ files.
1937The ``populate_sdk`` class provides support for SDK-only recipes. For 1993The ``populate_sdk`` class provides support for SDK-only recipes. For
1938information on advantages gained when building a cross-development 1994information on advantages gained when building a cross-development
1939toolchain using the :ref:`ref-tasks-populate_sdk` 1995toolchain using the :ref:`ref-tasks-populate_sdk`
1940task, see the "`Building an SDK 1996task, see the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
1941Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
1942section in the Yocto Project Application Development and the Extensible 1997section in the Yocto Project Application Development and the Extensible
1943Software Development Kit (eSDK) manual. 1998Software Development Kit (eSDK) manual.
1944 1999
@@ -1950,19 +2005,19 @@ Software Development Kit (eSDK) manual.
1950The ``populate_sdk_*`` classes support SDK creation and consist of the 2005The ``populate_sdk_*`` classes support SDK creation and consist of the
1951following classes: 2006following classes:
1952 2007
1953- *``populate_sdk_base``:* The base class supporting SDK creation under 2008- ``populate_sdk_base``: The base class supporting SDK creation under
1954 all package managers (i.e. DEB, RPM, and opkg). 2009 all package managers (i.e. DEB, RPM, and opkg).
1955 2010
1956- *``populate_sdk_deb``:* Supports creation of the SDK given the Debian 2011- ``populate_sdk_deb``: Supports creation of the SDK given the Debian
1957 package manager. 2012 package manager.
1958 2013
1959- *``populate_sdk_rpm``:* Supports creation of the SDK given the RPM 2014- ``populate_sdk_rpm``: Supports creation of the SDK given the RPM
1960 package manager. 2015 package manager.
1961 2016
1962- *``populate_sdk_ipk``:* Supports creation of the SDK given the opkg 2017- ``populate_sdk_ipk``: Supports creation of the SDK given the opkg
1963 (IPK format) package manager. 2018 (IPK format) package manager.
1964 2019
1965- *``populate_sdk_ext``:* Supports extensible SDK creation under all 2020- ``populate_sdk_ext``: Supports extensible SDK creation under all
1966 package managers. 2021 package managers.
1967 2022
1968The ``populate_sdk_base`` class inherits the appropriate 2023The ``populate_sdk_base`` class inherits the appropriate
@@ -1977,8 +2032,10 @@ contains the cross-compiler and associated tooling, and the target,
1977which contains a target root filesystem that is configured for the SDK 2032which contains a target root filesystem that is configured for the SDK
1978usage. These two images reside in :term:`SDK_OUTPUT`, 2033usage. These two images reside in :term:`SDK_OUTPUT`,
1979which consists of the following: 2034which consists of the following:
1980${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs 2035::
1981${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs 2036
2037 ${SDK_OUTPUT}/${SDK_ARCH}-nativesdk-pkgs
2038 ${SDK_OUTPUT}/${SDKTARGETSYSROOT}/target-pkgs
1982 2039
1983Finally, the base populate SDK class creates the toolchain environment 2040Finally, the base populate SDK class creates the toolchain environment
1984setup script, the tarball of the SDK, and the installer. 2041setup script, the tarball of the SDK, and the installer.
@@ -1989,13 +2046,12 @@ These classes are inherited by and used with the ``populate_sdk_base``
1989class. 2046class.
1990 2047
1991For more information on the cross-development toolchain generation, see 2048For more information on the cross-development toolchain generation, see
1992the "`Cross-Development Toolchain 2049the ":ref:`overview-manual/overview-manual-concepts:cross-development toolchain generation`"
1993Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
1994section in the Yocto Project Overview and Concepts Manual. For 2050section in the Yocto Project Overview and Concepts Manual. For
1995information on advantages gained when building a cross-development 2051information on advantages gained when building a cross-development
1996toolchain using the :ref:`ref-tasks-populate_sdk` 2052toolchain using the :ref:`ref-tasks-populate_sdk`
1997task, see the "`Building an SDK 2053task, see the
1998Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__" 2054":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
1999section in the Yocto Project Application Development and the Extensible 2055section in the Yocto Project Application Development and the Extensible
2000Software Development Kit (eSDK) manual. 2056Software Development Kit (eSDK) manual.
2001 2057
@@ -2034,8 +2090,8 @@ The ``primport`` class provides functionality for importing
2034``prserv.bbclass`` 2090``prserv.bbclass``
2035================== 2091==================
2036 2092
2037The ``prserv`` class provides functionality for using a `PR 2093The ``prserv`` class provides functionality for using a :ref:`PR
2038service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__ in order to 2094service <dev-manual/dev-manual-common-tasks:working with a pr service>` in order to
2039automatically manage the incrementing of the :term:`PR` 2095automatically manage the incrementing of the :term:`PR`
2040variable for each recipe. 2096variable for each recipe.
2041 2097
@@ -2054,11 +2110,10 @@ runtime tests for recipes that build software that provides these tests.
2054 2110
2055This class is intended to be inherited by individual recipes. However, 2111This class is intended to be inherited by individual recipes. However,
2056the class' functionality is largely disabled unless "ptest" appears in 2112the class' functionality is largely disabled unless "ptest" appears in
2057:term:`DISTRO_FEATURES`. See the "`Testing 2113:term:`DISTRO_FEATURES`. See the
2058Packages With 2114":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
2059ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in 2115section in the Yocto Project Development Tasks Manual for more information
2060the Yocto Project Development Tasks Manual for more information on 2116on ptest.
2061ptest.
2062 2117
2063.. _ref-classes-ptest-gnome: 2118.. _ref-classes-ptest-gnome:
2064 2119
@@ -2068,10 +2123,9 @@ ptest.
2068Enables package tests (ptests) specifically for GNOME packages, which 2123Enables package tests (ptests) specifically for GNOME packages, which
2069have tests intended to be executed with ``gnome-desktop-testing``. 2124have tests intended to be executed with ``gnome-desktop-testing``.
2070 2125
2071For information on setting up and running ptests, see the "`Testing 2126For information on setting up and running ptests, see the
2072Packages With 2127":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`"
2073ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section in 2128section in the Yocto Project Development Tasks Manual.
2074the Yocto Project Development Tasks Manual.
2075 2129
2076.. _ref-classes-python-dir: 2130.. _ref-classes-python-dir:
2077 2131
@@ -2142,7 +2196,9 @@ absent from both the sysroot and target packages.
2142 2196
2143If a recipe needs the ``.la`` files to be installed, then the recipe can 2197If a recipe needs the ``.la`` files to be installed, then the recipe can
2144override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows: 2198override the removal by setting ``REMOVE_LIBTOOL_LA`` to "0" as follows:
2145REMOVE_LIBTOOL_LA = "0" 2199::
2200
2201 REMOVE_LIBTOOL_LA = "0"
2146 2202
2147.. note:: 2203.. note::
2148 2204
@@ -2155,9 +2211,9 @@ REMOVE_LIBTOOL_LA = "0"
2155``report-error.bbclass`` 2211``report-error.bbclass``
2156======================== 2212========================
2157 2213
2158The ``report-error`` class supports enabling the `error reporting 2214The ``report-error`` class supports enabling the :ref:`error reporting
2159tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which 2215tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`",
2160allows you to submit build error information to a central database. 2216which allows you to submit build error information to a central database.
2161 2217
2162The class collects debug information for recipe, recipe version, task, 2218The class collects debug information for recipe, recipe version, task,
2163machine, distro, build system, target system, host distro, branch, 2219machine, distro, build system, target system, host distro, branch,
@@ -2182,14 +2238,20 @@ preserves these files for inspection and possible debugging purposes. If
2182you would rather have these files deleted to save disk space as the 2238you would rather have these files deleted to save disk space as the
2183build progresses, you can enable ``rm_work`` by adding the following to 2239build progresses, you can enable ``rm_work`` by adding the following to
2184your ``local.conf`` file, which is found in the :term:`Build Directory`. 2240your ``local.conf`` file, which is found in the :term:`Build Directory`.
2185INHERIT += "rm_work" If you are 2241::
2242
2243 INHERIT += "rm_work"
2244
2245If you are
2186modifying and building source code out of the work directory for a 2246modifying and building source code out of the work directory for a
2187recipe, enabling ``rm_work`` will potentially result in your changes to 2247recipe, enabling ``rm_work`` will potentially result in your changes to
2188the source being lost. To exclude some recipes from having their work 2248the source being lost. To exclude some recipes from having their work
2189directories deleted by ``rm_work``, you can add the names of the recipe 2249directories deleted by ``rm_work``, you can add the names of the recipe
2190or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which 2250or recipes you are working on to the ``RM_WORK_EXCLUDE`` variable, which
2191can also be set in your ``local.conf`` file. Here is an example: 2251can also be set in your ``local.conf`` file. Here is an example:
2192RM_WORK_EXCLUDE += "busybox glibc" 2252::
2253
2254 RM_WORK_EXCLUDE += "busybox glibc"
2193 2255
2194.. _ref-classes-rootfs*: 2256.. _ref-classes-rootfs*:
2195 2257
@@ -2219,8 +2281,7 @@ The root filesystem is created from packages using one of the
2219:term:`PACKAGE_CLASSES` variable. 2281:term:`PACKAGE_CLASSES` variable.
2220 2282
2221For information on how root filesystem images are created, see the 2283For information on how root filesystem images are created, see the
2222"`Image 2284:ref:`image-generation-dev-environment`"
2223Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
2224section in the Yocto Project Overview and Concepts Manual. 2285section in the Yocto Project Overview and Concepts Manual.
2225 2286
2226.. _ref-classes-sanity: 2287.. _ref-classes-sanity:
@@ -2339,9 +2400,9 @@ The ``sstate`` class provides support for Shared State (sstate). By
2339default, the class is enabled through the 2400default, the class is enabled through the
2340:term:`INHERIT_DISTRO` variable's default value. 2401:term:`INHERIT_DISTRO` variable's default value.
2341 2402
2342For more information on sstate, see the "`Shared State 2403For more information on sstate, see the
2343Cache <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__" section in the Yocto 2404":ref:`overview-manual/overview-manual-concepts:shared state cache`"
2344Project Overview and Concepts Manual. 2405section in the Yocto Project Overview and Concepts Manual.
2345 2406
2346.. _ref-classes-staging: 2407.. _ref-classes-staging:
2347 2408
@@ -2510,14 +2571,17 @@ You should set :term:`SYSTEMD_SERVICE` to the
2510name of the service file. You should also use a package name override to 2571name of the service file. You should also use a package name override to
2511indicate the package to which the value applies. If the value applies to 2572indicate the package to which the value applies. If the value applies to
2512the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here 2573the recipe's main package, use ``${``\ :term:`PN`\ ``}``. Here
2513is an example from the connman recipe: SYSTEMD_SERVICE_${PN} = 2574is an example from the connman recipe:
2514"connman.service" Services are set up to start on boot automatically 2575::
2576
2577 SYSTEMD_SERVICE_${PN} = "connman.service"
2578
2579Services are set up to start on boot automatically
2515unless you have set 2580unless you have set
2516:term:`SYSTEMD_AUTO_ENABLE` to "disable". 2581:term:`SYSTEMD_AUTO_ENABLE` to "disable".
2517 2582
2518For more information on ``systemd``, see the "`Selecting an 2583For more information on ``systemd``, see the
2519Initialization 2584":ref:`dev-manual/dev-manual-common-tasks:selecting an initialization manager`"
2520Manager <&YOCTO_DOCS_DEV_URL;#selecting-an-initialization-manager>`__"
2521section in the Yocto Project Development Tasks Manual. 2585section in the Yocto Project Development Tasks Manual.
2522 2586
2523.. _ref-classes-systemd-boot: 2587.. _ref-classes-systemd-boot:
@@ -2593,13 +2657,17 @@ The tests are commands that run on the target system over ``ssh``. Each
2593test is written in Python and makes use of the ``unittest`` module. 2657test is written in Python and makes use of the ``unittest`` module.
2594 2658
2595The ``testimage.bbclass`` runs tests on an image when called using the 2659The ``testimage.bbclass`` runs tests on an image when called using the
2596following: $ bitbake -c testimage image The ``testimage-auto`` class 2660following:
2661::
2662
2663 $ bitbake -c testimage image
2664
2665The ``testimage-auto`` class
2597runs tests on an image after the image is constructed (i.e. 2666runs tests on an image after the image is constructed (i.e.
2598:term:`TESTIMAGE_AUTO` must be set to "1"). 2667:term:`TESTIMAGE_AUTO` must be set to "1").
2599 2668
2600For information on how to enable, run, and create new tests, see the 2669For information on how to enable, run, and create new tests, see the
2601"`Performing Automated Runtime 2670":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
2602Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
2603section in the Yocto Project Development Tasks Manual. 2671section in the Yocto Project Development Tasks Manual.
2604 2672
2605.. _ref-classes-testsdk: 2673.. _ref-classes-testsdk:
@@ -2609,7 +2677,10 @@ section in the Yocto Project Development Tasks Manual.
2609 2677
2610This class supports running automated tests against software development 2678This class supports running automated tests against software development
2611kits (SDKs). The ``testsdk`` class runs tests on an SDK when called 2679kits (SDKs). The ``testsdk`` class runs tests on an SDK when called
2612using the following: $ bitbake -c testsdk image 2680using the following:
2681::
2682
2683 $ bitbake -c testsdk image
2613 2684
2614.. note:: 2685.. note::
2615 2686
@@ -2682,7 +2753,9 @@ The ``typecheck`` class provides support for validating the values of
2682variables set at the configuration level against their defined types. 2753variables set at the configuration level against their defined types.
2683The OpenEmbedded build system allows you to define the type of a 2754The OpenEmbedded build system allows you to define the type of a
2684variable using the "type" varflag. Here is an example: 2755variable using the "type" varflag. Here is an example:
2685IMAGE_FEATURES[type] = "list" 2756::
2757
2758 IMAGE_FEATURES[type] = "list"
2686 2759
2687.. _ref-classes-uboot-config: 2760.. _ref-classes-uboot-config:
2688 2761
@@ -2690,11 +2763,18 @@ IMAGE_FEATURES[type] = "list"
2690======================== 2763========================
2691 2764
2692The ``uboot-config`` class provides support for U-Boot configuration for 2765The ``uboot-config`` class provides support for U-Boot configuration for
2693a machine. Specify the machine in your recipe as follows: UBOOT_CONFIG 2766a machine. Specify the machine in your recipe as follows:
2694??= <default> UBOOT_CONFIG[foo] = "config,images" You can also specify 2767::
2695the machine using this method: UBOOT_MACHINE = "config" See the 2768
2696:term:`UBOOT_CONFIG` and 2769 UBOOT_CONFIG ??= <default>
2697:term:`UBOOT_MACHINE` variables for additional 2770 UBOOT_CONFIG[foo] = "config,images"
2771
2772You can also specify the machine using this method:
2773::
2774
2775 UBOOT_MACHINE = "config"
2776
2777See the :term:`UBOOT_CONFIG` and :term:`UBOOT_MACHINE` variables for additional
2698information. 2778information.
2699 2779
2700.. _ref-classes-uninative: 2780.. _ref-classes-uninative:
diff --git a/documentation/ref-manual/ref-devtool-reference.rst b/documentation/ref-manual/ref-devtool-reference.rst
index ca1d7fd0cb..eaca45ae25 100644
--- a/documentation/ref-manual/ref-devtool-reference.rst
+++ b/documentation/ref-manual/ref-devtool-reference.rst
@@ -11,8 +11,7 @@ is a key part of the extensible SDK.
11 11
12This chapter provides a Quick Reference for the ``devtool`` command. For 12This chapter provides a Quick Reference for the ``devtool`` command. For
13more information on how to apply the command when using the extensible 13more information on how to apply the command when using the extensible
14SDK, see the "`Using the Extensible 14SDK, see the ":doc:`../sdk-manual/sdk-extensible`" chapter in the Yocto
15SDK <&YOCTO_DOCS_SDK_URL;#sdk-extensible>`__" chapter in the Yocto
16Project Application Development and the Extensible Software Development 15Project Application Development and the Extensible Software Development
17Kit (eSDK) manual. 16Kit (eSDK) manual.
18 17
@@ -23,66 +22,99 @@ Getting Help
23 22
24The ``devtool`` command line is organized similarly to Git in that it 23The ``devtool`` command line is organized similarly to Git in that it
25has a number of sub-commands for each function. You can run 24has a number of sub-commands for each function. You can run
26``devtool --help`` to see all the commands: $ devtool -h NOTE: Starting 25``devtool --help`` to see all the commands:
27bitbake server... usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] 26::
28[-d] [-q] [--color COLOR] [-h] <subcommand> ... OpenEmbedded development 27
29tool options: --basepath BASEPATH Base directory of SDK / build 28 $ devtool -h
30directory --bbpath BBPATH Explicitly specify the BBPATH, rather than 29 NOTE: Starting bitbake server...
31getting it from the metadata -d, --debug Enable debug output -q, --quiet 30 usage: devtool [--basepath BASEPATH] [--bbpath BBPATH] [-d] [-q] [--color COLOR] [-h] <subcommand> ...
32Print only errors --color COLOR Colorize output (where COLOR is auto, 31
33always, never) -h, --help show this help message and exit subcommands: 32 OpenEmbedded development tool
34Beginning work on a recipe: add Add a new recipe modify Modify the 33
35source for an existing recipe upgrade Upgrade an existing recipe Getting 34 options:
36information: status Show workspace status search Search available 35 --basepath BASEPATH Base directory of SDK / build directory
37recipes latest-version Report the latest version of an existing recipe 36 --bbpath BBPATH Explicitly specify the BBPATH, rather than getting it from the metadata
38check-upgrade-status Report upgradability for multiple (or all) recipes 37 -d, --debug Enable debug output
39Working on a recipe in the workspace: build Build a recipe rename Rename 38 -q, --quiet Print only errors
40a recipe file in the workspace edit-recipe Edit a recipe file 39 --color COLOR Colorize output (where COLOR is auto, always, never)
41find-recipe Find a recipe file configure-help Get help on configure 40 -h, --help show this help message and exit
42script options update-recipe Apply changes from external source tree to 41
43recipe reset Remove a recipe from your workspace finish Finish working 42 subcommands:
44on a recipe in your workspace Testing changes on target: deploy-target 43 Beginning work on a recipe:
45Deploy recipe output files to live target machine undeploy-target 44 add Add a new recipe
46Undeploy recipe output files in live target machine build-image Build 45 modify Modify the source for an existing recipe
47image including workspace recipe packages Advanced: create-workspace Set 46 upgrade Upgrade an existing recipe
48up workspace in an alternative location export Export workspace into a 47 Getting information:
49tar archive import Import exported tar archive into workspace extract 48 status Show workspace status
50Extract the source for an existing recipe sync Synchronize the source 49 latest-version Report the latest version of an existing recipe
51tree for an existing recipe Use devtool <subcommand> --help to get help 50 check-upgrade-status Report upgradability for multiple (or all) recipes
52on a specific command As directed in the general help output, you can 51 search Search available recipes
52 Working on a recipe in the workspace:
53 build Build a recipe
54 rename Rename a recipe file in the workspace
55 edit-recipe Edit a recipe file
56 find-recipe Find a recipe file
57 configure-help Get help on configure script options
58 update-recipe Apply changes from external source tree to recipe
59 reset Remove a recipe from your workspace
60 finish Finish working on a recipe in your workspace
61 Testing changes on target:
62 deploy-target Deploy recipe output files to live target machine
63 undeploy-target Undeploy recipe output files in live target machine
64 build-image Build image including workspace recipe packages
65 Advanced:
66 create-workspace Set up workspace in an alternative location
67 extract Extract the source for an existing recipe
68 sync Synchronize the source tree for an existing recipe
69 menuconfig Alter build-time configuration for a recipe
70 import Import exported tar archive into workspace
71 export Export workspace into a tar archive
72 other:
73 selftest-reverse Reverse value (for selftest)
74 pluginfile Print the filename of this plugin
75 bbdir Print the BBPATH directory of this plugin
76 count How many times have this plugin been registered.
77 multiloaded How many times have this plugin been initialized
78 Use devtool <subcommand> --help to get help on a specific command
79
80As directed in the general help output, you can
53get more syntax on a specific command by providing the command name and 81get more syntax on a specific command by providing the command name and
54using "--help": $ devtool add --help NOTE: Starting bitbake server... 82using "--help":
55usage: devtool add [-h] [--same-dir \| --no-same-dir] [--fetch URI] 83::
56[--fetch-dev] [--version VERSION] [--no-git] [--srcrev SRCREV \| 84
57--autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] 85 $ devtool add --help
58[--src-subdir SUBDIR] [--mirrors] [--provides PROVIDES] [recipename] 86 NOTE: Starting bitbake server...
59[srctree] [fetchuri] Adds a new recipe to the workspace to build a 87 usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI] [--npm-dev] [--version VERSION] [--no-git] [--srcrev SRCREV | --autorev] [--srcbranch SRCBRANCH] [--binary] [--also-native] [--src-subdir SUBDIR] [--mirrors]
60specified source tree. Can optionally fetch a remote URI and unpack it 88 [--provides PROVIDES]
61to create the source tree. arguments: recipename Name for new recipe to 89 [recipename] [srctree] [fetchuri]
62add (just name - no version, path or extension). If not specified, will 90
63attempt to auto-detect it. srctree Path to external source tree. If not 91 Adds a new recipe to the workspace to build a specified source tree. Can optionally fetch a remote URI and unpack it to create the source tree.
64specified, a subdirectory of /home/scottrif/poky/build/workspace/sources 92
65will be used. fetchuri Fetch the specified URI and extract it to create 93 arguments:
66the source tree options: -h, --help show this help message and exit 94 recipename Name for new recipe to add (just name - no version, path or extension). If not specified, will attempt to auto-detect it.
67--same-dir, -s Build in same directory as source --no-same-dir Force 95 srctree Path to external source tree. If not specified, a subdirectory of /media/build1/poky/build/workspace/sources will be used.
68build in a separate build directory --fetch URI, -f URI Fetch the 96 fetchuri Fetch the specified URI and extract it to create the source tree
69specified URI and extract it to create the source tree (deprecated - 97
70pass as positional argument instead) --fetch-dev For npm, also fetch 98 options:
71devDependencies --version VERSION, -V VERSION Version to use within 99 -h, --help show this help message and exit
72recipe (PV) --no-git, -g If fetching source, do not set up source tree 100 --same-dir, -s Build in same directory as source
73as a git repository --srcrev SRCREV, -S SRCREV Source revision to fetch 101 --no-same-dir Force build in a separate build directory
74if fetching from an SCM such as git (default latest) --autorev, -a When 102 --fetch URI, -f URI Fetch the specified URI and extract it to create the source tree (deprecated - pass as positional argument instead)
75fetching from a git repository, set SRCREV in the recipe to a floating 103 --npm-dev For npm, also fetch devDependencies
76revision instead of fixed --srcbranch SRCBRANCH, -B SRCBRANCH Branch in 104 --version VERSION, -V VERSION
77source repository if fetching from an SCM such as git (default master) 105 Version to use within recipe (PV)
78--binary, -b Treat the source tree as something that should be installed 106 --no-git, -g If fetching source, do not set up source tree as a git repository
79verbatim (no compilation, same directory structure). Useful with binary 107 --srcrev SRCREV, -S SRCREV
80packages e.g. RPMs. --also-native Also add native variant (i.e. support 108 Source revision to fetch if fetching from an SCM such as git (default latest)
81building recipe for the build host as well as the target machine) 109 --autorev, -a When fetching from a git repository, set SRCREV in the recipe to a floating revision instead of fixed
82--src-subdir SUBDIR Specify subdirectory within source tree to use 110 --srcbranch SRCBRANCH, -B SRCBRANCH
83--mirrors Enable PREMIRRORS and MIRRORS for source tree fetching 111 Branch in source repository if fetching from an SCM such as git (default master)
84(disable by default). --provides PROVIDES, -p PROVIDES Specify an alias 112 --binary, -b Treat the source tree as something that should be installed verbatim (no compilation, same directory structure). Useful with binary packages e.g. RPMs.
85for the item provided by the recipe. E.g. virtual/libgl 113 --also-native Also add native variant (i.e. support building recipe for the build host as well as the target machine)
114 --src-subdir SUBDIR Specify subdirectory within source tree to use
115 --mirrors Enable PREMIRRORS and MIRRORS for source tree fetching (disable by default).
116 --provides PROVIDES, -p PROVIDES
117 Specify an alias for the item provided by the recipe. E.g. virtual/libgl
86 118
87.. _devtool-the-workspace-layer-structure: 119.. _devtool-the-workspace-layer-structure:
88 120
@@ -99,22 +131,35 @@ The following figure shows the workspace structure:
99 :align: center 131 :align: center
100 :scale: 70% 132 :scale: 70%
101 133
102attic - A directory created if devtool believes it must preserve 134::
103anything when you run "devtool reset". For example, if you run "devtool 135
104add", make changes to the recipe, and then run "devtool reset", devtool 136 attic - A directory created if devtool believes it must preserve
105takes notice that the file has been changed and moves it into the attic 137 anything when you run "devtool reset". For example, if you
106should you still want the recipe. README - Provides information on what 138 run "devtool add", make changes to the recipe, and then
107is in workspace layer and how to manage it. .devtool_md5 - A checksum 139 run "devtool reset", devtool takes notice that the file has
108file used by devtool. appends - A directory that contains \*.bbappend 140 been changed and moves it into the attic should you still
109files, which point to external source. conf - A configuration directory 141 want the recipe.
110that contains the layer.conf file. recipes - A directory containing 142
111recipes. This directory contains a folder for each directory added whose 143 README - Provides information on what is in workspace layer and how to
112name matches that of the added recipe. devtool places the recipe.bb file 144 manage it.
113within that sub-directory. sources - A directory containing a working 145
114copy of the source files used when building the recipe. This is the 146 .devtool_md5 - A checksum file used by devtool.
115default directory used as the location of the source tree when you do 147
116not provide a source tree path. This directory contains a folder for 148 appends - A directory that contains *.bbappend files, which point to
117each set of source files matched to a corresponding recipe. 149 external source.
150
151 conf - A configuration directory that contains the layer.conf file.
152
153 recipes - A directory containing recipes. This directory contains a
154 folder for each directory added whose name matches that of the
155 added recipe. devtool places the recipe.bb file
156 within that sub-directory.
157
158 sources - A directory containing a working copy of the source files used
159 when building the recipe. This is the default directory used
160 as the location of the source tree when you do not provide a
161 source tree path. This directory contains a folder for each
162 set of source files matched to a corresponding recipe.
118 163
119.. _devtool-adding-a-new-recipe-to-the-workspace: 164.. _devtool-adding-a-new-recipe-to-the-workspace:
120 165
@@ -127,8 +172,10 @@ you. The source files the recipe uses should exist in an external area.
127 172
128The following example creates and adds a new recipe named ``jackson`` to 173The following example creates and adds a new recipe named ``jackson`` to
129a workspace layer the tool creates. The source code built by the recipes 174a workspace layer the tool creates. The source code built by the recipes
130resides in ``/home/user/sources/jackson``: $ devtool add jackson 175resides in ``/home/user/sources/jackson``:
131/home/user/sources/jackson 176::
177
178 $ devtool add jackson /home/user/sources/jackson
132 179
133If you add a recipe and the workspace layer does not exist, the command 180If you add a recipe and the workspace layer does not exist, the command
134creates the layer and populates it as described in "`The Workspace Layer 181creates the layer and populates it as described in "`The Workspace Layer
@@ -145,35 +192,38 @@ external source tree.
145 that these packages exist on the target hardware before attempting to 192 that these packages exist on the target hardware before attempting to
146 run your application. If dependent packages (e.g. libraries) do not 193 run your application. If dependent packages (e.g. libraries) do not
147 exist on the target, your application, when run, will fail to find 194 exist on the target, your application, when run, will fail to find
148 those functions. For more information, see the " 195 those functions. For more information, see the
149 Deploying Your Software on the Target Machine 196 ":ref:`ref-manual/ref-devtool-reference:deploying your software on the target machine`"
150 " section. 197 section.
151 198
152By default, ``devtool add`` uses the latest revision (i.e. master) when 199By default, ``devtool add`` uses the latest revision (i.e. master) when
153unpacking files from a remote URI. In some cases, you might want to 200unpacking files from a remote URI. In some cases, you might want to
154specify a source revision by branch, tag, or commit hash. You can 201specify a source revision by branch, tag, or commit hash. You can
155specify these options when using the ``devtool add`` command: 202specify these options when using the ``devtool add`` command:
156 203
157- To specify a source branch, use the ``--srcbranch`` option: $ devtool 204- To specify a source branch, use the ``--srcbranch`` option:
158 add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson 205 ::
206
207 $ devtool add --srcbranch DISTRO_NAME_NO_CAP jackson /home/user/sources/jackson
208
159 In the previous example, you are checking out the DISTRO_NAME_NO_CAP 209 In the previous example, you are checking out the DISTRO_NAME_NO_CAP
160 branch. 210 branch.
161 211
162- To specify a specific tag or commit hash, use the ``--srcrev`` 212- To specify a specific tag or commit hash, use the ``--srcrev``
163 option: $ devtool add --srcrev DISTRO_REL_TAG jackson 213 option:
164 /home/user/sources/jackson $ devtool add --srcrev some_commit_hash 214 ::
165 /home/user/sources/jackson The previous examples check out the 215
216 $ devtool add --srcrev DISTRO_REL_TAG jackson /home/user/sources/jackson
217 $ devtool add --srcrev some_commit_hash /home/user/sources/jackson
218
219 The previous examples check out the
166 DISTRO_REL_TAG tag and the commit associated with the 220 DISTRO_REL_TAG tag and the commit associated with the
167 some_commit_hash hash. 221 some_commit_hash hash.
168 222
169.. note:: 223.. note::
170 224
171 If you prefer to use the latest revision every time the recipe is 225 If you prefer to use the latest revision every time the recipe is
172 built, use the options 226 built, use the options --autorev or -a.
173 --autorev
174 or
175 -a
176 .
177 227
178.. _devtool-extracting-the-source-for-an-existing-recipe: 228.. _devtool-extracting-the-source-for-an-existing-recipe:
179 229
@@ -219,8 +269,12 @@ The ``devtool modify`` command extracts the source for a recipe, sets it
219up as a Git repository if the source had not already been fetched from 269up as a Git repository if the source had not already been fetched from
220Git, checks out a branch for development, and applies any patches from 270Git, checks out a branch for development, and applies any patches from
221the recipe as commits on top. You can use the following command to 271the recipe as commits on top. You can use the following command to
222checkout the source files: $ devtool modify recipe Using the above 272checkout the source files:
223command form, ``devtool`` uses the existing recipe's 273::
274
275 $ devtool modify recipe
276
277Using the above command form, ``devtool`` uses the existing recipe's
224:term:`SRC_URI` statement to locate the upstream source, 278:term:`SRC_URI` statement to locate the upstream source,
225extracts the source into the default sources location in the workspace. 279extracts the source into the default sources location in the workspace.
226The default development branch used is "devtool". 280The default development branch used is "devtool".
@@ -255,16 +309,24 @@ compile, and test the code.
255 309
256When you are satisfied with the results and you have committed your 310When you are satisfied with the results and you have committed your
257changes to the Git repository, you can then run the 311changes to the Git repository, you can then run the
258``devtool update-recipe`` to create the patches and update the recipe: $ 312``devtool update-recipe`` to create the patches and update the recipe:
259devtool update-recipe recipe If you run the ``devtool update-recipe`` 313::
314
315 $ devtool update-recipe recipe
316
317If you run the ``devtool update-recipe``
260without committing your changes, the command ignores the changes. 318without committing your changes, the command ignores the changes.
261 319
262Often, you might want to apply customizations made to your software in 320Often, you might want to apply customizations made to your software in
263your own layer rather than apply them to the original recipe. If so, you 321your own layer rather than apply them to the original recipe. If so, you
264can use the ``-a`` or ``--append`` option with the 322can use the ``-a`` or ``--append`` option with the
265``devtool update-recipe`` command. These options allow you to specify 323``devtool update-recipe`` command. These options allow you to specify
266the layer into which to write an append file: $ devtool update-recipe 324the layer into which to write an append file:
267recipe -a base-layer-directory The ``*.bbappend`` file is created at the 325::
326
327 $ devtool update-recipe recipe -a base-layer-directory
328
329The ``*.bbappend`` file is created at the
268appropriate path within the specified layer directory, which may or may 330appropriate path within the specified layer directory, which may or may
269not be in your ``bblayers.conf`` file. If an append file already exists, 331not be in your ``bblayers.conf`` file. If an append file already exists,
270the command updates it appropriately. 332the command updates it appropriately.
@@ -287,7 +349,7 @@ particular recipe.
287.. note:: 349.. note::
288 350
289 - For the ``oe-core`` layer, recipe maintainers come from the 351 - For the ``oe-core`` layer, recipe maintainers come from the
290 ```maintainers.inc`http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc 352 `maintainers.inc <http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/distro/include/maintainers.inc>`_
291 file. 353 file.
292 354
293 - If the recipe is using the :ref:`bitbake:git-fetcher` 355 - If the recipe is using the :ref:`bitbake:git-fetcher`
@@ -296,14 +358,21 @@ particular recipe.
296 recipe's latest version tag. 358 recipe's latest version tag.
297 359
298As with all ``devtool`` commands, you can get help on the individual 360As with all ``devtool`` commands, you can get help on the individual
299command: $ devtool check-upgrade-status -h NOTE: Starting bitbake 361command:
300server... usage: devtool check-upgrade-status [-h] [--all] [recipe 362::
301[recipe ...]] Prints a table of recipes together with versions currently 363
302provided by recipes, and latest upstream versions, when there is a later 364 $ devtool check-upgrade-status -h
303version available arguments: recipe Name of the recipe to report (omit 365 NOTE: Starting bitbake server...
304to report upgrade info for all recipes) options: -h, --help show this 366 usage: devtool check-upgrade-status [-h] [--all] [recipe [recipe ...]]
305help message and exit --all, -a Show all recipes, not just recipes 367
306needing upgrade 368 Prints a table of recipes together with versions currently provided by recipes, and latest upstream versions, when there is a later version available
369
370 arguments:
371 recipe Name of the recipe to report (omit to report upgrade info for all recipes)
372
373 options:
374 -h, --help show this help message and exit
375 --all, -a Show all recipes, not just recipes needing upgrade
307 376
308Unless you provide a specific recipe name on the command line, the 377Unless you provide a specific recipe name on the command line, the
309command checks all recipes in all configured layers. 378command checks all recipes in all configured layers.
@@ -317,21 +386,18 @@ satisfied.
317.. note:: 386.. note::
318 387
319 When a reason for not upgrading displays, the reason is usually 388 When a reason for not upgrading displays, the reason is usually
320 written into the recipe using the 389 written into the recipe using the RECIPE_NO_UPDATE_REASON
321 RECIPE_NO_UPDATE_REASON 390 variable. See the base-passwd.bb recipe for an example.
322 variable. See the 391
323 base-passwd.bb 392::
324 recipe for an example. 393
325 394 $ devtool check-upgrade-status ...
326$ devtool check-upgrade-status ... NOTE: acpid 2.0.30 2.0.31 Ross Burton 395 NOTE: acpid 2.0.30 2.0.31 Ross Burton <ross.burton@intel.com>
327<ross.burton@intel.com> NOTE: u-boot-fw-utils 2018.11 2019.01 Marek 396 NOTE: u-boot-fw-utils 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff
328Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff 397 NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> d3689267f92c5956e09cc7d1baa4700141662bff . . .
329NOTE: u-boot-tools 2018.11 2019.01 Marek Vasut <marek.vasut@gmail.com> 398 NOTE: base-passwd 3.5.29 3.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: Version 3.5.38 requires cdebconf for update-passwd utility
330d3689267f92c5956e09cc7d1baa4700141662bff . . . NOTE: base-passwd 3.5.29 399 NOTE: busybox 1.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com>
3313.5.45 Anuj Mittal <anuj.mittal@intel.com> cannot be updated due to: 400 NOTE: dbus-test 1.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
332Version 3.5.38 requires cdebconf for update-passwd utility NOTE: busybox
3331.29.2 1.30.0 Andrej Valek <andrej.valek@siemens.com> NOTE: dbus-test
3341.12.10 1.12.12 Chen Qi <Qi.Chen@windriver.com>
335 401
336.. _devtool-upgrading-a-recipe: 402.. _devtool-upgrading-a-recipe:
337 403
@@ -341,17 +407,13 @@ Upgrading a Recipe
341As software matures, upstream recipes are upgraded to newer versions. As 407As software matures, upstream recipes are upgraded to newer versions. As
342a developer, you need to keep your local recipes up-to-date with the 408a developer, you need to keep your local recipes up-to-date with the
343upstream version releases. Several methods exist by which you can 409upstream version releases. Several methods exist by which you can
344upgrade recipes. You can read about them in the "`Upgrading 410upgrade recipes. You can read about them in the ":ref:`gs-upgrading-recipes`"
345Recipes <&YOCTO_DOCS_DEV_URL;#gs-upgrading-recipes>`__" section of the 411section of the Yocto Project Development Tasks Manual. This section
346Yocto Project Development Tasks Manual. This section overviews the 412overviews the ``devtool upgrade`` command.
347``devtool upgrade`` command.
348 413
349.. note:: 414Before you upgrade a recipe, you can check on its upgrade status. See
350 415the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`" section
351 Before you upgrade a recipe, you can check on its upgrade status. See 416for more information.
352 the "
353 Checking on the Upgrade Status of a Recipe
354 " for more information.
355 417
356The ``devtool upgrade`` command upgrades an existing recipe to a more 418The ``devtool upgrade`` command upgrades an existing recipe to a more
357recent version of the recipe upstream. The command puts the upgraded 419recent version of the recipe upstream. The command puts the upgraded
@@ -369,14 +431,11 @@ revision to which you want to upgrade (i.e. the
369:term:`SRCREV`), whether or not to apply patches, and so 431:term:`SRCREV`), whether or not to apply patches, and so
370forth. 432forth.
371 433
372You can read more on the ``devtool upgrade`` workflow in the "`Use 434You can read more on the ``devtool upgrade`` workflow in the
373``devtool upgrade`` to Create a Version of the Recipe that Supports a 435":ref:`sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software`"
374Newer Version of the
375Software <&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software>`__"
376section in the Yocto Project Application Development and the Extensible 436section in the Yocto Project Application Development and the Extensible
377Software Development Kit (eSDK) manual. You can also see an example of 437Software Development Kit (eSDK) manual. You can also see an example of
378how to use ``devtool upgrade`` in the "`Using 438how to use ``devtool upgrade`` in the ":ref:`gs-using-devtool-upgrade`"
379``devtool upgrade`` <&YOCTO_DOCS_DEV_URL;#gs-using-devtool-upgrade>`__"
380section in the Yocto Project Development Tasks Manual. 439section in the Yocto Project Development Tasks Manual.
381 440
382.. _devtool-resetting-a-recipe: 441.. _devtool-resetting-a-recipe:
@@ -397,10 +456,13 @@ files have been modified, the command preserves the modified files in a
397separate "attic" subdirectory under the workspace layer. 456separate "attic" subdirectory under the workspace layer.
398 457
399Here is an example that resets the workspace directory that contains the 458Here is an example that resets the workspace directory that contains the
400``mtr`` recipe: $ devtool reset mtr NOTE: Cleaning sysroot for recipe 459``mtr`` recipe:
401mtr... NOTE: Leaving source tree 460::
402/home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer 461
403need it then please delete it manually $ 462 $ devtool reset mtr
463 NOTE: Cleaning sysroot for recipe mtr...
464 NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/mtr as-is; if you no longer need it then please delete it manually
465 $
404 466
405.. _devtool-building-your-recipe: 467.. _devtool-building-your-recipe:
406 468
@@ -414,8 +476,10 @@ Use the ``devtool build`` command to build your recipe. The
414When you use the ``devtool build`` command, you must supply the root 476When you use the ``devtool build`` command, you must supply the root
415name of the recipe (i.e. do not provide versions, paths, or extensions). 477name of the recipe (i.e. do not provide versions, paths, or extensions).
416You can use either the "-s" or the "--disable-parallel-make" options to 478You can use either the "-s" or the "--disable-parallel-make" options to
417disable parallel makes during the build. Here is an example: $ devtool 479disable parallel makes during the build. Here is an example:
418build recipe 480::
481
482 $ devtool build recipe
419 483
420.. _devtool-building-your-image: 484.. _devtool-building-your-image:
421 485
@@ -429,8 +493,10 @@ device for testing. For proper integration into a final image, you need
429to edit your custom image recipe appropriately. 493to edit your custom image recipe appropriately.
430 494
431When you use the ``devtool build-image`` command, you must supply the 495When you use the ``devtool build-image`` command, you must supply the
432name of the image. This command has no command line options: $ devtool 496name of the image. This command has no command line options:
433build-image image 497::
498
499 $ devtool build-image image
434 500
435.. _devtool-deploying-your-software-on-the-target-machine: 501.. _devtool-deploying-your-software-on-the-target-machine:
436 502
@@ -438,7 +504,11 @@ Deploying Your Software on the Target Machine
438============================================= 504=============================================
439 505
440Use the ``devtool deploy-target`` command to deploy the recipe's build 506Use the ``devtool deploy-target`` command to deploy the recipe's build
441output to the live target machine: $ devtool deploy-target recipe target 507output to the live target machine:
508::
509
510 $ devtool deploy-target recipe target
511
442The target is the address of the target machine, which must be running 512The target is the address of the target machine, which must be running
443an SSH server (i.e. ``user@hostname[:destdir]``). 513an SSH server (i.e. ``user@hostname[:destdir]``).
444 514
@@ -485,8 +555,13 @@ Removing Your Software from the Target Machine
485Use the ``devtool undeploy-target`` command to remove deployed build 555Use the ``devtool undeploy-target`` command to remove deployed build
486output from the target machine. For the ``devtool undeploy-target`` 556output from the target machine. For the ``devtool undeploy-target``
487command to work, you must have previously used the 557command to work, you must have previously used the
488```devtool deploy-target`` <#devtool-deploying-your-software-on-the-target-machine>`__ 558":ref:`devtool deploy-target <ref-manual/ref-devtool-reference:deploying your software on the target machine>`"
489command. $ devtool undeploy-target recipe target The target is the 559command.
560::
561
562 $ devtool undeploy-target recipe target
563
564The target is the
490address of the target machine, which must be running an SSH server (i.e. 565address of the target machine, which must be running an SSH server (i.e.
491``user@hostname``). 566``user@hostname``).
492 567
@@ -501,12 +576,17 @@ new workspace layer, it is populated with the ``README`` file and the
501``conf`` directory only. 576``conf`` directory only.
502 577
503The following example creates a new workspace layer in your current 578The following example creates a new workspace layer in your current
504working and by default names the workspace layer "workspace": $ devtool 579working and by default names the workspace layer "workspace":
505create-workspace 580::
581
582 $ devtool create-workspace
506 583
507You can create a workspace layer anywhere by supplying a pathname with 584You can create a workspace layer anywhere by supplying a pathname with
508the command. The following command creates a new workspace layer named 585the command. The following command creates a new workspace layer named
509"new-workspace": $ devtool create-workspace /home/scottrif/new-workspace 586"new-workspace":
587::
588
589 $ devtool create-workspace /home/scottrif/new-workspace
510 590
511.. _devtool-get-the-status-of-the-recipes-in-your-workspace: 591.. _devtool-get-the-status-of-the-recipes-in-your-workspace:
512 592
@@ -517,13 +597,19 @@ Use the ``devtool status`` command to list the recipes currently in your
517workspace. Information includes the paths to their respective external 597workspace. Information includes the paths to their respective external
518source trees. 598source trees.
519 599
520The ``devtool status`` command has no command-line options: $ devtool 600The ``devtool status`` command has no command-line options:
521status Following is sample output after using 601::
522```devtool add`` <#devtool-adding-a-new-recipe-to-the-workspace>`__ to 602
523create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` 603 $ devtool status
524directory: $ devtool status mtr: 604
525/home/scottrif/poky/build/workspace/sources/mtr 605Following is sample output after using
526(/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb) $ 606:ref:`devtool add <ref-manual/ref-devtool-reference:adding a new recipe to the workspace layer>`
607to create and add the ``mtr_0.86.bb`` recipe to the ``workspace`` directory:
608::
609
610 $ devtool status mtr
611 :/home/scottrif/poky/build/workspace/sources/mtr (/home/scottrif/poky/build/workspace/recipes/mtr/mtr_0.86.bb)
612 $
527 613
528.. _devtool-search-for-available-target-recipes: 614.. _devtool-search-for-available-target-recipes:
529 615
diff --git a/documentation/ref-manual/ref-features.rst b/documentation/ref-manual/ref-features.rst
index 0e901edaeb..ae5a0e3b24 100644
--- a/documentation/ref-manual/ref-features.rst
+++ b/documentation/ref-manual/ref-features.rst
@@ -26,8 +26,11 @@ One method you can use to determine which recipes are checking to see if
26a particular feature is contained or not is to ``grep`` through the 26a particular feature is contained or not is to ``grep`` through the
27:term:`Metadata` for the feature. Here is an example that 27:term:`Metadata` for the feature. Here is an example that
28discovers the recipes whose build is potentially changed based on a 28discovers the recipes whose build is potentially changed based on a
29given feature: $ cd poky $ git grep 29given feature:
30'contains.*MACHINE_FEATURES.*feature' 30::
31
32 $ cd poky
33 $ git grep 'contains.*MACHINE_FEATURES.*feature'
31 34
32.. _ref-features-machine: 35.. _ref-features-machine:
33 36
@@ -115,8 +118,7 @@ metadata:
115- *api-documentation:* Enables generation of API documentation during 118- *api-documentation:* Enables generation of API documentation during
116 recipe builds. The resulting documentation is added to SDK tarballs 119 recipe builds. The resulting documentation is added to SDK tarballs
117 when the ``bitbake -c populate_sdk`` command is used. See the 120 when the ``bitbake -c populate_sdk`` command is used. See the
118 "`Adding API Documentation to the Standard 121 ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding api documentation to the standard sdk`"
119 SDK <&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk>`__"
120 section in the Yocto Project Application Development and the 122 section in the Yocto Project Application Development and the
121 Extensible Software Development Kit (eSDK) manual. 123 Extensible Software Development Kit (eSDK) manual.
122 124
@@ -154,8 +156,7 @@ metadata:
154 156
155- *ptest:* Enables building the package tests where supported by 157- *ptest:* Enables building the package tests where supported by
156 individual recipes. For more information on package tests, see the 158 individual recipes. For more information on package tests, see the
157 "`Testing Packages With 159 ":ref:`dev-manual/dev-manual-common-tasks:testing packages with ptest`" section
158 ptest <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__" section
159 in the Yocto Project Development Tasks Manual. 160 in the Yocto Project Development Tasks Manual.
160 161
161- *smbfs:* Include SMB networks client support (for mounting 162- *smbfs:* Include SMB networks client support (for mounting
@@ -237,8 +238,8 @@ The following image features are available for all images:
237- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes. 238- *ptest-pkgs:* Installs ptest packages for all ptest-enabled recipes.
238 239
239- *read-only-rootfs:* Creates an image whose root filesystem is 240- *read-only-rootfs:* Creates an image whose root filesystem is
240 read-only. See the "`Creating a Read-Only Root 241 read-only. See the
241 Filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__" 242 ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`"
242 section in the Yocto Project Development Tasks Manual for more 243 section in the Yocto Project Development Tasks Manual for more
243 information. 244 information.
244 245
@@ -263,8 +264,7 @@ these valid features is as follows:
263 264
264- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and 265- *perf:* Installs profiling tools such as ``perf``, ``systemtap``, and
265 ``LTTng``. For general information on user-space tools, see the 266 ``LTTng``. For general information on user-space tools, see the
266 `Yocto Project Application Development and the Extensible Software 267 :doc:`../sdk-manual/sdk-manual` manual.
267 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual.
268 268
269- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server. 269- *ssh-server-dropbear:* Installs the Dropbear minimal SSH server.
270 270
@@ -275,12 +275,10 @@ these valid features is as follows:
275 will not be installed. 275 will not be installed.
276 276
277- *tools-debug:* Installs debugging tools such as ``strace`` and 277- *tools-debug:* Installs debugging tools such as ``strace`` and
278 ``gdb``. For information on GDB, see the "`Debugging With the GNU 278 ``gdb``. For information on GDB, see the
279 Project Debugger (GDB) 279 ":ref:`platdev-gdb-remotedebug`" section
280 Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section
281 in the Yocto Project Development Tasks Manual. For information on 280 in the Yocto Project Development Tasks Manual. For information on
282 tracing and profiling, see the `Yocto Project Profiling and Tracing 281 tracing and profiling, see the :doc:`../profile-manual/profile-manual`.
283 Manual <&YOCTO_DOCS_PROF_URL;>`__.
284 282
285- *tools-sdk:* Installs a full SDK that runs on the device. 283- *tools-sdk:* Installs a full SDK that runs on the device.
286 284
diff --git a/documentation/ref-manual/ref-images.rst b/documentation/ref-manual/ref-images.rst
index 0e26e57155..47beda0c23 100644
--- a/documentation/ref-manual/ref-images.rst
+++ b/documentation/ref-manual/ref-images.rst
@@ -24,12 +24,13 @@ image you want.
24 24
25 1. Comment out the EXTRA_IMAGE_FEATURES line 25 1. Comment out the EXTRA_IMAGE_FEATURES line
26 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" 26 2. Set INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
27 27
28 28
29From within the ``poky`` Git repository, you can use the following 29From within the ``poky`` Git repository, you can use the following
30command to display the list of directories within the :term:`Source Directory` 30command to display the list of directories within the :term:`Source Directory`
31that contain image recipe files: $ ls 31that contain image recipe files: ::
32meta*/recipes*/images/*.bb 32
33 $ ls meta*/recipes*/images/*.bb
33 34
34Following is a list of supported recipes: 35Following is a list of supported recipes:
35 36
@@ -121,9 +122,8 @@ Following is a list of supported recipes:
121 automated runtime testing. Provides a "known good" image that is 122 automated runtime testing. Provides a "known good" image that is
122 deployed to a separate partition so that you can boot into it and use 123 deployed to a separate partition so that you can boot into it and use
123 it to deploy a second image to be tested. You can find more 124 it to deploy a second image to be tested. You can find more
124 information about runtime testing in the "`Performing Automated 125 information about runtime testing in the
125 Runtime 126 ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
126 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
127 section in the Yocto Project Development Tasks Manual. 127 section in the Yocto Project Development Tasks Manual.
128 128
129- ``core-image-testmaster-initramfs``: A RAM-based Initial Root 129- ``core-image-testmaster-initramfs``: A RAM-based Initial Root
@@ -132,8 +132,8 @@ Following is a list of supported recipes:
132 132
133- ``core-image-weston``: A very basic Wayland image with a terminal. 133- ``core-image-weston``: A very basic Wayland image with a terminal.
134 This image provides the Wayland protocol libraries and the reference 134 This image provides the Wayland protocol libraries and the reference
135 Weston compositor. For more information, see the "`Using Wayland and 135 Weston compositor. For more information, see the
136 Weston <&YOCTO_DOCS_DEV_URL;#dev-using-wayland-and-weston>`__" 136 ":ref:`dev-manual/dev-manual-common-tasks:using wayland and weston`"
137 section in the Yocto Project Development Tasks Manual. 137 section in the Yocto Project Development Tasks Manual.
138 138
139- ``core-image-x11``: A very basic X11 image with a terminal. 139- ``core-image-x11``: A very basic X11 image with a terminal.
diff --git a/documentation/ref-manual/ref-kickstart.rst b/documentation/ref-manual/ref-kickstart.rst
index 271e6e8509..45222de05b 100644
--- a/documentation/ref-manual/ref-kickstart.rst
+++ b/documentation/ref-manual/ref-kickstart.rst
@@ -30,7 +30,13 @@ Command: part or partition
30========================== 30==========================
31 31
32Either of these commands creates a partition on the system and uses the 32Either of these commands creates a partition on the system and uses the
33following syntax: part [mntpoint] partition [mntpoint] If you do not 33following syntax:
34::
35
36 part [mntpoint]
37 partition [mntpoint]
38
39If you do not
34provide mntpoint, Wic creates a partition but does not mount it. 40provide mntpoint, Wic creates a partition but does not mount it.
35 41
36The ``mntpoint`` is where the partition is mounted and must be in one of 42The ``mntpoint`` is where the partition is mounted and must be in one of
@@ -62,20 +68,19 @@ Here is an example that uses "/" as the mountpoint. The command uses
62Here is a list that describes other supported options you can use with 68Here is a list that describes other supported options you can use with
63the ``part`` and ``partition`` commands: 69the ``part`` and ``partition`` commands:
64 70
65- *``--size``:* The minimum partition size in MBytes. Specify an 71- ``--size``: The minimum partition size in MBytes. Specify an
66 integer value such as 500. Do not append the number with "MB". You do 72 integer value such as 500. Do not append the number with "MB". You do
67 not need this option if you use ``--source``. 73 not need this option if you use ``--source``.
68 74
69- *``--fixed-size``:* The exact partition size in MBytes. You cannot 75- ``--fixed-size``: The exact partition size in MBytes. You cannot
70 specify with ``--size``. An error occurs when assembling the disk 76 specify with ``--size``. An error occurs when assembling the disk
71 image if the partition data is larger than ``--fixed-size``. 77 image if the partition data is larger than ``--fixed-size``.
72 78
73- *``--source``:* This option is a Wic-specific option that names the 79- ``--source``: This option is a Wic-specific option that names the
74 source of the data that populates the partition. The most common 80 source of the data that populates the partition. The most common
75 value for this option is "rootfs", but you can use any value that 81 value for this option is "rootfs", but you can use any value that
76 maps to a valid source plugin. For information on the source plugins, 82 maps to a valid source plugin. For information on the source plugins,
77 see the "`Using the Wic Plugins 83 see the ":ref:`dev-manual/dev-manual-common-tasks:using the wic plugin interface`"
78 Interface <&YOCTO_DOCS_DEV_URL;#wic-using-the-wic-plugin-interface>`__"
79 section in the Yocto Project Development Tasks Manual. 84 section in the Yocto Project Development Tasks Manual.
80 85
81 If you use ``--source rootfs``, Wic creates a partition as large as 86 If you use ``--source rootfs``, Wic creates a partition as large as
@@ -98,10 +103,10 @@ the ``part`` and ``partition`` commands:
98 creates an empty partition. Consequently, you must use the ``--size`` 103 creates an empty partition. Consequently, you must use the ``--size``
99 option to specify the size of the empty partition. 104 option to specify the size of the empty partition.
100 105
101- *``--ondisk`` or ``--ondrive``:* Forces the partition to be created 106- ``--ondisk`` or ``--ondrive``: Forces the partition to be created
102 on a particular disk. 107 on a particular disk.
103 108
104- *``--fstype``:* Sets the file system type for the partition. Valid 109- ``--fstype``: Sets the file system type for the partition. Valid
105 values are: 110 values are:
106 111
107 - ``ext4`` 112 - ``ext4``
@@ -116,66 +121,66 @@ the ``part`` and ``partition`` commands:
116 121
117 - ``swap`` 122 - ``swap``
118 123
119- *``--fsoptions``:* Specifies a free-form string of options to be used 124- ``--fsoptions``: Specifies a free-form string of options to be used
120 when mounting the filesystem. This string is copied into the 125 when mounting the filesystem. This string is copied into the
121 ``/etc/fstab`` file of the installed system and should be enclosed in 126 ``/etc/fstab`` file of the installed system and should be enclosed in
122 quotes. If not specified, the default string is "defaults". 127 quotes. If not specified, the default string is "defaults".
123 128
124- *``--label label``:* Specifies the label to give to the filesystem to 129- ``--label label``: Specifies the label to give to the filesystem to
125 be made on the partition. If the given label is already in use by 130 be made on the partition. If the given label is already in use by
126 another filesystem, a new label is created for the partition. 131 another filesystem, a new label is created for the partition.
127 132
128- *``--active``:* Marks the partition as active. 133- ``--active``: Marks the partition as active.
129 134
130- *``--align (in KBytes)``:* This option is a Wic-specific option that 135- ``--align (in KBytes)``: This option is a Wic-specific option that
131 says to start partitions on boundaries given x KBytes. 136 says to start partitions on boundaries given x KBytes.
132 137
133- *``--no-table``:* This option is a Wic-specific option. Using the 138- ``--no-table``: This option is a Wic-specific option. Using the
134 option reserves space for the partition and causes it to become 139 option reserves space for the partition and causes it to become
135 populated. However, the partition is not added to the partition 140 populated. However, the partition is not added to the partition
136 table. 141 table.
137 142
138- *``--exclude-path``:* This option is a Wic-specific option that 143- ``--exclude-path``: This option is a Wic-specific option that
139 excludes the given relative path from the resulting image. This 144 excludes the given relative path from the resulting image. This
140 option is only effective with the rootfs source plugin. 145 option is only effective with the rootfs source plugin.
141 146
142- *``--extra-space``:* This option is a Wic-specific option that adds 147- ``--extra-space``: This option is a Wic-specific option that adds
143 extra space after the space filled by the content of the partition. 148 extra space after the space filled by the content of the partition.
144 The final size can exceed the size specified by the ``--size`` 149 The final size can exceed the size specified by the ``--size``
145 option. The default value is 10 Mbytes. 150 option. The default value is 10 Mbytes.
146 151
147- *``--overhead-factor``:* This option is a Wic-specific option that 152- ``--overhead-factor``: This option is a Wic-specific option that
148 multiplies the size of the partition by the option's value. You must 153 multiplies the size of the partition by the option's value. You must
149 supply a value greater than or equal to "1". The default value is 154 supply a value greater than or equal to "1". The default value is
150 "1.3". 155 "1.3".
151 156
152- *``--part-name``:* This option is a Wic-specific option that 157- ``--part-name``: This option is a Wic-specific option that
153 specifies a name for GPT partitions. 158 specifies a name for GPT partitions.
154 159
155- *``--part-type``:* This option is a Wic-specific option that 160- ``--part-type``: This option is a Wic-specific option that
156 specifies the partition type globally unique identifier (GUID) for 161 specifies the partition type globally unique identifier (GUID) for
157 GPT partitions. You can find the list of partition type GUIDs at 162 GPT partitions. You can find the list of partition type GUIDs at
158 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs. 163 http://en.wikipedia.org/wiki/GUID_Partition_Table#Partition_type_GUIDs.
159 164
160- *``--use-uuid``:* This option is a Wic-specific option that causes 165- ``--use-uuid``: This option is a Wic-specific option that causes
161 Wic to generate a random GUID for the partition. The generated 166 Wic to generate a random GUID for the partition. The generated
162 identifier is used in the bootloader configuration to specify the 167 identifier is used in the bootloader configuration to specify the
163 root partition. 168 root partition.
164 169
165- *``--uuid``:* This option is a Wic-specific option that specifies the 170- ``--uuid``: This option is a Wic-specific option that specifies the
166 partition UUID. 171 partition UUID.
167 172
168- *``--fsuuid``:* This option is a Wic-specific option that specifies 173- ``--fsuuid``: This option is a Wic-specific option that specifies
169 the filesystem UUID. You can generate or modify 174 the filesystem UUID. You can generate or modify
170 :term:`WKS_FILE` with this option if a preconfigured 175 :term:`WKS_FILE` with this option if a preconfigured
171 filesystem UUID is added to the kernel command line in the bootloader 176 filesystem UUID is added to the kernel command line in the bootloader
172 configuration before you run Wic. 177 configuration before you run Wic.
173 178
174- *``--system-id``:* This option is a Wic-specific option that 179- ``--system-id``: This option is a Wic-specific option that
175 specifies the partition system ID, which is a one byte long, 180 specifies the partition system ID, which is a one byte long,
176 hexadecimal parameter with or without the 0x prefix. 181 hexadecimal parameter with or without the 0x prefix.
177 182
178- *``--mkfs-extraopts``:* This option specifies additional options to 183- ``--mkfs-extraopts``: This option specifies additional options to
179 pass to the ``mkfs`` utility. Some default options for certain 184 pass to the ``mkfs`` utility. Some default options for certain
180 filesystems do not take effect. See Wic's help on kickstart (i.e. 185 filesystems do not take effect. See Wic's help on kickstart (i.e.
181 ``wic help kickstart``). 186 ``wic help kickstart``).
@@ -195,13 +200,13 @@ supports the following options:
195 command essentially provides a means of modifying bootloader 200 command essentially provides a means of modifying bootloader
196 configuration. 201 configuration.
197 202
198- *``--timeout``:* Specifies the number of seconds before the 203- ``--timeout``: Specifies the number of seconds before the
199 bootloader times out and boots the default option. 204 bootloader times out and boots the default option.
200 205
201- *``--append``:* Specifies kernel parameters. These parameters will be 206- ``--append``: Specifies kernel parameters. These parameters will be
202 added to the syslinux ``APPEND`` or ``grub`` kernel command line. 207 added to the syslinux ``APPEND`` or ``grub`` kernel command line.
203 208
204- *``--configfile``:* Specifies a user-defined configuration file for 209- ``--configfile``: Specifies a user-defined configuration file for
205 the bootloader. You can provide a full pathname for the file or a 210 the bootloader. You can provide a full pathname for the file or a
206 file that exists in the ``canned-wks`` folder. This option overrides 211 file that exists in the ``canned-wks`` folder. This option overrides
207 all other bootloader options. 212 all other bootloader options.
diff --git a/documentation/ref-manual/ref-qa-checks.rst b/documentation/ref-manual/ref-qa-checks.rst
index a56de690b1..3e76ac1509 100644
--- a/documentation/ref-manual/ref-qa-checks.rst
+++ b/documentation/ref-manual/ref-qa-checks.rst
@@ -209,7 +209,10 @@ Errors and Warnings
209 Typically, the way to solve this performance issue is to add "-fPIC" 209 Typically, the way to solve this performance issue is to add "-fPIC"
210 or "-fpic" to the compiler command-line options. For example, given 210 or "-fpic" to the compiler command-line options. For example, given
211 software that reads :term:`CFLAGS` when you build it, 211 software that reads :term:`CFLAGS` when you build it,
212 you could add the following to your recipe: CFLAGS_append = " -fPIC " 212 you could add the following to your recipe:
213 ::
214
215 CFLAGS_append = " -fPIC "
213 216
214 For more information on text relocations at runtime, see 217 For more information on text relocations at runtime, see
215 http://www.akkadia.org/drepper/textrelocs.html. 218 http://www.akkadia.org/drepper/textrelocs.html.
@@ -224,7 +227,10 @@ Errors and Warnings
224 variable is being passed to the linker command. A common workaround 227 variable is being passed to the linker command. A common workaround
225 for this situation is to pass in ``LDFLAGS`` using 228 for this situation is to pass in ``LDFLAGS`` using
226 :term:`TARGET_CC_ARCH` within the recipe as 229 :term:`TARGET_CC_ARCH` within the recipe as
227 follows: TARGET_CC_ARCH += "${LDFLAGS}" 230 follows:
231 ::
232
233 TARGET_CC_ARCH += "${LDFLAGS}"
228 234
229   235  
230 236
@@ -244,10 +250,11 @@ Errors and Warnings
244 250
245 The ``/usr/share/info/dir`` should not be packaged. Add the following 251 The ``/usr/share/info/dir`` should not be packaged. Add the following
246 line to your :ref:`ref-tasks-install` task or to your 252 line to your :ref:`ref-tasks-install` task or to your
247 ``do_install_append`` within the recipe as follows: rm 253 ``do_install_append`` within the recipe as follows:
248 ${D}${infodir}/dir 254 ::
249 255
250   256 rm ${D}${infodir}/dir
257  
251 258
252- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]`` 259- ``Symlink <path> in <packagename> points to TMPDIR [symlink-to-sysroot]``
253 260
diff --git a/documentation/ref-manual/ref-release-process.rst b/documentation/ref-manual/ref-release-process.rst
index 7b33c0ae6b..be041e7254 100644
--- a/documentation/ref-manual/ref-release-process.rst
+++ b/documentation/ref-manual/ref-release-process.rst
@@ -17,8 +17,13 @@ month cadence roughly timed each April and October of the year.
17Following are examples of some major YP releases with their codenames 17Following are examples of some major YP releases with their codenames
18also shown. See the "`Major Release 18also shown. See the "`Major Release
19Codenames <#major-release-codenames>`__" section for information on 19Codenames <#major-release-codenames>`__" section for information on
20codenames used with major releases. 2.2 (Morty) 2.1 (Krogoth) 2.0 20codenames used with major releases.
21(Jethro) While the cadence is never perfect, this timescale facilitates 21
22 - 2.2 (Morty)
23 - 2.1 (Krogoth)
24 - 2.0 (Jethro)
25
26While the cadence is never perfect, this timescale facilitates
22regular releases that have strong QA cycles while not overwhelming users 27regular releases that have strong QA cycles while not overwhelming users
23with too many new releases. The cadence is predictable and avoids many 28with too many new releases. The cadence is predictable and avoids many
24major holidays in various geographies. 29major holidays in various geographies.
@@ -26,7 +31,13 @@ major holidays in various geographies.
26The Yocto project delivers minor (point) releases on an unscheduled 31The Yocto project delivers minor (point) releases on an unscheduled
27basis and are usually driven by the accumulation of enough significant 32basis and are usually driven by the accumulation of enough significant
28fixes or enhancements to the associated major release. Following are 33fixes or enhancements to the associated major release. Following are
29some example past point releases: 2.1.1 2.1.2 2.2.1 The point release 34some example past point releases:
35
36 - 2.1.1
37 - 2.1.2
38 - 2.2.1
39
40The point release
30indicates a point in the major release branch where a full QA cycle and 41indicates a point in the major release branch where a full QA cycle and
31release process validates the content of the new branch. 42release process validates the content of the new branch.
32 43
@@ -39,9 +50,8 @@ Major Release Codenames
39======================= 50=======================
40 51
41Each major release receives a codename that identifies the release in 52Each major release receives a codename that identifies the release in
42the `Yocto Project Source 53the :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories`.
43Repositories <&YOCTO_DOCS_OM_URL;#yocto-project-repositories>`__. The 54The concept is that branches of :term:`Metadata` with the same
44concept is that branches of :term:`Metadata` with the same
45codename are likely to be compatible and thus work together. 55codename are likely to be compatible and thus work together.
46 56
47.. note:: 57.. note::
@@ -95,9 +105,8 @@ provide the Yocto Project team a way to ensure a release is validated.
95Additionally, because the test strategies are visible to you as a 105Additionally, because the test strategies are visible to you as a
96developer, you can validate your projects. This section overviews the 106developer, you can validate your projects. This section overviews the
97available test infrastructure used in the Yocto Project. For information 107available test infrastructure used in the Yocto Project. For information
98on how to run available tests on your projects, see the "`Performing 108on how to run available tests on your projects, see the
99Automated Runtime 109":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
100Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
101section in the Yocto Project Development Tasks Manual. 110section in the Yocto Project Development Tasks Manual.
102 111
103The QA/testing infrastructure is woven into the project to the point 112The QA/testing infrastructure is woven into the project to the point
@@ -119,12 +128,12 @@ consists of the following pieces:
119 128
120- :ref:`testimage.bbclass <ref-classes-testimage*>`: This class 129- :ref:`testimage.bbclass <ref-classes-testimage*>`: This class
121 performs runtime testing of images after they are built. The tests 130 performs runtime testing of images after they are built. The tests
122 are usually used with `QEMU <&YOCTO_DOCS_DEV_URL;#dev-manual-qemu>`__ 131 are usually used with :doc:`QEMU <../dev-manual/dev-manual-qemu>`
123 to boot the images and check the combined runtime result boot 132 to boot the images and check the combined runtime result boot
124 operation and functions. However, the test can also use the IP 133 operation and functions. However, the test can also use the IP
125 address of a machine to test. 134 address of a machine to test.
126 135
127- ```ptest`` <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__: 136- :ref:`ptest <dev-manual/dev-manual-common-tasks:testing packages with ptest>`:
128 Runs tests against packages produced during the build for a given 137 Runs tests against packages produced during the build for a given
129 piece of software. The test allows the packages to be be run within a 138 piece of software. The test allows the packages to be be run within a
130 target image. 139 target image.
@@ -147,7 +156,7 @@ effort has been made to automate the tests so that more people can use
147them and the Yocto Project development team can run them faster and more 156them and the Yocto Project development team can run them faster and more
148efficiently. 157efficiently.
149 158
150The Yocto Project's main Autobuilder (``autobuilder.yoctoproject.org``) 159The Yocto Project's main Autobuilder (https://autobuilder.yoctoproject.org/)
151publicly tests each Yocto Project release's code in the 160publicly tests each Yocto Project release's code in the
152:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing 161:term:`OpenEmbedded-Core (OE-Core)`, Poky, and BitBake repositories. The testing
153occurs for both the current state of the "master" branch and also for 162occurs for both the current state of the "master" branch and also for
diff --git a/documentation/ref-manual/ref-structure.rst b/documentation/ref-manual/ref-structure.rst
index 1efb81414f..48a443331b 100644
--- a/documentation/ref-manual/ref-structure.rst
+++ b/documentation/ref-manual/ref-structure.rst
@@ -11,8 +11,8 @@ describes the Source Directory and gives information about those files
11and directories. 11and directories.
12 12
13For information on how to establish a local Source Directory on your 13For information on how to establish a local Source Directory on your
14development system, see the "`Locating Yocto Project Source 14development system, see the
15Files <&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files>`__" 15":ref:`dev-manual/dev-manual-start:locating yocto project source files`"
16section in the Yocto Project Development Tasks Manual. 16section in the Yocto Project Development Tasks Manual.
17 17
18.. note:: 18.. note::
@@ -42,7 +42,7 @@ itself; consequently, most users do not need to worry about BitBake.
42 42
43When you run the ``bitbake`` command, the main BitBake executable (which 43When you run the ``bitbake`` command, the main BitBake executable (which
44resides in the ``bitbake/bin/`` directory) starts. Sourcing the 44resides in the ``bitbake/bin/`` directory) starts. Sourcing the
45environment setup script (i.e. ````` <#structure-core-script>`__) places 45environment setup script (i.e. :ref:`structure-core-script`) places
46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into 46the ``scripts/`` and ``bitbake/bin/`` directories (in that order) into
47the shell's ``PATH`` environment variable. 47the shell's ``PATH`` environment variable.
48 48
@@ -59,14 +59,14 @@ generated by the OpenEmbedded build system in its standard configuration
59where the source tree is combined with the output. The :term:`Build Directory` 59where the source tree is combined with the output. The :term:`Build Directory`
60is created initially when you ``source`` 60is created initially when you ``source``
61the OpenEmbedded build environment setup script (i.e. 61the OpenEmbedded build environment setup script (i.e.
62````` <#structure-core-script>`__). 62:ref:`structure-core-script`).
63 63
64It is also possible to place output and configuration files in a 64It is also possible to place output and configuration files in a
65directory separate from the :term:`Source Directory` by 65directory separate from the :term:`Source Directory` by
66providing a directory name when you ``source`` the setup script. For 66providing a directory name when you ``source`` the setup script. For
67information on separating output from your local Source Directory files 67information on separating output from your local Source Directory files
68(commonly described as an "out of tree" build), see the 68(commonly described as an "out of tree" build), see the
69"````` <#structure-core-script>`__" section. 69":ref:`structure-core-script`" section.
70 70
71.. _handbook: 71.. _handbook:
72 72
@@ -103,9 +103,8 @@ metadata to define the Poky reference distribution.
103------------------- 103-------------------
104 104
105This directory contains the Yocto Project reference hardware Board 105This directory contains the Yocto Project reference hardware Board
106Support Packages (BSPs). For more information on BSPs, see the `Yocto 106Support Packages (BSPs). For more information on BSPs, see the
107Project Board Support Package (BSP) Developer's 107:doc:`../bsp-guide/bsp-guide`.
108Guide <&YOCTO_DOCS_BSP_URL;>`__.
109 108
110.. _structure-meta-selftest: 109.. _structure-meta-selftest:
111 110
@@ -131,7 +130,7 @@ This directory contains template recipes for BSP and kernel development.
131 130
132This directory contains various integration scripts that implement extra 131This directory contains various integration scripts that implement extra
133functionality in the Yocto Project environment (e.g. QEMU scripts). The 132functionality in the Yocto Project environment (e.g. QEMU scripts). The
134````` <#structure-core-script>`__ script prepends this directory to the 133:ref:`structure-core-script` script prepends this directory to the
135shell's ``PATH`` environment variable. 134shell's ``PATH`` environment variable.
136 135
137The ``scripts`` directory has useful scripts that assist in contributing 136The ``scripts`` directory has useful scripts that assist in contributing
@@ -154,18 +153,30 @@ When you run this script, your Yocto Project environment is set up, a
154:term:`Build Directory` is created, your working 153:term:`Build Directory` is created, your working
155directory becomes the Build Directory, and you are presented with some 154directory becomes the Build Directory, and you are presented with some
156simple suggestions as to what to do next, including a list of some 155simple suggestions as to what to do next, including a list of some
157possible targets to build. Here is an example: $ source 156possible targets to build. Here is an example:
158oe-init-build-env ### Shell environment set up for builds. ### You can 157::
159now run 'bitbake <target>' Common targets are: core-image-minimal 158
160core-image-sato meta-toolchain meta-ide-support You can also run 159 $ source oe-init-build-env
161generated qemu images with a command like 'runqemu qemux86-64' The 160
162default output of the ``oe-init-build-env`` script is from the 161 ### Shell environment set up for builds. ###
162
163 You can now run 'bitbake <target>'
164
165 Common targets are:
166 core-image-minimal
167 core-image-sato
168 meta-toolchain
169 meta-ide-support
170
171 You can also run generated qemu images with a command like 'runqemu qemux86-64'
172
173The default output of the ``oe-init-build-env`` script is from the
163``conf-notes.txt`` file, which is found in the ``meta-poky`` directory 174``conf-notes.txt`` file, which is found in the ``meta-poky`` directory
164within the :term:`Source Directory`. If you design a 175within the :term:`Source Directory`. If you design a
165custom distribution, you can include your own version of this 176custom distribution, you can include your own version of this
166configuration file to mention the targets defined by your distribution. 177configuration file to mention the targets defined by your distribution.
167See the "`Creating a Custom Template Configuration 178See the
168Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" 179":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
169section in the Yocto Project Development Tasks Manual for more 180section in the Yocto Project Development Tasks Manual for more
170information. 181information.
171 182
@@ -175,11 +186,14 @@ you provide a Build Directory argument when you ``source`` the script,
175you direct the OpenEmbedded build system to create a Build Directory of 186you direct the OpenEmbedded build system to create a Build Directory of
176your choice. For example, the following command creates a Build 187your choice. For example, the following command creates a Build
177Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`: 188Directory named ``mybuilds/`` that is outside of the :term:`Source Directory`:
178$ source OE_INIT_FILE ~/mybuilds The 189::
179OpenEmbedded build system uses the template configuration files, which 190
191 $ source OE_INIT_FILE ~/mybuilds
192
193The OpenEmbedded build system uses the template configuration files, which
180are found by default in the ``meta-poky/conf/`` directory in the Source 194are found by default in the ``meta-poky/conf/`` directory in the Source
181Directory. See the "`Creating a Custom Template Configuration 195Directory. See the
182Directory <&YOCTO_DOCS_DEV_URL;#creating-a-custom-template-configuration-directory>`__" 196":ref:`dev-manual/dev-manual-common-tasks:creating a custom template configuration directory`"
183section in the Yocto Project Development Tasks Manual for more 197section in the Yocto Project Development Tasks Manual for more
184information. 198information.
185 199
@@ -207,7 +221,7 @@ The Build Directory - ``build/``
207 221
208The OpenEmbedded build system creates the :term:`Build Directory` 222The OpenEmbedded build system creates the :term:`Build Directory`
209when you run the build environment setup 223when you run the build environment setup
210script ````` <#structure-core-script>`__. If you do not give the Build 224script :ref:`structure-core-script`. If you do not give the Build
211Directory a specific name when you run the setup script, the name 225Directory a specific name when you run the setup script, the name
212defaults to ``build/``. 226defaults to ``build/``.
213 227
@@ -223,8 +237,7 @@ The OpenEmbedded build system creates this directory when you enable
223build history via the ``buildhistory`` class file. The directory 237build history via the ``buildhistory`` class file. The directory
224organizes build information into image, packages, and SDK 238organizes build information into image, packages, and SDK
225subdirectories. For information on the build history feature, see the 239subdirectories. For information on the build history feature, see the
226"`Maintaining Build Output 240":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
227Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
228section in the Yocto Project Development Tasks Manual. 241section in the Yocto Project Development Tasks Manual.
229 242
230.. _structure-build-conf-local.conf: 243.. _structure-build-conf-local.conf:
@@ -248,7 +261,7 @@ which you want to access downloaded files (``DL_DIR``).
248If ``local.conf`` is not present when you start the build, the 261If ``local.conf`` is not present when you start the build, the
249OpenEmbedded build system creates it from ``local.conf.sample`` when you 262OpenEmbedded build system creates it from ``local.conf.sample`` when you
250``source`` the top-level build environment setup script 263``source`` the top-level build environment setup script
251````` <#structure-core-script>`__. 264:ref:`structure-core-script`.
252 265
253The source ``local.conf.sample`` file used depends on the 266The source ``local.conf.sample`` file used depends on the
254``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/`` 267``$TEMPLATECONF`` script variable, which defaults to ``meta-poky/conf/``
@@ -258,7 +271,11 @@ environment. Because the script variable points to the source of the
258``local.conf.sample`` file, this implies that you can configure your 271``local.conf.sample`` file, this implies that you can configure your
259build environment from any layer by setting the variable in the 272build environment from any layer by setting the variable in the
260top-level build environment setup script as follows: 273top-level build environment setup script as follows:
261TEMPLATECONF=your_layer/conf Once the build process gets the sample 274::
275
276 TEMPLATECONF=your_layer/conf
277
278Once the build process gets the sample
262file, it uses ``sed`` to substitute final 279file, it uses ``sed`` to substitute final
263``${``\ :term:`OEROOT`\ ``}`` values for all 280``${``\ :term:`OEROOT`\ ``}`` values for all
264``##OEROOT##`` values. 281``##OEROOT##`` values.
@@ -283,7 +300,7 @@ file, it uses ``sed`` to substitute final
283---------------------------- 300----------------------------
284 301
285This configuration file defines 302This configuration file defines
286`layers <&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers>`__, 303:ref:`layers <dev-manual/dev-manual-common-tasks:understanding and creating layers>`,
287which are directory trees, traversed (or walked) by BitBake. The 304which are directory trees, traversed (or walked) by BitBake. The
288``bblayers.conf`` file uses the :term:`BBLAYERS` 305``bblayers.conf`` file uses the :term:`BBLAYERS`
289variable to list the layers BitBake tries to find. 306variable to list the layers BitBake tries to find.
@@ -291,7 +308,7 @@ variable to list the layers BitBake tries to find.
291If ``bblayers.conf`` is not present when you start the build, the 308If ``bblayers.conf`` is not present when you start the build, the
292OpenEmbedded build system creates it from ``bblayers.conf.sample`` when 309OpenEmbedded build system creates it from ``bblayers.conf.sample`` when
293you ``source`` the top-level build environment setup script (i.e. 310you ``source`` the top-level build environment setup script (i.e.
294````` <#structure-core-script>`__). 311:ref:`structure-core-script`).
295 312
296As with the ``local.conf`` file, the source ``bblayers.conf.sample`` 313As with the ``local.conf`` file, the source ``bblayers.conf.sample``
297file used depends on the ``$TEMPLATECONF`` script variable, which 314file used depends on the ``$TEMPLATECONF`` script variable, which
@@ -301,10 +318,12 @@ building from the OpenEmbedded-Core environment. Because the script
301variable points to the source of the ``bblayers.conf.sample`` file, this 318variable points to the source of the ``bblayers.conf.sample`` file, this
302implies that you can base your build from any layer by setting the 319implies that you can base your build from any layer by setting the
303variable in the top-level build environment setup script as follows: 320variable in the top-level build environment setup script as follows:
304TEMPLATECONF=your_layer/conf Once the build process gets the sample 321::
305file, it uses ``sed`` to substitute final 322
306``${``\ :term:`OEROOT`\ ``}`` values for all 323 TEMPLATECONF=your_layer/conf
307``##OEROOT##`` values. 324
325Once the build process gets the sample file, it uses ``sed`` to substitute final
326``${``\ :term:`OEROOT`\ ``}`` values for all ``##OEROOT##`` values.
308 327
309.. note:: 328.. note::
310 329
@@ -395,9 +414,8 @@ This directory contains any "end result" output from the OpenEmbedded
395build process. The :term:`DEPLOY_DIR` variable points 414build process. The :term:`DEPLOY_DIR` variable points
396to this directory. For more detail on the contents of the ``deploy`` 415to this directory. For more detail on the contents of the ``deploy``
397directory, see the 416directory, see the
398"`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and 417":ref:`images-dev-environment`" and
399"`Application Development 418":ref:`sdk-dev-environment`" sections in the Yocto
400SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections in the Yocto
401Project Overview and Concepts Manual. 419Project Overview and Concepts Manual.
402 420
403.. _structure-build-tmp-deploy-deb: 421.. _structure-build-tmp-deploy-deb:
@@ -434,9 +452,8 @@ This directory receives package licensing information. For example, the
434directory contains sub-directories for ``bash``, ``busybox``, and 452directory contains sub-directories for ``bash``, ``busybox``, and
435``glibc`` (among others) that in turn contain appropriate ``COPYING`` 453``glibc`` (among others) that in turn contain appropriate ``COPYING``
436license files with other licensing information. For information on 454license files with other licensing information. For information on
437licensing, see the "`Maintaining Open Source License Compliance During 455licensing, see the
438Your Product's 456":ref:`dev-manual/dev-manual-common-tasks:maintaining open source license compliance during your product's lifecycle`"
439Lifecycle <&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle>`__"
440section in the Yocto Project Development Tasks Manual. 457section in the Yocto Project Development Tasks Manual.
441 458
442.. _structure-build-tmp-deploy-images: 459.. _structure-build-tmp-deploy-images:
@@ -461,8 +478,11 @@ image again.
461If you do accidentally delete files here, you will need to force them to 478If you do accidentally delete files here, you will need to force them to
462be re-created. In order to do that, you will need to know the target 479be re-created. In order to do that, you will need to know the target
463that produced them. For example, these commands rebuild and re-create 480that produced them. For example, these commands rebuild and re-create
464the kernel files: $ bitbake -c clean virtual/kernel $ bitbake 481the kernel files:
465virtual/kernel 482::
483
484 $ bitbake -c clean virtual/kernel
485 $ bitbake virtual/kernel
466 486
467.. _structure-build-tmp-deploy-sdk: 487.. _structure-build-tmp-deploy-sdk:
468 488
@@ -472,8 +492,7 @@ virtual/kernel
472The OpenEmbedded build system creates this directory to hold toolchain 492The OpenEmbedded build system creates this directory to hold toolchain
473installer scripts which, when executed, install the sysroot that matches 493installer scripts which, when executed, install the sysroot that matches
474your target hardware. You can find out more about these installers in 494your target hardware. You can find out more about these installers in
475the "`Building an SDK 495the ":ref:`sdk-manual/sdk-appendix-obtain:building an sdk installer`"
476Installer <&YOCTO_DOCS_SDK_URL;#sdk-building-an-sdk-installer>`__"
477section in the Yocto Project Application Development and the Extensible 496section in the Yocto Project Application Development and the Extensible
478Software Development Kit (eSDK) manual. 497Software Development Kit (eSDK) manual.
479 498
@@ -540,8 +559,8 @@ the files in the directory are empty of data, BitBake uses the filenames
540and timestamps for tracking purposes. 559and timestamps for tracking purposes.
541 560
542For information on how BitBake uses stamp files to determine if a task 561For information on how BitBake uses stamp files to determine if a task
543should be rerun, see the "`Stamp Files and the Rerunning of 562should be rerun, see the
544Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__" 563":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`"
545section in the Yocto Project Overview and Concepts Manual. 564section in the Yocto Project Overview and Concepts Manual.
546 565
547.. _structure-build-tmp-log: 566.. _structure-build-tmp-log:
@@ -573,8 +592,7 @@ built within the Yocto Project. For this package, a work directory of
573``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred 592``tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+<.....>``, referred
574to as the ``WORKDIR``, is created. Within this directory, the source is 593to as the ``WORKDIR``, is created. Within this directory, the source is
575unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt. 594unpacked to ``linux-qemux86-standard-build`` and then patched by Quilt.
576(See the "`Using Quilt in Your 595(See the ":ref:`using-a-quilt-workflow`" section in
577Workflow <&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow>`__" section in
578the Yocto Project Development Tasks Manual for more information.) Within 596the Yocto Project Development Tasks Manual for more information.) Within
579the ``linux-qemux86-standard-build`` directory, standard Quilt 597the ``linux-qemux86-standard-build`` directory, standard Quilt
580directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and 598directories ``linux-3.0/patches`` and ``linux-3.0/.pc`` are created, and
diff --git a/documentation/ref-manual/ref-system-requirements.rst b/documentation/ref-manual/ref-system-requirements.rst
index b82bed8a76..56218e4ebb 100644
--- a/documentation/ref-manual/ref-system-requirements.rst
+++ b/documentation/ref-manual/ref-system-requirements.rst
@@ -14,18 +14,15 @@ descriptions, and so forth as needed during the course of using the
14Yocto Project. 14Yocto Project.
15 15
16For introductory information on the Yocto Project, see the 16For introductory information on the Yocto Project, see the
17:yocto_home:`Yocto Project Website <>` and the "`Yocto Project 17:yocto_home:`Yocto Project Website <>` and the
18Development 18":ref:`overview-manual/overview-manual-development-environment:the yocto project development environment`"
19Environment <&YOCTO_DOCS_OM_URL;#overview-development-environment>`__"
20chapter in the Yocto Project Overview and Concepts Manual. 19chapter in the Yocto Project Overview and Concepts Manual.
21 20
22If you want to use the Yocto Project to quickly build an image without 21If you want to use the Yocto Project to quickly build an image without
23having to understand concepts, work through the `Yocto Project Quick 22having to understand concepts, work through the
24Build <&YOCTO_DOCS_BRIEF_URL;>`__ document. You can find "how-to" 23:doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` document. You can find "how-to"
25information in the `Yocto Project Development Tasks 24information in the :doc:`../dev-manual/dev-manual`. You can find Yocto Project overview
26Manual <&YOCTO_DOCS_DEV_URL;>`__. You can find Yocto Project overview 25and conceptual information in the :doc:`../overview-manual/overview-manual`.
27and conceptual information in the `Yocto Project Overview and Concepts
28Manual <&YOCTO_DOCS_OM_URL;>`__.
29 26
30.. note:: 27.. note::
31 28
@@ -95,12 +92,11 @@ distributions:
95 WSLv2, if you still decide to use WSL please upgrade to WSLv2. 92 WSLv2, if you still decide to use WSL please upgrade to WSLv2.
96 93
97 - If you encounter problems, please go to `Yocto Project 94 - If you encounter problems, please go to `Yocto Project
98 Bugzilla <&YOCTO_BUGZILLA_URL;>`__ and submit a bug. We are 95 Bugzilla <http://bugzilla.yoctoproject.org>`__ and submit a bug. We are
99 interested in hearing about your experience. For information on 96 interested in hearing about your experience. For information on
100 how to submit a bug, see the Yocto Project 97 how to submit a bug, see the Yocto Project
101 :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` 98 :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
102 and the "`Submitting a Defect Against the Yocto 99 and the ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`"
103 Project <&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project>`__"
104 section in the Yocto Project Development Tasks Manual. 100 section in the Yocto Project Development Tasks Manual.
105 101
106 102
@@ -126,19 +122,28 @@ supported Ubuntu or Debian Linux distribution:
126 might experience QEMU build failures due to the package installing 122 might experience QEMU build failures due to the package installing
127 its own custom ``/usr/include/linux/soundcard.h`` on the Debian 123 its own custom ``/usr/include/linux/soundcard.h`` on the Debian
128 system. If you run into this situation, either of the following 124 system. If you run into this situation, either of the following
129 solutions exist: $ sudo apt-get build-dep qemu $ sudo apt-get 125 solutions exist:
130 remove oss4-dev 126 ::
127
128 $ sudo apt-get build-dep qemu
129 $ sudo apt-get remove oss4-dev
131 130
132 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer 131 - For Debian-8, ``python3-git`` and ``pylint3`` are no longer
133 available via ``apt-get``. $ sudo pip3 install GitPython 132 available via ``apt-get``.
134 pylint==1.9.5 133 ::
134
135 $ sudo pip3 install GitPython pylint==1.9.5
135 136
136- *Essentials:* Packages needed to build an image on a headless system: 137- *Essentials:* Packages needed to build an image on a headless system:
137 $ sudo apt-get install UBUNTU_HOST_PACKAGES_ESSENTIAL 138 ::
139
140 $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
138 141
139- *Documentation:* Packages needed if you are going to build out the 142- *Documentation:* Packages needed if you are going to build out the
140 Yocto Project documentation manuals: $ sudo apt-get install make 143 Yocto Project documentation manuals:
141 xsltproc docbook-utils fop dblatex xmlto 144 ::
145
146 $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
142 147
143Fedora Packages 148Fedora Packages
144--------------- 149---------------
@@ -147,12 +152,17 @@ The following list shows the required packages by function given a
147supported Fedora Linux distribution: 152supported Fedora Linux distribution:
148 153
149- *Essentials:* Packages needed to build an image for a headless 154- *Essentials:* Packages needed to build an image for a headless
150 system: $ sudo dnf install FEDORA_HOST_PACKAGES_ESSENTIAL 155 system:
156 ::
157
158 $ sudo dnf install &FEDORA_HOST_PACKAGES_ESSENTIAL;
151 159
152- *Documentation:* Packages needed if you are going to build out the 160- *Documentation:* Packages needed if you are going to build out the
153 Yocto Project documentation manuals: $ sudo dnf install 161 Yocto Project documentation manuals:
154 docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils 162 ::
155 fop libxslt dblatex xmlto 163
164 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \
165 docbook-dtds docbook-utils fop libxslt dblatex xmlto
156 166
157openSUSE Packages 167openSUSE Packages
158----------------- 168-----------------
@@ -161,7 +171,10 @@ The following list shows the required packages by function given a
161supported openSUSE Linux distribution: 171supported openSUSE Linux distribution:
162 172
163- *Essentials:* Packages needed to build an image for a headless 173- *Essentials:* Packages needed to build an image for a headless
164 system: $ sudo zypper install OPENSUSE_HOST_PACKAGES_ESSENTIAL 174 system:
175 ::
176
177 $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
165 178
166- *Documentation:* Packages needed if you are going to build out the 179- *Documentation:* Packages needed if you are going to build out the
167 Yocto Project documentation manuals: $ sudo zypper install dblatex 180 Yocto Project documentation manuals: $ sudo zypper install dblatex
@@ -174,7 +187,10 @@ The following list shows the required packages by function given a
174supported CentOS-7 Linux distribution: 187supported CentOS-7 Linux distribution:
175 188
176- *Essentials:* Packages needed to build an image for a headless 189- *Essentials:* Packages needed to build an image for a headless
177 system: $ sudo yum install CENTOS7_HOST_PACKAGES_ESSENTIAL 190 system:
191 ::
192
193 $ sudo yum install &CENTOS7_HOST_PACKAGES_ESSENTIAL;
178 194
179 .. note:: 195 .. note::
180 196
@@ -187,9 +203,11 @@ supported CentOS-7 Linux distribution:
187 ``epel-release``. 203 ``epel-release``.
188 204
189- *Documentation:* Packages needed if you are going to build out the 205- *Documentation:* Packages needed if you are going to build out the
190 Yocto Project documentation manuals: $ sudo yum install 206 Yocto Project documentation manuals:
191 docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils 207 ::
192 fop libxslt dblatex xmlto 208
209 $ sudo yum install docbook-style-dsssl docbook-style-xsl \
210 docbook-dtds docbook-utils fop libxslt dblatex xmlto
193 211
194CentOS-8 Packages 212CentOS-8 Packages
195----------------- 213-----------------
@@ -198,7 +216,10 @@ The following list shows the required packages by function given a
198supported CentOS-8 Linux distribution: 216supported CentOS-8 Linux distribution:
199 217
200- *Essentials:* Packages needed to build an image for a headless 218- *Essentials:* Packages needed to build an image for a headless
201 system: $ sudo dnf install CENTOS8_HOST_PACKAGES_ESSENTIAL 219 system:
220 ::
221
222 $ sudo dnf install &CENTOS8_HOST_PACKAGES_ESSENTIAL;
202 223
203 .. note:: 224 .. note::
204 225
@@ -214,9 +235,11 @@ supported CentOS-8 Linux distribution:
214 ``epel-release``. 235 ``epel-release``.
215 236
216- *Documentation:* Packages needed if you are going to build out the 237- *Documentation:* Packages needed if you are going to build out the
217 Yocto Project documentation manuals: $ sudo dnf install 238 Yocto Project documentation manuals:
218 docbook-style-dsssl docbook-style-xsl \\ docbook-dtds docbook-utils 239 ::
219 fop libxslt dblatex xmlto 240
241 $ sudo dnf install docbook-style-dsssl docbook-style-xsl \\
242 docbook-dtds docbook-utils fop libxslt dblatex xmlto
220 243
221Required Git, tar, Python and gcc Versions 244Required Git, tar, Python and gcc Versions
222========================================== 245==========================================
@@ -251,10 +274,14 @@ The ``install-buildtools`` script is the easiest of the three methods by
251which you can get these tools. It downloads a pre-built buildtools 274which you can get these tools. It downloads a pre-built buildtools
252installer and automatically installs the tools for you: 275installer and automatically installs the tools for you:
253 276
2541. Execute the ``install-buildtools`` script. Here is an example: $ cd 2771. Execute the ``install-buildtools`` script. Here is an example:
255 poky $ scripts/install-buildtools --without-extended-buildtools \\ 278 ::
256 --base-url https://downloads.yoctoproject.org/releases/yocto \\ --release yocto-DISTRO \\ 279
257 --installer-version DISTRO 280 $ cd poky
281 $ scripts/install-buildtools --without-extended-buildtools \
282 --base-url https://downloads.yoctoproject.org/releases/yocto \
283 --release yocto-&DISTRO; \
284 --installer-version &DISTRO;
258 285
259 During execution, the buildtools tarball will be downloaded, the 286 During execution, the buildtools tarball will be downloaded, the
260 checksum of the download will be verified, the installer will be run 287 checksum of the download will be verified, the installer will be run
@@ -263,17 +290,25 @@ installer and automatically installs the tools for you:
263 290
264 To avoid the need of ``sudo`` privileges, the ``install-buildtools`` 291 To avoid the need of ``sudo`` privileges, the ``install-buildtools``
265 script will by default tell the installer to install in: 292 script will by default tell the installer to install in:
266 /path/to/poky/buildtools 293 ::
294
295 /path/to/poky/buildtools
267 296
268 If your host development system needs the additional tools provided 297 If your host development system needs the additional tools provided
269 in the ``buildtools-extended`` tarball, you can instead execute the 298 in the ``buildtools-extended`` tarball, you can instead execute the
270 ``install-buildtools`` script with the default parameters: $ cd poky 299 ``install-buildtools`` script with the default parameters:
271 $ scripts/install-buildtools 300 ::
301
302 $ cd poky
303 $ scripts/install-buildtools
272 304
2732. Source the tools environment setup script by using a command like the 3052. Source the tools environment setup script by using a command like the
274 following: $ source 306 following:
275 /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux Of 307 ::
276 course, you need to supply your installation directory and be sure to 308
309 $ source /path/to/poky/buildtools/environment-setup-x86_64-pokysdk-linux
310
311 Of course, you need to supply your installation directory and be sure to
277 use the right file (i.e. i586 or x86_64). 312 use the right file (i.e. i586 or x86_64).
278 313
279 After you have sourced the setup script, the tools are added to 314 After you have sourced the setup script, the tools are added to
@@ -290,21 +325,30 @@ Downloading a Pre-Built ``buildtools`` Tarball
290Downloading and running a pre-built buildtools installer is the easiest 325Downloading and running a pre-built buildtools installer is the easiest
291of the two methods by which you can get these tools: 326of the two methods by which you can get these tools:
292 327
2931. Locate and download the ``*.sh`` at 3281. Locate and download the ``*.sh`` at &YOCTO_RELEASE_DL_URL;/buildtools/
294 ` <&YOCTO_RELEASE_DL_URL;/buildtools/>`__.
295 329
2962. Execute the installation script. Here is an example for the 3302. Execute the installation script. Here is an example for the
297 traditional installer: $ sh 331 traditional installer:
298 ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh Here is 332 ::
299 an example for the extended installer: $ sh 333
300 ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh 334 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh
335
336 Here is an example for the extended installer:
337 ::
338
339 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh
340
301 During execution, a prompt appears that allows you to choose the 341 During execution, a prompt appears that allows you to choose the
302 installation directory. For example, you could choose the following: 342 installation directory. For example, you could choose the following:
303 /home/your-username/buildtools 343 /home/your-username/buildtools
304 344
3053. Source the tools environment setup script by using a command like the 3453. Source the tools environment setup script by using a command like the
306 following: $ source 346 following:
307 /home/your_username/buildtools/environment-setup-i586-poky-linux Of 347 ::
348
349 $ source /home/your_username/buildtools/environment-setup-i586-poky-linux
350
351 Of
308 course, you need to supply your installation directory and be sure to 352 course, you need to supply your installation directory and be sure to
309 use the right file (i.e. i585 or x86-64). 353 use the right file (i.e. i585 or x86-64).
310 354
@@ -330,11 +374,17 @@ installer:
330 374
3311. On the machine that is able to run BitBake, be sure you have set up 3751. On the machine that is able to run BitBake, be sure you have set up
332 your build environment with the setup script 376 your build environment with the setup script
333 (````` <#structure-core-script>`__). 377 (:ref:`structure-core-script`).
378
3792. Run the BitBake command to build the tarball:
380 ::
381
382 $ bitbake buildtools-tarball
334 383
3352. Run the BitBake command to build the tarball: $ bitbake 384 or run the BitBake command to build the extended tarball:
336 buildtools-tarball or run the BitBake command to build the extended 385 ::
337 tarball: $ bitbake buildtools-extended-tarball 386
387 $ bitbake buildtools-extended-tarball
338 388
339 .. note:: 389 .. note::
340 390
@@ -355,18 +405,27 @@ installer:
355 405
3564. On the machine that does not meet the requirements, run the ``.sh`` 4064. On the machine that does not meet the requirements, run the ``.sh``
357 file to install the tools. Here is an example for the traditional 407 file to install the tools. Here is an example for the traditional
358 installer: $ sh 408 installer:
359 ~/Downloads/x86_64-buildtools-nativesdk-standalone-DISTRO.sh Here is 409 ::
360 an example for the extended installer: $ sh 410
361 ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-DISTRO.sh 411 $ sh ~/Downloads/x86_64-buildtools-nativesdk-standalone-&DISTRO;.sh
412
413 Here is an example for the extended installer:
414 ::
415
416 $ sh ~/Downloads/x86_64-buildtools-extended-nativesdk-standalone-&DISTRO;.sh
417
362 During execution, a prompt appears that allows you to choose the 418 During execution, a prompt appears that allows you to choose the
363 installation directory. For example, you could choose the following: 419 installation directory. For example, you could choose the following:
364 /home/your_username/buildtools 420 /home/your_username/buildtools
365 421
3665. Source the tools environment setup script by using a command like the 4225. Source the tools environment setup script by using a command like the
367 following: $ source 423 following:
368 /home/your_username/buildtools/environment-setup-x86_64-poky-linux Of 424 ::
369 course, you need to supply your installation directory and be sure to 425
426 $ source /home/your_username/buildtools/environment-setup-x86_64-poky-linux
427
428 Of course, you need to supply your installation directory and be sure to
370 use the right file (i.e. i586 or x86_64). 429 use the right file (i.e. i586 or x86_64).
371 430
372 After you have sourced the setup script, the tools are added to 431 After you have sourced the setup script, the tools are added to
diff --git a/documentation/ref-manual/ref-tasks.rst b/documentation/ref-manual/ref-tasks.rst
index 5b0711586f..44463f2236 100644
--- a/documentation/ref-manual/ref-tasks.rst
+++ b/documentation/ref-manual/ref-tasks.rst
@@ -109,7 +109,7 @@ after other tasks works the same way.
109 :: 109 ::
110 110
111 do_build[recrdeptask] += "do_deploy" 111 do_build[recrdeptask] += "do_deploy"
112 112
113 113
114 See the " 114 See the "
115 Dependencies 115 Dependencies
@@ -143,8 +143,7 @@ The ``do_image`` task performs pre-processing on the image through the
143:term:`IMAGE_PREPROCESS_COMMAND` and 143:term:`IMAGE_PREPROCESS_COMMAND` and
144dynamically generates supporting ``do_image_*`` tasks as needed. 144dynamically generates supporting ``do_image_*`` tasks as needed.
145 145
146For more information on image creation, see the "`Image 146For more information on image creation, see the ":ref:`image-generation-dev-environment`"
147Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
148section in the Yocto Project Overview and Concepts Manual. 147section in the Yocto Project Overview and Concepts Manual.
149 148
150.. _ref-tasks-image-complete: 149.. _ref-tasks-image-complete:
@@ -162,8 +161,8 @@ The ``do_image_complete`` task performs post-processing on the image
162through the 161through the
163:term:`IMAGE_POSTPROCESS_COMMAND`. 162:term:`IMAGE_POSTPROCESS_COMMAND`.
164 163
165For more information on image creation, see the "`Image 164For more information on image creation, see the
166Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__" 165":ref:`image-generation-dev-environment`"
167section in the Yocto Project Overview and Concepts Manual. 166section in the Yocto Project Overview and Concepts Manual.
168 167
169.. _ref-tasks-install: 168.. _ref-tasks-install:
@@ -176,10 +175,9 @@ Copies files that are to be packaged into the holding area
176working directory set to ``${``\ :term:`B`\ ``}``, which is the 175working directory set to ``${``\ :term:`B`\ ``}``, which is the
177compilation directory. The ``do_install`` task, as well as other tasks 176compilation directory. The ``do_install`` task, as well as other tasks
178that either directly or indirectly depend on the installed files (e.g. 177that either directly or indirectly depend on the installed files (e.g.
179:ref:`ref-tasks-package`, 178:ref:`ref-tasks-package`, ``do_package_write_*``, and
180```do_package_write_*`` <#ref-tasks-package_write_deb>`__, and
181:ref:`ref-tasks-rootfs`), run under 179:ref:`ref-tasks-rootfs`), run under
182`fakeroot <&YOCTO_DOCS_OM_URL;#fakeroot-and-pseudo>`__. 180:ref:`fakeroot <overview-manual/overview-manual-concepts:fakeroot and pseudo>`.
183 181
184.. note:: 182.. note::
185 183
@@ -187,9 +185,8 @@ that either directly or indirectly depend on the installed files (e.g.
187 of the installed files to unintended values. Some methods of copying 185 of the installed files to unintended values. Some methods of copying
188 files, notably when using the recursive ``cp`` command, can preserve 186 files, notably when using the recursive ``cp`` command, can preserve
189 the UID and/or GID of the original file, which is usually not what 187 the UID and/or GID of the original file, which is usually not what
190 you want. The 188 you want. The ``host-user-contaminated`` QA check checks for files
191 ```host-user-contaminated`` <#insane-host-user-contaminated>`__ QA 189 that probably have the wrong ownership.
192 check checks for files that probably have the wrong ownership.
193 190
194 Safe methods for installing files include the following: 191 Safe methods for installing files include the following:
195 192
@@ -223,9 +220,8 @@ variables.
223The ``do_package`` task, in conjunction with the 220The ``do_package`` task, in conjunction with the
224:ref:`ref-tasks-packagedata` task, also saves some 221:ref:`ref-tasks-packagedata` task, also saves some
225important package metadata. For additional information, see the 222important package metadata. For additional information, see the
226:term:`PKGDESTWORK` variable and the "`Automatically 223:term:`PKGDESTWORK` variable and the
227Added Runtime 224":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
228Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
229section in the Yocto Project Overview and Concepts Manual. 225section in the Yocto Project Overview and Concepts Manual.
230 226
231.. _ref-tasks-package_qa: 227.. _ref-tasks-package_qa:
@@ -243,8 +239,8 @@ see the :ref:`insane <ref-classes-insane>` class.
243 239
244Creates Debian packages (i.e. ``*.deb`` files) and places them in the 240Creates Debian packages (i.e. ``*.deb`` files) and places them in the
245``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in 241``${``\ :term:`DEPLOY_DIR_DEB`\ ``}`` directory in
246the package feeds area. For more information, see the "`Package 242the package feeds area. For more information, see the
247Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in 243":ref:`package-feeds-dev-environment`" section in
248the Yocto Project Overview and Concepts Manual. 244the Yocto Project Overview and Concepts Manual.
249 245
250.. _ref-tasks-package_write_ipk: 246.. _ref-tasks-package_write_ipk:
@@ -254,8 +250,8 @@ the Yocto Project Overview and Concepts Manual.
254 250
255Creates IPK packages (i.e. ``*.ipk`` files) and places them in the 251Creates IPK packages (i.e. ``*.ipk`` files) and places them in the
256``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in 252``${``\ :term:`DEPLOY_DIR_IPK`\ ``}`` directory in
257the package feeds area. For more information, see the "`Package 253the package feeds area. For more information, see the
258Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in 254":ref:`package-feeds-dev-environment`" section in
259the Yocto Project Overview and Concepts Manual. 255the Yocto Project Overview and Concepts Manual.
260 256
261.. _ref-tasks-package_write_rpm: 257.. _ref-tasks-package_write_rpm:
@@ -265,8 +261,8 @@ the Yocto Project Overview and Concepts Manual.
265 261
266Creates RPM packages (i.e. ``*.rpm`` files) and places them in the 262Creates RPM packages (i.e. ``*.rpm`` files) and places them in the
267``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in 263``${``\ :term:`DEPLOY_DIR_RPM`\ ``}`` directory in
268the package feeds area. For more information, see the "`Package 264the package feeds area. For more information, see the
269Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in 265":ref:`package-feeds-dev-environment`" section in
270the Yocto Project Overview and Concepts Manual. 266the Yocto Project Overview and Concepts Manual.
271 267
272.. _ref-tasks-package_write_tar: 268.. _ref-tasks-package_write_tar:
@@ -276,8 +272,8 @@ the Yocto Project Overview and Concepts Manual.
276 272
277Creates tarballs and places them in the 273Creates tarballs and places them in the
278``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in 274``${``\ :term:`DEPLOY_DIR_TAR`\ ``}`` directory in
279the package feeds area. For more information, see the "`Package 275the package feeds area. For more information, see the
280Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section in 276":ref:`package-feeds-dev-environment`" section in
281the Yocto Project Overview and Concepts Manual. 277the Yocto Project Overview and Concepts Manual.
282 278
283.. _ref-tasks-packagedata: 279.. _ref-tasks-packagedata:
@@ -312,8 +308,14 @@ and kept in a subdirectory of the directory holding the recipe file. For
312example, consider the 308example, consider the
313:yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>` 309:yocto_git:`bluez5 </cgit/cgit.cgi/poky/tree/meta/recipes-connectivity/bluez5>`
314recipe from the OE-Core layer (i.e. ``poky/meta``): 310recipe from the OE-Core layer (i.e. ``poky/meta``):
315poky/meta/recipes-connectivity/bluez5 This recipe has two patch files 311::
316located here: poky/meta/recipes-connectivity/bluez5/bluez5 312
313 poky/meta/recipes-connectivity/bluez5
314
315This recipe has two patch files located here:
316::
317
318 poky/meta/recipes-connectivity/bluez5/bluez5
317 319
318In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source 320In the ``bluez5`` recipe, the ``SRC_URI`` statements point to the source
319and patch files needed to build the package. 321and patch files needed to build the package.
@@ -331,23 +333,35 @@ and patch files needed to build the package.
331As mentioned earlier, the build system treats files whose file types are 333As mentioned earlier, the build system treats files whose file types are
332``.patch`` and ``.diff`` as patch files. However, you can use the 334``.patch`` and ``.diff`` as patch files. However, you can use the
333"apply=yes" parameter with the ``SRC_URI`` statement to indicate any 335"apply=yes" parameter with the ``SRC_URI`` statement to indicate any
334file as a patch file: SRC_URI = " \\ git://path_to_repo/some_package \\ 336file as a patch file:
335file://file;apply=yes \\ " 337::
338
339 SRC_URI = " \\
340 git://path_to_repo/some_package \\
341 file://file;apply=yes \\
342 "
336 343
337Conversely, if you have a directory full of patch files and you want to 344Conversely, if you have a directory full of patch files and you want to
338exclude some so that the ``do_patch`` task does not apply them during 345exclude some so that the ``do_patch`` task does not apply them during
339the patch phase, you can use the "apply=no" parameter with the 346the patch phase, you can use the "apply=no" parameter with the
340``SRC_URI`` statement: SRC_URI = " \\ git://path_to_repo/some_package \\ 347``SRC_URI`` statement:
341file://path_to_lots_of_patch_files \\ 348::
342file://path_to_lots_of_patch_files/patch_file5;apply=no \\ " In the 349
350 SRC_URI = " \
351 git://path_to_repo/some_package \
352 file://path_to_lots_of_patch_files \
353 file://path_to_lots_of_patch_files/patch_file5;apply=no \
354 "
355
356In the
343previous example, assuming all the files in the directory holding the 357previous example, assuming all the files in the directory holding the
344patch files end with either ``.patch`` or ``.diff``, every file would be 358patch files end with either ``.patch`` or ``.diff``, every file would be
345applied as a patch by default except for the patch_file5 patch. 359applied as a patch by default except for the patch_file5 patch.
346 360
347You can find out more about the patching process in the 361You can find out more about the patching process in the
348"`Patching <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__" section in 362":ref:`patching-dev-environment`" section in
349the Yocto Project Overview and Concepts Manual and the "`Patching 363the Yocto Project Overview and Concepts Manual and the
350Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in the 364":ref:`new-recipe-patching-code`" section in the
351Yocto Project Development Tasks Manual. 365Yocto Project Development Tasks Manual.
352 366
353.. _ref-tasks-populate_lic: 367.. _ref-tasks-populate_lic:
@@ -364,8 +378,7 @@ the image is constructed.
364------------------- 378-------------------
365 379
366Creates the file and directory structure for an installable SDK. See the 380Creates the file and directory structure for an installable SDK. See the
367"`SDK 381":ref:`sdk-generation-dev-environment`"
368Generation <&YOCTO_DOCS_OM_URL;#sdk-generation-dev-environment>`__"
369section in the Yocto Project Overview and Concepts Manual for more 382section in the Yocto Project Overview and Concepts Manual for more
370information. 383information.
371 384
@@ -420,8 +433,7 @@ Unpacks the source code into a working directory pointed to by
420``${``\ :term:`WORKDIR`\ ``}``. The :term:`S` 433``${``\ :term:`WORKDIR`\ ``}``. The :term:`S`
421variable also plays a role in where unpacked source files ultimately 434variable also plays a role in where unpacked source files ultimately
422reside. For more information on how source files are unpacked, see the 435reside. For more information on how source files are unpacked, see the
423"`Source 436":ref:`source-fetching-dev-environment`"
424Fetching <&YOCTO_DOCS_OM_URL;#source-fetching-dev-environment>`__"
425section in the Yocto Project Overview and Concepts Manual and also see 437section in the Yocto Project Overview and Concepts Manual and also see
426the ``WORKDIR`` and ``S`` variable descriptions. 438the ``WORKDIR`` and ``S`` variable descriptions.
427 439
@@ -442,16 +454,24 @@ of the recipe exists upstream and a status of not updated, updated, or
442unknown. 454unknown.
443 455
444To check the upstream version and status of a recipe, use the following 456To check the upstream version and status of a recipe, use the following
445devtool commands: $ devtool latest-version $ devtool 457devtool commands:
446check-upgrade-status See the "```devtool`` Quick 458::
447Reference <#ref-devtool-reference>`__" chapter for more information on 459
448``devtool``. See the "`Checking on the Upgrade Status of a 460 $ devtool latest-version
449Recipe <&YOCTO_DOCS_REF_URL;#devtool-checking-on-the-upgrade-status-of-a-recipe>`__" 461 $ devtool check-upgrade-status
462
463See the ":ref:`ref-manual/ref-devtool-reference:\`\`devtool\`\` quick reference`"
464chapter for more information on
465``devtool``. See the ":ref:`devtool-checking-on-the-upgrade-status-of-a-recipe`"
450section for information on checking the upgrade status of a recipe. 466section for information on checking the upgrade status of a recipe.
451 467
452To build the ``checkpkg`` task, use the ``bitbake`` command with the 468To build the ``checkpkg`` task, use the ``bitbake`` command with the
453"-c" option and task name: $ bitbake core-image-minimal -c checkpkg By 469"-c" option and task name:
454default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g. 470::
471
472 $ bitbake core-image-minimal -c checkpkg
473
474By default, the results are stored in :term:`$LOG_DIR <LOG_DIR>` (e.g.
455``$BUILD_DIR/tmp/log``). 475``$BUILD_DIR/tmp/log``).
456 476
457.. _ref-tasks-checkuri: 477.. _ref-tasks-checkuri:
@@ -473,11 +493,13 @@ Removes all output files for a target from the
473:ref:`ref-tasks-install`, and 493:ref:`ref-tasks-install`, and
474:ref:`ref-tasks-package`). 494:ref:`ref-tasks-package`).
475 495
476You can run this task using BitBake as follows: $ bitbake -c clean 496You can run this task using BitBake as follows:
477recipe 497::
498
499 $ bitbake -c clean recipe
478 500
479Running this task does not remove the 501Running this task does not remove the
480`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ cache files. 502:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>` cache files.
481Consequently, if no changes have been made and the recipe is rebuilt 503Consequently, if no changes have been made and the recipe is rebuilt
482after cleaning, output files are simply restored from the sstate cache. 504after cleaning, output files are simply restored from the sstate cache.
483If you want to remove the sstate cache files for the recipe, you need to 505If you want to remove the sstate cache files for the recipe, you need to
@@ -490,14 +512,16 @@ use the :ref:`ref-tasks-cleansstate` task instead
490--------------- 512---------------
491 513
492Removes all output files, shared state 514Removes all output files, shared state
493(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache, and 515(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache, and
494downloaded source files for a target (i.e. the contents of 516downloaded source files for a target (i.e. the contents of
495:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is 517:term:`DL_DIR`). Essentially, the ``do_cleanall`` task is
496identical to the :ref:`ref-tasks-cleansstate` task 518identical to the :ref:`ref-tasks-cleansstate` task
497with the added removal of downloaded source files. 519with the added removal of downloaded source files.
498 520
499You can run this task using BitBake as follows: $ bitbake -c cleanall 521You can run this task using BitBake as follows:
500recipe 522::
523
524 $ bitbake -c cleanall recipe
501 525
502Typically, you would not normally use the ``cleanall`` task. Do so only 526Typically, you would not normally use the ``cleanall`` task. Do so only
503if you want to start fresh with the :ref:`ref-tasks-fetch` 527if you want to start fresh with the :ref:`ref-tasks-fetch`
@@ -509,14 +533,16 @@ task.
509------------------ 533------------------
510 534
511Removes all output files and shared state 535Removes all output files and shared state
512(`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) cache for a 536(:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`) cache for a
513target. Essentially, the ``do_cleansstate`` task is identical to the 537target. Essentially, the ``do_cleansstate`` task is identical to the
514:ref:`ref-tasks-clean` task with the added removal of 538:ref:`ref-tasks-clean` task with the added removal of
515shared state (`sstate <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__) 539shared state (`:ref:`sstate <overview-manual/overview-manual-concepts:shared state cache>`)
516cache. 540cache.
517 541
518You can run this task using BitBake as follows: $ bitbake -c cleansstate 542You can run this task using BitBake as follows:
519recipe 543::
544
545 $ bitbake -c cleansstate recipe
520 546
521When you run the ``do_cleansstate`` task, the OpenEmbedded build system 547When you run the ``do_cleansstate`` task, the OpenEmbedded build system
522no longer uses any sstate. Consequently, building the recipe from 548no longer uses any sstate. Consequently, building the recipe from
@@ -531,8 +557,8 @@ scratch is guaranteed.
531 as follows: 557 as follows:
532 :: 558 ::
533 559
534 $ bitbake -f -c do_cleansstate target 560 $ bitbake -f -c do_cleansstate target
535 561
536 562
537.. _ref-tasks-devpyshell: 563.. _ref-tasks-devpyshell:
538 564
@@ -542,9 +568,7 @@ scratch is guaranteed.
542Starts a shell in which an interactive Python interpreter allows you to 568Starts a shell in which an interactive Python interpreter allows you to
543interact with the BitBake build environment. From within this shell, you 569interact with the BitBake build environment. From within this shell, you
544can directly examine and set bits from the data store and execute 570can directly examine and set bits from the data store and execute
545functions as if within the BitBake environment. See the "`Using a 571functions as if within the BitBake environment. See the ":ref:`platdev-appdev-devpyshell`" section in
546Development Python
547Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devpyshell>`__" section in
548the Yocto Project Development Tasks Manual for more information about 572the Yocto Project Development Tasks Manual for more information about
549using ``devpyshell``. 573using ``devpyshell``.
550 574
@@ -554,8 +578,7 @@ using ``devpyshell``.
554--------------- 578---------------
555 579
556Starts a shell whose environment is set up for development, debugging, 580Starts a shell whose environment is set up for development, debugging,
557or both. See the "`Using a Development 581or both. See the ":ref:`platdev-appdev-devshell`" section in the
558Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" section in the
559Yocto Project Development Tasks Manual for more information about using 582Yocto Project Development Tasks Manual for more information about using
560``devshell``. 583``devshell``.
561 584
@@ -571,8 +594,7 @@ Lists all defined tasks for a target.
571``do_package_index`` 594``do_package_index``
572-------------------- 595--------------------
573 596
574Creates or updates the index in the `Package 597Creates or updates the index in the `:ref:`package-feeds-dev-environment` area.
575Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__ area.
576 598
577.. note:: 599.. note::
578 600
@@ -615,8 +637,7 @@ has some more information about these types of images.
615------------- 637-------------
616 638
617Creates the root filesystem (file and directory structure) for an image. 639Creates the root filesystem (file and directory structure) for an image.
618See the "`Image 640See the ":ref:`image-generation-dev-environment`"
619Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
620section in the Yocto Project Overview and Concepts Manual for more 641section in the Yocto Project Overview and Concepts Manual for more
621information on how the root filesystem is created. 642information on how the root filesystem is created.
622 643
@@ -626,9 +647,8 @@ information on how the root filesystem is created.
626---------------- 647----------------
627 648
628Boots an image and performs runtime tests within the image. For 649Boots an image and performs runtime tests within the image. For
629information on automatically testing images, see the "`Performing 650information on automatically testing images, see the
630Automated Runtime 651":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
631Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
632section in the Yocto Project Development Tasks Manual. 652section in the Yocto Project Development Tasks Manual.
633 653
634.. _ref-tasks-testimage_auto: 654.. _ref-tasks-testimage_auto:
@@ -640,9 +660,8 @@ Boots an image and performs runtime tests within the image immediately
640after it has been built. This task is enabled when you set 660after it has been built. This task is enabled when you set
641:term:`TESTIMAGE_AUTO` equal to "1". 661:term:`TESTIMAGE_AUTO` equal to "1".
642 662
643For information on automatically testing images, see the "`Performing 663For information on automatically testing images, see the
644Automated Runtime 664":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
645Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
646section in the Yocto Project Development Tasks Manual. 665section in the Yocto Project Development Tasks Manual.
647 666
648Kernel-Related Tasks 667Kernel-Related Tasks
@@ -674,9 +693,13 @@ changes made by the user with other methods (i.e. using
674(:ref:`ref-tasks-kernel_menuconfig`). Once the 693(:ref:`ref-tasks-kernel_menuconfig`). Once the
675file of differences is created, it can be used to create a config 694file of differences is created, it can be used to create a config
676fragment that only contains the differences. You can invoke this task 695fragment that only contains the differences. You can invoke this task
677from the command line as follows: $ bitbake linux-yocto -c diffconfig 696from the command line as follows:
678For more information, see the "`Creating Configuration 697::
679Fragments <&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments>`__" 698
699 $ bitbake linux-yocto -c diffconfig
700
701For more information, see the
702":ref:`kernel-dev/kernel-dev-common:creating configuration fragments`"
680section in the Yocto Project Linux Kernel Development Manual. 703section in the Yocto Project Linux Kernel Development Manual.
681 704
682.. _ref-tasks-kernel_checkout: 705.. _ref-tasks-kernel_checkout:
@@ -701,9 +724,13 @@ Validates the configuration produced by the
701configuration does not appear in the final ``.config`` file or when you 724configuration does not appear in the final ``.config`` file or when you
702override a policy configuration in a hardware configuration fragment. 725override a policy configuration in a hardware configuration fragment.
703You can run this task explicitly and view the output by using the 726You can run this task explicitly and view the output by using the
704following command: $ bitbake linux-yocto -c kernel_configcheck -f For 727following command:
705more information, see the "`Validating 728::
706Configuration <&YOCTO_DOCS_KERNEL_DEV_URL;#validating-configuration>`__" 729
730 $ bitbake linux-yocto -c kernel_configcheck -f
731
732For more information, see the
733":ref:`kernel-dev/kernel-dev-common:validating configuration`"
707section in the Yocto Project Linux Kernel Development Manual. 734section in the Yocto Project Linux Kernel Development Manual.
708 735
709.. _ref-tasks-kernel_configme: 736.. _ref-tasks-kernel_configme:
@@ -733,10 +760,9 @@ tool, which you then use to modify the kernel configuration.
733 :: 760 ::
734 761
735 $ bitbake linux-yocto -c menuconfig 762 $ bitbake linux-yocto -c menuconfig
736
737 763
738See the "`Using 764
739``menuconfig`` <&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig>`__" 765See the ":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
740section in the Yocto Project Linux Kernel Development Manual for more 766section in the Yocto Project Linux Kernel Development Manual for more
741information on this configuration tool. 767information on this configuration tool.
742 768
@@ -760,7 +786,7 @@ which can then be applied by subsequent tasks such as
760 786
761Runs ``make menuconfig`` for the kernel. For information on 787Runs ``make menuconfig`` for the kernel. For information on
762``menuconfig``, see the 788``menuconfig``, see the
763"`Using  ``menuconfig`` <&YOCTO_DOCS_KERNEL_DEV_URL;#using-menuconfig>`__" 789":ref:`kernel-dev/kernel-dev-common:using \`\`menuconfig\`\``"
764section in the Yocto Project Linux Kernel Development Manual. 790section in the Yocto Project Linux Kernel Development Manual.
765 791
766.. _ref-tasks-savedefconfig: 792.. _ref-tasks-savedefconfig:
@@ -773,8 +799,10 @@ instead of the default defconfig. The saved defconfig contains the
773differences between the default defconfig and the changes made by the 799differences between the default defconfig and the changes made by the
774user using other methods (i.e. the 800user using other methods (i.e. the
775:ref:`ref-tasks-kernel_menuconfig` task. You 801:ref:`ref-tasks-kernel_menuconfig` task. You
776can invoke the task using the following command: $ bitbake linux-yocto 802can invoke the task using the following command:
777-c savedefconfig 803::
804
805 $ bitbake linux-yocto -c savedefconfig
778 806
779.. _ref-tasks-shared_workdir: 807.. _ref-tasks-shared_workdir:
780 808
diff --git a/documentation/ref-manual/ref-terms.rst b/documentation/ref-manual/ref-terms.rst
index 24eff62bcd..312fc12ef0 100644
--- a/documentation/ref-manual/ref-terms.rst
+++ b/documentation/ref-manual/ref-terms.rst
@@ -26,7 +26,12 @@ universal, the list includes them just in case:
26 26
27 When you name an append file, you can use the "``%``" wildcard character 27 When you name an append file, you can use the "``%``" wildcard character
28 to allow for matching recipe names. For example, suppose you have an 28 to allow for matching recipe names. For example, suppose you have an
29 append file named as follows: busybox_1.21.%.bbappend That append file 29 append file named as follows:
30 ::
31
32 busybox_1.21.%.bbappend
33
34 That append file
30 would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So, 35 would match any ``busybox_1.21.``\ x\ ``.bb`` version of the recipe. So,
31 the append file would match any of the following recipe names: 36 the append file would match any of the following recipe names:
32 37
@@ -68,11 +73,11 @@ universal, the list includes them just in case:
68 examples assume your :term:`Source Directory` is named ``poky``: 73 examples assume your :term:`Source Directory` is named ``poky``:
69 74
70 - Create the Build Directory inside your Source Directory and let 75 - Create the Build Directory inside your Source Directory and let
71 the name of the Build Directory default to ``build``: 76 the name of the Build Directory default to ``build``:
72 77
73 .. code-block:: shell 78 .. code-block:: shell
74 79
75 $ cd $HOME/poky 80 $ cd $HOME/poky
76 $ source oe-init-build-env 81 $ source oe-init-build-env
77 82
78 - Create the Build Directory inside your home directory and 83 - Create the Build Directory inside your home directory and
@@ -80,18 +85,18 @@ universal, the list includes them just in case:
80 85
81 .. code-block:: shell 86 .. code-block:: shell
82 87
83 $ cd $HOME 88 $ cd $HOME
84 $ source poky/oe-init-build-env test-builds 89 $ source poky/oe-init-build-env test-builds
85 90
86 - Provide a directory path and specifically name the Build 91 - Provide a directory path and specifically name the Build
87 Directory. Any intermediate folders in the pathname must exist. 92 Directory. Any intermediate folders in the pathname must exist.
88 This next example creates a Build Directory named 93 This next example creates a Build Directory named
89 ``YP-POKYVERSION`` in your home directory within the existing 94 ``YP-POKYVERSION`` in your home directory within the existing
90 directory ``mybuilds``: 95 directory ``mybuilds``:
91 96
92 .. code-block:: shell 97 .. code-block:: shell
93 98
94 $ cd $HOME 99 $ cd $HOME
95 $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION 100 $ source $HOME/poky/oe-init-build-env $HOME/mybuilds/YP-POKYVERSION
96 101
97 .. note:: 102 .. note::
@@ -349,8 +354,9 @@ universal, the list includes them just in case:
349 While it is not recommended that you use tarball expansion to set up 354 While it is not recommended that you use tarball expansion to set up
350 the Source Directory, if you do, the top-level directory name of the 355 the Source Directory, if you do, the top-level directory name of the
351 Source Directory is derived from the Yocto Project release tarball. 356 Source Directory is derived from the Yocto Project release tarball.
352 For example, downloading and unpacking ```` results in a Source 357 For example, downloading and unpacking
353 Directory whose root folder is named ````. 358 :yocto_dl:`releases/yocto/&DISTRO_REL_TAG;/&YOCTO_POKY;.tar.bz2`
359 results in a Source Directory whose root folder is named ``poky``.
354 360
355 It is important to understand the differences between the Source 361 It is important to understand the differences between the Source
356 Directory created by unpacking a released tarball as compared to 362 Directory created by unpacking a released tarball as compared to
@@ -366,8 +372,8 @@ universal, the list includes them just in case:
366 repository. 372 repository.
367 373
368 For more information on concepts related to Git repositories, 374 For more information on concepts related to Git repositories,
369 branches, and tags, see the "`Repositories, Tags, and 375 branches, and tags, see the
370 Branches <&YOCTO_DOCS_OM_URL;#repositories-tags-and-branches>`__" 376 ":ref:`overview-manual/overview-manual-development-environment:repositories, tags, and branches`"
371 section in the Yocto Project Overview and Concepts Manual. 377 section in the Yocto Project Overview and Concepts Manual.
372 378
373 Task 379 Task
@@ -381,7 +387,7 @@ universal, the list includes them just in case:
381 The interface enables you to 387 The interface enables you to
382 configure and run your builds. Information about builds is collected 388 configure and run your builds. Information about builds is collected
383 and stored in a database. For information on Toaster, see the 389 and stored in a database. For information on Toaster, see the
384 `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__. 390 :doc:`../toaster-manual/toaster-manual`.
385 391
386 Upstream 392 Upstream
387 A reference to source code or repositories that are not 393 A reference to source code or repositories that are not
diff --git a/documentation/ref-manual/ref-variables.rst b/documentation/ref-manual/ref-variables.rst
index 54a892576b..625a37c158 100644
--- a/documentation/ref-manual/ref-variables.rst
+++ b/documentation/ref-manual/ref-variables.rst
@@ -21,74 +21,86 @@ system and gives an overview of their function and contents.
21 ABIEXTENSION 21 ABIEXTENSION
22 Extension to the Application Binary Interface (ABI) field of the GNU 22 Extension to the Application Binary Interface (ABI) field of the GNU
23 canonical architecture name (e.g. "eabi"). 23 canonical architecture name (e.g. "eabi").
24 24
25 ABI extensions are set in the machine include files. For example, the 25 ABI extensions are set in the machine include files. For example, the
26 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the 26 ``meta/conf/machine/include/arm/arch-arm.inc`` file sets the
27 following extension: ABIEXTENSION = "eabi" 27 following extension:
28 28 ::
29
30 ABIEXTENSION = "eabi"
31
29 ALLOW_EMPTY 32 ALLOW_EMPTY
30 Specifies whether to produce an output package even if it is empty. 33 Specifies whether to produce an output package even if it is empty.
31 By default, BitBake does not produce empty packages. This default 34 By default, BitBake does not produce empty packages. This default
32 behavior can cause issues when there is an 35 behavior can cause issues when there is an
33 :term:`RDEPENDS` or some other hard runtime 36 :term:`RDEPENDS` or some other hard runtime
34 requirement on the existence of the package. 37 requirement on the existence of the package.
35 38
36 Like all package-controlling variables, you must always use them in 39 Like all package-controlling variables, you must always use them in
37 conjunction with a package name override, as in: ALLOW_EMPTY_${PN} = 40 conjunction with a package name override, as in:
38 "1" ALLOW_EMPTY_${PN}-dev = "1" ALLOW_EMPTY_${PN}-staticdev = "1" 41 ::
39 42
43 ALLOW_EMPTY_${PN} = "1"
44 ALLOW_EMPTY_${PN}-dev = "1"
45 ALLOW_EMPTY_${PN}-staticdev = "1"
46
40 ALTERNATIVE 47 ALTERNATIVE
41 Lists commands in a package that need an alternative binary naming 48 Lists commands in a package that need an alternative binary naming
42 scheme. Sometimes the same command is provided in multiple packages. 49 scheme. Sometimes the same command is provided in multiple packages.
43 When this occurs, the OpenEmbedded build system needs to use the 50 When this occurs, the OpenEmbedded build system needs to use the
44 alternatives system to create a different binary naming scheme so the 51 alternatives system to create a different binary naming scheme so the
45 commands can co-exist. 52 commands can co-exist.
46 53
47 To use the variable, list out the package's commands that also exist 54 To use the variable, list out the package's commands that also exist
48 as part of another package. For example, if the ``busybox`` package 55 as part of another package. For example, if the ``busybox`` package
49 has four commands that also exist as part of another package, you 56 has four commands that also exist as part of another package, you
50 identify them as follows: ALTERNATIVE_busybox = "sh sed test bracket" 57 identify them as follows:
58 ::
59
60 ALTERNATIVE_busybox = "sh sed test bracket"
61
51 For more information on the alternatives system, see the 62 For more information on the alternatives system, see the
52 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 63 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
53 section. 64 section.
54 65
55 ALTERNATIVE_LINK_NAME 66 ALTERNATIVE_LINK_NAME
56 Used by the alternatives system to map duplicated commands to actual 67 Used by the alternatives system to map duplicated commands to actual
57 locations. For example, if the ``bracket`` command provided by the 68 locations. For example, if the ``bracket`` command provided by the
58 ``busybox`` package is duplicated through another package, you must 69 ``busybox`` package is duplicated through another package, you must
59 use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual 70 use the ``ALTERNATIVE_LINK_NAME`` variable to specify the actual
60 location: ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/[" 71 location:
61 72 ::
73
74 ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
75
62 In this example, the binary for the ``bracket`` command (i.e. ``[``) 76 In this example, the binary for the ``bracket`` command (i.e. ``[``)
63 from the ``busybox`` package resides in ``/usr/bin/``. 77 from the ``busybox`` package resides in ``/usr/bin/``.
64 78
65 .. note:: 79 .. note::
66 80
67 If 81 If ALTERNATIVE_LINK_NAME is not defined, it defaults to ${bindir}/ name.
68 ALTERNATIVE_LINK_NAME 82
69 is not defined, it defaults to
70 ${bindir}/
71 name
72 .
73
74 For more information on the alternatives system, see the 83 For more information on the alternatives system, see the
75 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 84 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
76 section. 85 section.
77 86
78 ALTERNATIVE_PRIORITY 87 ALTERNATIVE_PRIORITY
79 Used by the alternatives system to create default priorities for 88 Used by the alternatives system to create default priorities for
80 duplicated commands. You can use the variable to create a single 89 duplicated commands. You can use the variable to create a single
81 default regardless of the command name or package, a default for 90 default regardless of the command name or package, a default for
82 specific duplicated commands regardless of the package, or a default 91 specific duplicated commands regardless of the package, or a default
83 for specific commands tied to particular packages. Here are the 92 for specific commands tied to particular packages. Here are the
84 available syntax forms: ALTERNATIVE_PRIORITY = "priority" 93 available syntax forms:
85 ALTERNATIVE_PRIORITY[name] = "priority" 94 ::
86 ALTERNATIVE_PRIORITY_pkg[name] = "priority" 95
87 96 ALTERNATIVE_PRIORITY = "priority"
97 ALTERNATIVE_PRIORITY[name] = "priority"
98 ALTERNATIVE_PRIORITY_pkg[name] = "priority"
99
88 For more information on the alternatives system, see the 100 For more information on the alternatives system, see the
89 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 101 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
90 section. 102 section.
91 103
92 ALTERNATIVE_TARGET 104 ALTERNATIVE_TARGET
93 Used by the alternatives system to create default link locations for 105 Used by the alternatives system to create default link locations for
94 duplicated commands. You can use the variable to create a single 106 duplicated commands. You can use the variable to create a single
@@ -96,105 +108,115 @@ system and gives an overview of their function and contents.
96 command name or package, a default for specific duplicated commands 108 command name or package, a default for specific duplicated commands
97 regardless of the package, or a default for specific commands tied to 109 regardless of the package, or a default for specific commands tied to
98 particular packages. Here are the available syntax forms: 110 particular packages. Here are the available syntax forms:
99 ALTERNATIVE_TARGET = "target" ALTERNATIVE_TARGET[name] = "target" 111 ::
100 ALTERNATIVE_TARGET_pkg[name] = "target" 112
101 113 ALTERNATIVE_TARGET = "target"
114 ALTERNATIVE_TARGET[name] = "target"
115 ALTERNATIVE_TARGET_pkg[name] = "target"
116
102 .. note:: 117 .. note::
103 118
104 If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value 119 If ``ALTERNATIVE_TARGET`` is not defined, it inherits the value
105 from the 120 from the :term:`ALTERNATIVE_LINK_NAME` variable.
106 :term:`ALTERNATIVE_LINK_NAME` 121
107 variable.
108
109 If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the 122 If ``ALTERNATIVE_LINK_NAME`` and ``ALTERNATIVE_TARGET`` are the
110 same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``" 123 same, the target for ``ALTERNATIVE_TARGET`` has "``.{BPN}``"
111 appended to it. 124 appended to it.
112 125
113 Finally, if the file referenced has not been renamed, the 126 Finally, if the file referenced has not been renamed, the
114 alternatives system will rename it to avoid the need to rename 127 alternatives system will rename it to avoid the need to rename
115 alternative files in the :ref:`ref-tasks-install` 128 alternative files in the :ref:`ref-tasks-install`
116 task while retaining support for the command if necessary. 129 task while retaining support for the command if necessary.
117 130
118 For more information on the alternatives system, see the 131 For more information on the alternatives system, see the
119 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`" 132 ":ref:`update-alternatives.bbclass <ref-classes-update-alternatives>`"
120 section. 133 section.
121 134
122 APPEND 135 APPEND
123 An override list of append strings for each target specified with 136 An override list of append strings for each target specified with
124 :term:`LABELS`. 137 :term:`LABELS`.
125 138
126 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 139 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
127 information on how this variable is used. 140 information on how this variable is used.
128 141
129 AR 142 AR
130 The minimal command and arguments used to run ``ar``. 143 The minimal command and arguments used to run ``ar``.
131 144
132 ARCHIVER_MODE 145 ARCHIVER_MODE
133 When used with the :ref:`archiver <ref-classes-archiver>` class, 146 When used with the :ref:`archiver <ref-classes-archiver>` class,
134 determines the type of information used to create a released archive. 147 determines the type of information used to create a released archive.
135 You can use this variable to create archives of patched source, 148 You can use this variable to create archives of patched source,
136 original source, configured source, and so forth by employing the 149 original source, configured source, and so forth by employing the
137 following variable flags (varflags): ARCHIVER_MODE[src] = "original" 150 following variable flags (varflags):
138 # Uses original (unpacked) source # files. ARCHIVER_MODE[src] = 151 ::
139 "patched" # Uses patched source files. This is # the default. 152
140 ARCHIVER_MODE[src] = "configured" # Uses configured source files. 153 ARCHIVER_MODE[src] = "original" # Uses original (unpacked) source files.
141 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and # 154 ARCHIVER_MODE[src] = "patched" # Uses patched source files. This is the default.
142 do_patch. ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists 155 ARCHIVER_MODE[src] = "configured" # Uses configured source files.
143 files and directories to # exclude from diff. ARCHIVER_MODE[dumpdata] 156 ARCHIVER_MODE[diff] = "1" # Uses patches between do_unpack and do_patch.
144 = "1" # Uses environment data. ARCHIVER_MODE[recipe] = "1" # Uses 157 ARCHIVER_MODE[diff-exclude] ?= "file file ..." # Lists files and directories to exclude from diff.
145 recipe and include files. ARCHIVER_MODE[srpm] = "1" # Uses RPM 158 ARCHIVER_MODE[dumpdata] = "1" # Uses environment data.
146 package files. For information on how the variable works, see the 159 ARCHIVER_MODE[recipe] = "1" # Uses recipe and include files.
160 ARCHIVER_MODE[srpm] = "1" # Uses RPM package files.
161
162 For information on how the variable works, see the
147 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`. 163 ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
148 164
149 AS 165 AS
150 Minimal command and arguments needed to run the assembler. 166 Minimal command and arguments needed to run the assembler.
151 167
152 ASSUME_PROVIDED 168 ASSUME_PROVIDED
153 Lists recipe names (:term:`PN` values) BitBake does not 169 Lists recipe names (:term:`PN` values) BitBake does not
154 attempt to build. Instead, BitBake assumes these recipes have already 170 attempt to build. Instead, BitBake assumes these recipes have already
155 been built. 171 been built.
156 172
157 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native 173 In OpenEmbedded-Core, ``ASSUME_PROVIDED`` mostly specifies native
158 tools that should not be built. An example is ``git-native``, which 174 tools that should not be built. An example is ``git-native``, which
159 when specified, allows for the Git binary from the host to be used 175 when specified, allows for the Git binary from the host to be used
160 rather than building ``git-native``. 176 rather than building ``git-native``.
161 177
162 ASSUME_SHLIBS 178 ASSUME_SHLIBS
163 Provides additional ``shlibs`` provider mapping information, which 179 Provides additional ``shlibs`` provider mapping information, which
164 adds to or overwrites the information provided automatically by the 180 adds to or overwrites the information provided automatically by the
165 system. Separate multiple entries using spaces. 181 system. Separate multiple entries using spaces.
166 182
167 As an example, use the following form to add an ``shlib`` provider of 183 As an example, use the following form to add an ``shlib`` provider of
168 shlibname in packagename with the optional version: 184 shlibname in packagename with the optional version:
169 shlibname:packagename[_version] 185 ::
170 186
187 shlibname:packagename[_version]
188
171 Here is an example that adds a shared library named ``libEGL.so.1`` 189 Here is an example that adds a shared library named ``libEGL.so.1``
172 as being provided by the ``libegl-implementation`` package: 190 as being provided by the ``libegl-implementation`` package:
173 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation" 191 ::
174 192
193 ASSUME_SHLIBS = "libEGL.so.1:libegl-implementation"
194
175 AUTHOR 195 AUTHOR
176 The email address used to contact the original author or authors in 196 The email address used to contact the original author or authors in
177 order to send patches and forward bugs. 197 order to send patches and forward bugs.
178 198
179 AUTO_LIBNAME_PKGS 199 AUTO_LIBNAME_PKGS
180 When the :ref:`debian <ref-classes-debian>` class is inherited, 200 When the :ref:`debian <ref-classes-debian>` class is inherited,
181 which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which 201 which is the default behavior, ``AUTO_LIBNAME_PKGS`` specifies which
182 packages should be checked for libraries and renamed according to 202 packages should be checked for libraries and renamed according to
183 Debian library package naming. 203 Debian library package naming.
184 204
185 The default value is "${PACKAGES}", which causes the debian class to 205 The default value is "${PACKAGES}", which causes the debian class to
186 act on all packages that are explicitly generated by the recipe. 206 act on all packages that are explicitly generated by the recipe.
187 207
188 AUTO_SYSLINUXMENU 208 AUTO_SYSLINUXMENU
189 Enables creating an automatic menu for the syslinux bootloader. You 209 Enables creating an automatic menu for the syslinux bootloader. You
190 must set this variable in your recipe. The 210 must set this variable in your recipe. The
191 :ref:`syslinux <ref-classes-syslinux>` class checks this variable. 211 :ref:`syslinux <ref-classes-syslinux>` class checks this variable.
192 212
193 AUTOREV 213 AUTOREV
194 When ``SRCREV`` is set to the value of this variable, it specifies to 214 When ``SRCREV`` is set to the value of this variable, it specifies to
195 use the latest source revision in the repository. Here is an example: 215 use the latest source revision in the repository. Here is an example:
196 SRCREV = "${AUTOREV}" 216 ::
197 217
218 SRCREV = "${AUTOREV}"
219
198 If you use the previous statement to retrieve the latest version of 220 If you use the previous statement to retrieve the latest version of
199 software, you need to be sure :term:`PV` contains 221 software, you need to be sure :term:`PV` contains
200 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you 222 ``${``\ :term:`SRCPV`\ ``}``. For example, suppose you
@@ -203,19 +225,18 @@ system and gives an overview of their function and contents.
203 statement. In this example, ``${SRCPV}`` does not automatically get 225 statement. In this example, ``${SRCPV}`` does not automatically get
204 into ``PV``. Consequently, you need to change ``PV`` in your recipe 226 into ``PV``. Consequently, you need to change ``PV`` in your recipe
205 so that it does contain ``${SRCPV}``. 227 so that it does contain ``${SRCPV}``.
206 228
207 For more information see the "`Automatically Incrementing a Binary 229 For more information see the
208 Package Revision 230 ":ref:`dev-manual/dev-manual-common-tasks:automatically incrementing a package version number`"
209 Number <&YOCTO_DOCS_DEV_URL;#automatically-incrementing-a-binary-package-revision-number>`__"
210 section in the Yocto Project Development Tasks Manual. 231 section in the Yocto Project Development Tasks Manual.
211 232
212 AVAILABLE_LICENSES 233 AVAILABLE_LICENSES
213 List of licenses found in the directories specified by 234 List of licenses found in the directories specified by
214 :term:`COMMON_LICENSE_DIR` and 235 :term:`COMMON_LICENSE_DIR` and
215 :term:`LICENSE_PATH`. 236 :term:`LICENSE_PATH`.
216 237
217 .. note:: 238 .. note::
218 239
219 It is assumed that all changes to 240 It is assumed that all changes to
220 COMMON_LICENSE_DIR 241 COMMON_LICENSE_DIR
221 and 242 and
@@ -225,106 +246,113 @@ system and gives an overview of their function and contents.
225 is defined (in 246 is defined (in
226 license.bbclass 247 license.bbclass
227 ). 248 ).
228 249
229 AVAILTUNES 250 AVAILTUNES
230 The list of defined CPU and Application Binary Interface (ABI) 251 The list of defined CPU and Application Binary Interface (ABI)
231 tunings (i.e. "tunes") available for use by the OpenEmbedded build 252 tunings (i.e. "tunes") available for use by the OpenEmbedded build
232 system. 253 system.
233 254
234 The list simply presents the tunes that are available. Not all tunes 255 The list simply presents the tunes that are available. Not all tunes
235 may be compatible with a particular machine configuration, or with 256 may be compatible with a particular machine configuration, or with
236 each other in a 257 each other in a
237 `Multilib <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__ 258 :ref:`Multilib <dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image>`
238 configuration. 259 configuration.
239 260
240 To add a tune to the list, be sure to append it with spaces using the 261 To add a tune to the list, be sure to append it with spaces using the
241 "+=" BitBake operator. Do not simply replace the list by using the 262 "+=" BitBake operator. Do not simply replace the list by using the
242 "=" operator. See the 263 "=" operator. See the
243 ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake 264 ":ref:`Basic Syntax <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:basic syntax>`" section in the BitBake
244 User Manual for more information. 265 User Manual for more information.
245 266
246 B 267 B
247 The directory within the :term:`Build Directory` in 268 The directory within the :term:`Build Directory` in
248 which the OpenEmbedded build system places generated objects during a 269 which the OpenEmbedded build system places generated objects during a
249 recipe's build process. By default, this directory is the same as the 270 recipe's build process. By default, this directory is the same as the
250 :term:`S` directory, which is defined as: S = 271 :term:`S` directory, which is defined as:
251 "${WORKDIR}/${BP}" 272 ::
252 273
274 S = "${WORKDIR}/${BP}"
275
253 You can separate the (``S``) directory and the directory pointed to 276 You can separate the (``S``) directory and the directory pointed to
254 by the ``B`` variable. Most Autotools-based recipes support 277 by the ``B`` variable. Most Autotools-based recipes support
255 separating these directories. The build system defaults to using 278 separating these directories. The build system defaults to using
256 separate directories for ``gcc`` and some kernel recipes. 279 separate directories for ``gcc`` and some kernel recipes.
257 280
258 BAD_RECOMMENDATIONS 281 BAD_RECOMMENDATIONS
259 Lists "recommended-only" packages to not install. Recommended-only 282 Lists "recommended-only" packages to not install. Recommended-only
260 packages are packages installed only through the 283 packages are packages installed only through the
261 :term:`RRECOMMENDS` variable. You can prevent any 284 :term:`RRECOMMENDS` variable. You can prevent any
262 of these "recommended" packages from being installed by listing them 285 of these "recommended" packages from being installed by listing them
263 with the ``BAD_RECOMMENDATIONS`` variable: BAD_RECOMMENDATIONS = 286 with the ``BAD_RECOMMENDATIONS`` variable:
264 "package_name package_name package_name ..." 287 ::
265 288
289 BAD_RECOMMENDATIONS = "package_name package_name package_name ..."
290
266 You can set this variable globally in your ``local.conf`` file or you 291 You can set this variable globally in your ``local.conf`` file or you
267 can attach it to a specific image recipe by using the recipe name 292 can attach it to a specific image recipe by using the recipe name
268 override: BAD_RECOMMENDATIONS_pn-target_image = "package_name" 293 override:
269 294 ::
295
296 BAD_RECOMMENDATIONS_pn-target_image = "package_name"
297
270 It is important to realize that if you choose to not install packages 298 It is important to realize that if you choose to not install packages
271 using this variable and some other packages are dependent on them 299 using this variable and some other packages are dependent on them
272 (i.e. listed in a recipe's :term:`RDEPENDS` 300 (i.e. listed in a recipe's :term:`RDEPENDS`
273 variable), the OpenEmbedded build system ignores your request and 301 variable), the OpenEmbedded build system ignores your request and
274 will install the packages to avoid dependency errors. 302 will install the packages to avoid dependency errors.
275 303
276 Support for this variable exists only when using the IPK and RPM 304 Support for this variable exists only when using the IPK and RPM
277 packaging backend. Support does not exist for DEB. 305 packaging backend. Support does not exist for DEB.
278 306
279 See the :term:`NO_RECOMMENDATIONS` and the 307 See the :term:`NO_RECOMMENDATIONS` and the
280 :term:`PACKAGE_EXCLUDE` variables for related 308 :term:`PACKAGE_EXCLUDE` variables for related
281 information. 309 information.
282 310
283 BASE_LIB 311 BASE_LIB
284 The library directory name for the CPU or Application Binary 312 The library directory name for the CPU or Application Binary
285 Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib 313 Interface (ABI) tune. The ``BASE_LIB`` applies only in the Multilib
286 context. See the "`Combining Multiple Versions of Library Files into 314 context. See the ":ref:`dev-manual/dev-manual-common-tasks:combining multiple versions of library files into one image`"
287 One
288 Image <&YOCTO_DOCS_DEV_URL;#combining-multiple-versions-library-files-into-one-image>`__"
289 section in the Yocto Project Development Tasks Manual for information 315 section in the Yocto Project Development Tasks Manual for information
290 on Multilib. 316 on Multilib.
291 317
292 The ``BASE_LIB`` variable is defined in the machine include files in 318 The ``BASE_LIB`` variable is defined in the machine include files in
293 the :term:`Source Directory`. If Multilib is not 319 the :term:`Source Directory`. If Multilib is not
294 being used, the value defaults to "lib". 320 being used, the value defaults to "lib".
295 321
296 BASE_WORKDIR 322 BASE_WORKDIR
297 Points to the base of the work directory for all recipes. The default 323 Points to the base of the work directory for all recipes. The default
298 value is "${TMPDIR}/work". 324 value is "${TMPDIR}/work".
299 325
300 BB_ALLOWED_NETWORKS 326 BB_ALLOWED_NETWORKS
301 Specifies a space-delimited list of hosts that the fetcher is allowed 327 Specifies a space-delimited list of hosts that the fetcher is allowed
302 to use to obtain the required source code. Following are 328 to use to obtain the required source code. Following are
303 considerations surrounding this variable: 329 considerations surrounding this variable:
304 330
305 - This host list is only used if ``BB_NO_NETWORK`` is either not set 331 - This host list is only used if ``BB_NO_NETWORK`` is either not set
306 or set to "0". 332 or set to "0".
307 333
308 - Limited support for wildcard matching against the beginning of 334 - Limited support for wildcard matching against the beginning of
309 host names exists. For example, the following setting matches 335 host names exists. For example, the following setting matches
310 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``. 336 ``git.gnu.org``, ``ftp.gnu.org``, and ``foo.git.gnu.org``.
311 BB_ALLOWED_NETWORKS = "*.gnu.org" 337 ::
312 338
339 BB_ALLOWED_NETWORKS = "*.gnu.org"
340
313 .. note:: 341 .. note::
314 342
315 The use of the "``*``" character only works at the beginning of 343 The use of the "``*``" character only works at the beginning of
316 a host name and it must be isolated from the remainder of the 344 a host name and it must be isolated from the remainder of the
317 host name. You cannot use the wildcard character in any other 345 host name. You cannot use the wildcard character in any other
318 location of the name or combined with the front part of the 346 location of the name or combined with the front part of the
319 name. 347 name.
320 348
321 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar`` 349 For example, ``*.foo.bar`` is supported, while ``*aa.foo.bar``
322 is not. 350 is not.
323 351
324 - Mirrors not in the host list are skipped and logged in debug. 352 - Mirrors not in the host list are skipped and logged in debug.
325 353
326 - Attempts to access networks not in the host list cause a failure. 354 - Attempts to access networks not in the host list cause a failure.
327 355
328 Using ``BB_ALLOWED_NETWORKS`` in conjunction with 356 Using ``BB_ALLOWED_NETWORKS`` in conjunction with
329 :term:`PREMIRRORS` is very useful. Adding the host 357 :term:`PREMIRRORS` is very useful. Adding the host
330 you want to use to ``PREMIRRORS`` results in the source code being 358 you want to use to ``PREMIRRORS`` results in the source code being
@@ -333,7 +361,7 @@ system and gives an overview of their function and contents.
333 statement. This is because the fetcher does not attempt to use the 361 statement. This is because the fetcher does not attempt to use the
334 host listed in ``SRC_URI`` after a successful fetch from the 362 host listed in ``SRC_URI`` after a successful fetch from the
335 ``PREMIRRORS`` occurs. 363 ``PREMIRRORS`` occurs.
336 364
337 BB_DANGLINGAPPENDS_WARNONLY 365 BB_DANGLINGAPPENDS_WARNONLY
338 Defines how BitBake handles situations where an append file 366 Defines how BitBake handles situations where an append file
339 (``.bbappend``) has no corresponding recipe file (``.bb``). This 367 (``.bbappend``) has no corresponding recipe file (``.bb``). This
@@ -341,42 +369,69 @@ system and gives an overview of their function and contents.
341 bumps a recipe version and the old recipe no longer exists and the 369 bumps a recipe version and the old recipe no longer exists and the
342 other layer has not been updated to the new version of the recipe 370 other layer has not been updated to the new version of the recipe
343 yet). 371 yet).
344 372
345 The default fatal behavior is safest because it is the sane reaction 373 The default fatal behavior is safest because it is the sane reaction
346 given something is out of sync. It is important to realize when your 374 given something is out of sync. It is important to realize when your
347 changes are no longer being applied. 375 changes are no longer being applied.
348 376
349 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",
350 "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
351 :term:`Build Directory`: Here is an example: 379 :term:`Build Directory`: Here is an example:
352 BB_DANGLINGAPPENDS_WARNONLY = "1" 380 ::
353 381
382 BB_DANGLINGAPPENDS_WARNONLY = "1"
383
354 BB_DISKMON_DIRS 384 BB_DISKMON_DIRS
355 Monitors disk space and available inodes during the build and allows 385 Monitors disk space and available inodes during the build and allows
356 you to control the build based on these parameters. 386 you to control the build based on these parameters.
357 387
358 Disk space monitoring is disabled by default. To enable monitoring, 388 Disk space monitoring is disabled by default. To enable monitoring,
359 add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file 389 add the ``BB_DISKMON_DIRS`` variable to your ``conf/local.conf`` file
360 found in the :term:`Build Directory`. Use the 390 found in the :term:`Build Directory`. Use the
361 following form: BB_DISKMON_DIRS = "action,dir,threshold [...]" where: 391 following form:
362 action is: ABORT: Immediately abort the build when a threshold is 392 ::
363 broken. STOPTASKS: Stop the build after the currently executing tasks 393
364 have finished when a threshold is broken. WARN: Issue a warning but 394 BB_DISKMON_DIRS = "action,dir,threshold [...]"
365 continue the build when a threshold is broken. Subsequent warnings 395
366 are issued as defined by the BB_DISKMON_WARNINTERVAL variable, which 396 where:
367 must be defined in the conf/local.conf file. dir is: Any directory 397
368 you choose. You can specify one or more directories to monitor by 398 action is:
369 separating the groupings with a space. If two directories are on the 399 ABORT: Immediately abort the build when
370 same device, only the first directory is monitored. threshold is: 400 a threshold is broken.
371 Either the minimum available disk space, the minimum number of free 401 STOPTASKS: Stop the build after the currently
372 inodes, or both. You must specify at least one. To omit one or the 402 executing tasks have finished when
373 other, simply omit the value. Specify the threshold using G, M, K for 403 a threshold is broken.
374 Gbytes, Mbytes, and Kbytes, respectively. If you do not specify G, M, 404 WARN: Issue a warning but continue the
375 or K, Kbytes is assumed by default. Do not use GB, MB, or KB. 405 build when a threshold is broken.
376 406 Subsequent warnings are issued as
377 Here are some examples: BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K 407 defined by the BB_DISKMON_WARNINTERVAL
378 WARN,${SSTATE_DIR},1G,100K" BB_DISKMON_DIRS = 408 variable, which must be defined in
379 "STOPTASKS,${TMPDIR},1G" BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K" 409 the conf/local.conf file.
410
411 dir is:
412 Any directory you choose. You can specify one or
413 more directories to monitor by separating the
414 groupings with a space. If two directories are
415 on the same device, only the first directory
416 is monitored.
417
418 threshold is:
419 Either the minimum available disk space,
420 the minimum number of free inodes, or
421 both. You must specify at least one. To
422 omit one or the other, simply omit the value.
423 Specify the threshold using G, M, K for Gbytes,
424 Mbytes, and Kbytes, respectively. If you do
425 not specify G, M, or K, Kbytes is assumed by
426 default. Do not use GB, MB, or KB.
427
428 Here are some examples:
429 ::
430
431 BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
432 BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
433 BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
434
380 The first example works only if you also provide the 435 The first example works only if you also provide the
381 :term:`BB_DISKMON_WARNINTERVAL` 436 :term:`BB_DISKMON_WARNINTERVAL`
382 variable in the ``conf/local.conf``. This example causes the build 437 variable in the ``conf/local.conf``. This example causes the build
@@ -388,64 +443,85 @@ system and gives an overview of their function and contents.
388 of free inodes drops below 100 Kbytes. Subsequent warnings are issued 443 of free inodes drops below 100 Kbytes. Subsequent warnings are issued
389 during intervals as defined by the ``BB_DISKMON_WARNINTERVAL`` 444 during intervals as defined by the ``BB_DISKMON_WARNINTERVAL``
390 variable. 445 variable.
391 446
392 The second example stops the build after all currently executing 447 The second example stops the build after all currently executing
393 tasks complete when the minimum disk space in the ``${TMPDIR}`` 448 tasks complete when the minimum disk space in the ``${TMPDIR}``
394 directory drops below 1 Gbyte. No disk monitoring occurs for the free 449 directory drops below 1 Gbyte. No disk monitoring occurs for the free
395 inodes in this case. 450 inodes in this case.
396 451
397 The final example immediately aborts the build when the number of 452 The final example immediately aborts the build when the number of
398 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No 453 free inodes in the ``${TMPDIR}`` directory drops below 100 Kbytes. No
399 disk space monitoring for the directory itself occurs in this case. 454 disk space monitoring for the directory itself occurs in this case.
400 455
401 BB_DISKMON_WARNINTERVAL 456 BB_DISKMON_WARNINTERVAL
402 Defines the disk space and free inode warning intervals. To set these 457 Defines the disk space and free inode warning intervals. To set these
403 intervals, define the variable in your ``conf/local.conf`` file in 458 intervals, define the variable in your ``conf/local.conf`` file in
404 the :term:`Build Directory`. 459 the :term:`Build Directory`.
405 460
406 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you 461 If you are going to use the ``BB_DISKMON_WARNINTERVAL`` variable, you
407 must also use the :term:`BB_DISKMON_DIRS` 462 must also use the :term:`BB_DISKMON_DIRS`
408 variable and define its action as "WARN". During the build, 463 variable and define its action as "WARN". During the build,
409 subsequent warnings are issued each time disk space or number of free 464 subsequent warnings are issued each time disk space or number of free
410 inodes further reduces by the respective interval. 465 inodes further reduces by the respective interval.
411 466
412 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you 467 If you do not provide a ``BB_DISKMON_WARNINTERVAL`` variable and you
413 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk 468 do use ``BB_DISKMON_DIRS`` with the "WARN" action, the disk
414 monitoring interval defaults to the following: 469 monitoring interval defaults to the following:
415 BB_DISKMON_WARNINTERVAL = "50M,5K" 470 ::
416 471
472 BB_DISKMON_WARNINTERVAL = "50M,5K"
473
417 When specifying the variable in your configuration file, use the 474 When specifying the variable in your configuration file, use the
418 following form: BB_DISKMON_WARNINTERVAL = 475 following form:
419 "disk_space_interval,disk_inode_interval" where: disk_space_interval 476 ::
420 is: An interval of memory expressed in either G, M, or K for Gbytes, 477
421 Mbytes, or Kbytes, respectively. You cannot use GB, MB, or KB. 478 BB_DISKMON_WARNINTERVAL = "disk_space_interval,disk_inode_interval"
422 disk_inode_interval is: An interval of free inodes expressed in 479
423 either G, M, or K for Gbytes, Mbytes, or Kbytes, respectively. You 480 where:
424 cannot use GB, MB, or KB. 481
425 482 disk_space_interval is:
426 Here is an example: BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K" 483 An interval of memory expressed in either
427 BB_DISKMON_WARNINTERVAL = "50M,5K" These variables cause the 484 G, M, or K for Gbytes, Mbytes, or Kbytes,
485 respectively. You cannot use GB, MB, or KB.
486
487 disk_inode_interval is:
488 An interval of free inodes expressed in either
489 G, M, or K for Gbytes, Mbytes, or Kbytes,
490 respectively. You cannot use GB, MB, or KB.
491
492 Here is an example:
493 ::
494
495 BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
496 BB_DISKMON_WARNINTERVAL = "50M,5K"
497
498 These variables cause the
428 OpenEmbedded build system to issue subsequent warnings each time the 499 OpenEmbedded build system to issue subsequent warnings each time the
429 available disk space further reduces by 50 Mbytes or the number of 500 available disk space further reduces by 50 Mbytes or the number of
430 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}`` 501 free inodes further reduces by 5 Kbytes in the ``${SSTATE_DIR}``
431 directory. Subsequent warnings based on the interval occur each time 502 directory. Subsequent warnings based on the interval occur each time
432 a respective interval is reached beyond the initial warning (i.e. 1 503 a respective interval is reached beyond the initial warning (i.e. 1
433 Gbytes and 100 Kbytes). 504 Gbytes and 100 Kbytes).
434 505
435 BB_GENERATE_MIRROR_TARBALLS 506 BB_GENERATE_MIRROR_TARBALLS
436 Causes tarballs of the source control repositories (e.g. Git 507 Causes tarballs of the source control repositories (e.g. Git
437 repositories), including metadata, to be placed in the 508 repositories), including metadata, to be placed in the
438 :term:`DL_DIR` directory. 509 :term:`DL_DIR` directory.
439 510
440 For performance reasons, creating and placing tarballs of these 511 For performance reasons, creating and placing tarballs of these
441 repositories is not the default action by the OpenEmbedded build 512 repositories is not the default action by the OpenEmbedded build
442 system. BB_GENERATE_MIRROR_TARBALLS = "1" Set this variable in your 513 system.
514 ::
515
516 BB_GENERATE_MIRROR_TARBALLS = "1"
517
518 Set this variable in your
443 ``local.conf`` file in the :term:`Build Directory`. 519 ``local.conf`` file in the :term:`Build Directory`.
444 520
445 Once you have the tarballs containing your source files, you can 521 Once you have the tarballs containing your source files, you can
446 clean up your ``DL_DIR`` directory by deleting any Git or other 522 clean up your ``DL_DIR`` directory by deleting any Git or other
447 source control work directories. 523 source control work directories.
448 524
449 BB_NUMBER_THREADS 525 BB_NUMBER_THREADS
450 The maximum number of tasks BitBake should run in parallel at any one 526 The maximum number of tasks BitBake should run in parallel at any one
451 time. The OpenEmbedded build system automatically configures this 527 time. The OpenEmbedded build system automatically configures this
@@ -453,27 +529,31 @@ system and gives an overview of their function and contents.
453 example, a system with a dual core processor that also uses 529 example, a system with a dual core processor that also uses
454 hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default 530 hyper-threading causes the ``BB_NUMBER_THREADS`` variable to default
455 to "4". 531 to "4".
456 532
457 For single socket systems (i.e. one CPU), you should not have to 533 For single socket systems (i.e. one CPU), you should not have to
458 override this variable to gain optimal parallelism during builds. 534 override this variable to gain optimal parallelism during builds.
459 However, if you have very large systems that employ multiple physical 535 However, if you have very large systems that employ multiple physical
460 CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable 536 CPUs, you might want to make sure the ``BB_NUMBER_THREADS`` variable
461 is not set higher than "20". 537 is not set higher than "20".
462 538
463 For more information on speeding up builds, see the "`Speeding Up a 539 For more information on speeding up builds, see the
464 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the 540 ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`"
465 Yocto Project Development Tasks Manual. 541 section in the Yocto Project Development Tasks Manual.
466 542
467 BB_SERVER_TIMEOUT 543 BB_SERVER_TIMEOUT
468 Specifies the time (in seconds) after which to unload the BitBake 544 Specifies the time (in seconds) after which to unload the BitBake
469 server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how 545 server due to inactivity. Set ``BB_SERVER_TIMEOUT`` to determine how
470 long the BitBake server stays resident between invocations. 546 long the BitBake server stays resident between invocations.
471 547
472 For example, the following statement in your ``local.conf`` file 548 For example, the following statement in your ``local.conf`` file
473 instructs the server to be unloaded after 20 seconds of inactivity: 549 instructs the server to be unloaded after 20 seconds of inactivity:
474 BB_SERVER_TIMEOUT = "20" If you want the server to never be unloaded, 550 ::
551
552 BB_SERVER_TIMEOUT = "20"
553
554 If you want the server to never be unloaded,
475 set ``BB_SERVER_TIMEOUT`` to "-1". 555 set ``BB_SERVER_TIMEOUT`` to "-1".
476 556
477 BBCLASSEXTEND 557 BBCLASSEXTEND
478 Allows you to extend a recipe so that it builds variants of the 558 Allows you to extend a recipe so that it builds variants of the
479 software. Common variants for recipes exist such as "natives" like 559 software. Common variants for recipes exist such as "natives" like
@@ -483,40 +563,42 @@ system and gives an overview of their function and contents.
483 :term:`MACHINE`; "nativesdk", which targets the SDK 563 :term:`MACHINE`; "nativesdk", which targets the SDK
484 machine instead of ``MACHINE``; and "mulitlibs" in the form 564 machine instead of ``MACHINE``; and "mulitlibs" in the form
485 "``multilib:``\ multilib_name". 565 "``multilib:``\ multilib_name".
486 566
487 To build a different variant of the recipe with a minimal amount of 567 To build a different variant of the recipe with a minimal amount of
488 code, it usually is as simple as adding the following to your recipe: 568 code, it usually is as simple as adding the following to your recipe:
489 BBCLASSEXTEND =+ "native nativesdk" BBCLASSEXTEND =+ 569 ::
490 "multilib:multilib_name" 570
491 571 BBCLASSEXTEND =+ "native nativesdk"
572 BBCLASSEXTEND =+ "multilib:multilib_name"
573
492 .. note:: 574 .. note::
493 575
494 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe 576 Internally, the ``BBCLASSEXTEND`` mechanism generates recipe
495 variants by rewriting variable values and applying overrides such 577 variants by rewriting variable values and applying overrides such
496 as ``_class-native``. For example, to generate a native version of 578 as ``_class-native``. For example, to generate a native version of
497 a recipe, a :term:`DEPENDS` on "foo" is rewritten 579 a recipe, a :term:`DEPENDS` on "foo" is rewritten
498 to a ``DEPENDS`` on "foo-native". 580 to a ``DEPENDS`` on "foo-native".
499 581
500 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once. 582 Even when using ``BBCLASSEXTEND``, the recipe is only parsed once.
501 Parsing once adds some limitations. For example, it is not 583 Parsing once adds some limitations. For example, it is not
502 possible to include a different file depending on the variant, 584 possible to include a different file depending on the variant,
503 since ``include`` statements are processed when the recipe is 585 since ``include`` statements are processed when the recipe is
504 parsed. 586 parsed.
505 587
506 BBFILE_COLLECTIONS 588 BBFILE_COLLECTIONS
507 Lists the names of configured layers. These names are used to find 589 Lists the names of configured layers. These names are used to find
508 the other ``BBFILE_*`` variables. Typically, each layer will append 590 the other ``BBFILE_*`` variables. Typically, each layer will append
509 its name to this variable in its ``conf/layer.conf`` file. 591 its name to this variable in its ``conf/layer.conf`` file.
510 592
511 BBFILE_PATTERN 593 BBFILE_PATTERN
512 Variable that expands to match files from 594 Variable that expands to match files from
513 :term:`BBFILES` in a particular layer. This variable 595 :term:`BBFILES` in a particular layer. This variable
514 is used in the ``conf/layer.conf`` file and must be suffixed with the 596 is used in the ``conf/layer.conf`` file and must be suffixed with the
515 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``). 597 name of the specific layer (e.g. ``BBFILE_PATTERN_emenlow``).
516 598
517 BBFILE_PRIORITY 599 BBFILE_PRIORITY
518 Assigns the priority for recipe files in each layer. 600 Assigns the priority for recipe files in each layer.
519 601
520 This variable is useful in situations where the same recipe appears 602 This variable is useful in situations where the same recipe appears
521 in more than one layer. Setting this variable allows you to 603 in more than one layer. Setting this variable allows you to
522 prioritize a layer against other layers that contain the same recipe 604 prioritize a layer against other layers that contain the same recipe
@@ -526,7 +608,7 @@ system and gives an overview of their function and contents.
526 example, a layer that has a recipe with a higher ``PV`` value but for 608 example, a layer that has a recipe with a higher ``PV`` value but for
527 which the ``BBFILE_PRIORITY`` is set to have a lower precedence still 609 which the ``BBFILE_PRIORITY`` is set to have a lower precedence still
528 has a lower precedence. 610 has a lower precedence.
529 611
530 A larger value for the ``BBFILE_PRIORITY`` variable results in a 612 A larger value for the ``BBFILE_PRIORITY`` variable results in a
531 higher precedence. For example, the value 6 has a higher precedence 613 higher precedence. For example, the value 6 has a higher precedence
532 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable 614 than the value 5. If not specified, the ``BBFILE_PRIORITY`` variable
@@ -534,116 +616,136 @@ system and gives an overview of their function and contents.
534 for more information. The default priority, if unspecified for a 616 for more information. The default priority, if unspecified for a
535 layer with no dependencies, is the lowest defined priority + 1 (or 1 617 layer with no dependencies, is the lowest defined priority + 1 (or 1
536 if no priorities are defined). 618 if no priorities are defined).
537 619
538 .. tip:: 620 .. tip::
539 621
540 You can use the command 622 You can use the command
541 bitbake-layers show-layers 623 bitbake-layers show-layers
542 to list all configured layers along with their priorities. 624 to list all configured layers along with their priorities.
543 625
544 BBFILES 626 BBFILES
545 A space-separated list of recipe files BitBake uses to build 627 A space-separated list of recipe files BitBake uses to build
546 software. 628 software.
547 629
548 When specifying recipe files, you can pattern match using Python's 630 When specifying recipe files, you can pattern match using Python's
549 ```glob`https://docs.python.org/3/library/glob.html syntax. 631 `glob <https://docs.python.org/3/library/glob.html>`_ syntax.
550 For details on the syntax, see the documentation by following the 632 For details on the syntax, see the documentation by following the
551 previous link. 633 previous link.
552 634
553 BBFILES_DYNAMIC 635 BBFILES_DYNAMIC
554 Activates content when identified layers are present. You identify 636 Activates content when identified layers are present. You identify
555 the layers by the collections that the layers define. 637 the layers by the collections that the layers define.
556 638
557 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files 639 Use the ``BBFILES_DYNAMIC`` variable to avoid ``.bbappend`` files
558 whose corresponding ``.bb`` file is in a layer that attempts to 640 whose corresponding ``.bb`` file is in a layer that attempts to
559 modify other layers through ``.bbappend`` but does not want to 641 modify other layers through ``.bbappend`` but does not want to
560 introduce a hard dependency on those other layers. 642 introduce a hard dependency on those other layers.
561 643
562 Use the following form for ``BBFILES_DYNAMIC``: 644 Use the following form for ``BBFILES_DYNAMIC``:
563 collection_name:filename_pattern The following example identifies two 645 collection_name:filename_pattern The following example identifies two
564 collection names and two filename patterns: BBFILES_DYNAMIC += " \\ 646 collection names and two filename patterns:
565 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \\ 647 ::
566 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \\ " 648
649 BBFILES_DYNAMIC += " \
650 clang-layer:${LAYERDIR}/bbappends/meta-clang/*/*/*.bbappend \
651 core:${LAYERDIR}/bbappends/openembedded-core/meta/*/*/*.bbappend \
652 "
653
567 This next example shows an error message that occurs because invalid 654 This next example shows an error message that occurs because invalid
568 entries are found, which cause parsing to abort: ERROR: 655 entries are found, which cause parsing to abort:
569 BBFILES_DYNAMIC entries must be of the form <collection 656 ::
570 name>:<filename pattern>, not: 657
571 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend 658 ERROR: BBFILES_DYNAMIC entries must be of the form <collection name>:<filename pattern>, not:
572 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend 659 /work/my-layer/bbappends/meta-security-isafw/*/*/*.bbappend
573 660 /work/my-layer/bbappends/openembedded-core/meta/*/*/*.bbappend
661
574 BBINCLUDELOGS 662 BBINCLUDELOGS
575 Variable that controls how BitBake displays logs on build failure. 663 Variable that controls how BitBake displays logs on build failure.
576 664
577 BBINCLUDELOGS_LINES 665 BBINCLUDELOGS_LINES
578 If :term:`BBINCLUDELOGS` is set, specifies the 666 If :term:`BBINCLUDELOGS` is set, specifies the
579 maximum number of lines from the task log file to print when 667 maximum number of lines from the task log file to print when
580 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``, 668 reporting a failed task. If you do not set ``BBINCLUDELOGS_LINES``,
581 the entire log is printed. 669 the entire log is printed.
582 670
583 BBLAYERS 671 BBLAYERS
584 Lists the layers to enable during the build. This variable is defined 672 Lists the layers to enable during the build. This variable is defined
585 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`. 673 in the ``bblayers.conf`` configuration file in the :term:`Build Directory`.
586 Here is an example: BBLAYERS = " \\ 674 Here is an example:
587 /home/scottrif/poky/meta \\ /home/scottrif/poky/meta-poky \\ 675 ::
588 /home/scottrif/poky/meta-yocto-bsp \\ 676
589 /home/scottrif/poky/meta-mykernel \\ " 677 BBLAYERS = " \
590 678 /home/scottrif/poky/meta \ /home/scottrif/poky/meta-poky \
679 /home/scottrif/poky/meta-yocto-bsp \
680 /home/scottrif/poky/meta-mykernel \
681 "
682
591 This example enables four layers, one of which is a custom, 683 This example enables four layers, one of which is a custom,
592 user-defined layer named ``meta-mykernel``. 684 user-defined layer named ``meta-mykernel``.
593 685
594 BBMASK 686 BBMASK
595 Prevents BitBake from processing recipes and recipe append files. 687 Prevents BitBake from processing recipes and recipe append files.
596 688
597 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and 689 You can use the ``BBMASK`` variable to "hide" these ``.bb`` and
598 ``.bbappend`` files. BitBake ignores any recipe or recipe append 690 ``.bbappend`` files. BitBake ignores any recipe or recipe append
599 files that match any of the expressions. It is as if BitBake does not 691 files that match any of the expressions. It is as if BitBake does not
600 see them at all. Consequently, matching files are not parsed or 692 see them at all. Consequently, matching files are not parsed or
601 otherwise used by BitBake. 693 otherwise used by BitBake.
602 694
603 The values you provide are passed to Python's regular expression 695 The values you provide are passed to Python's regular expression
604 compiler. Consequently, the syntax follows Python's Regular 696 compiler. Consequently, the syntax follows Python's Regular
605 Expression (re) syntax. The expressions are compared against the full 697 Expression (re) syntax. The expressions are compared against the full
606 paths to the files. For complete syntax information, see Python's 698 paths to the files. For complete syntax information, see Python's
607 documentation at http://docs.python.org/3/library/re.html#re. 699 documentation at http://docs.python.org/3/library/re.html#re.
608 700
609 The following example uses a complete regular expression to tell 701 The following example uses a complete regular expression to tell
610 BitBake to ignore all recipe and recipe append files in the 702 BitBake to ignore all recipe and recipe append files in the
611 ``meta-ti/recipes-misc/`` directory: BBMASK = "meta-ti/recipes-misc/" 703 ``meta-ti/recipes-misc/`` directory:
704 ::
705
706 BBMASK = "meta-ti/recipes-misc/"
707
612 If you want to mask out multiple directories or recipes, you can 708 If you want to mask out multiple directories or recipes, you can
613 specify multiple regular expression fragments. This next example 709 specify multiple regular expression fragments. This next example
614 masks out multiple directories and individual recipes: BBMASK += 710 masks out multiple directories and individual recipes: ::
615 "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/" BBMASK += 711
616 "/meta-oe/recipes-support/" BBMASK += "/meta-foo/.*/openldap" BBMASK 712 BBMASK += "/meta-ti/recipes-misc/ meta-ti/recipes-ti/packagegroup/"
617 += "opencv.*\.bbappend" BBMASK += "lzma" 713 BBMASK += "/meta-oe/recipes-support/"
618 714 BBMASK += "/meta-foo/.*/openldap"
715 BBMASK += "opencv.*\.bbappend"
716 BBMASK += "lzma"
717
619 .. note:: 718 .. note::
620 719
621 When specifying a directory name, use the trailing slash character 720 When specifying a directory name, use the trailing slash character
622 to ensure you match just that directory name. 721 to ensure you match just that directory name.
623 722
624 BBMULTICONFIG 723 BBMULTICONFIG
625 Specifies each additional separate configuration when you are 724 Specifies each additional separate configuration when you are
626 building targets with multiple configurations. Use this variable in 725 building targets with multiple configurations. Use this variable in
627 your ``conf/local.conf`` configuration file. Specify a 726 your ``conf/local.conf`` configuration file. Specify a
628 multiconfigname for each configuration file you are using. For 727 multiconfigname for each configuration file you are using. For
629 example, the following line specifies three configuration files: 728 example, the following line specifies three configuration files:
630 BBMULTICONFIG = "configA configB configC" Each configuration file you 729 ::
730
731 BBMULTICONFIG = "configA configB configC"
732
733 Each configuration file you
631 use must reside in the :term:`Build Directory` 734 use must reside in the :term:`Build Directory`
632 ``conf/multiconfig`` directory (e.g. 735 ``conf/multiconfig`` directory (e.g.
633 build_directory\ ``/conf/multiconfig/configA.conf``). 736 build_directory\ ``/conf/multiconfig/configA.conf``).
634 737
635 For information on how to use ``BBMULTICONFIG`` in an environment 738 For information on how to use ``BBMULTICONFIG`` in an environment
636 that supports building targets with multiple configurations, see the 739 that supports building targets with multiple configurations, see the
637 "`Building Images for Multiple Targets Using Multiple 740 ":ref:`dev-building-images-for-multiple-targets-using-multiple-configurations`"
638 Configurations <&YOCTO_DOCS_DEV_URL;#dev-building-images-for-multiple-targets-using-multiple-configurations>`__"
639 section in the Yocto Project Development Tasks Manual. 741 section in the Yocto Project Development Tasks Manual.
640 742
641 BBPATH 743 BBPATH
642 Used by BitBake to locate ``.bbclass`` and configuration files. This 744 Used by BitBake to locate ``.bbclass`` and configuration files. This
643 variable is analogous to the ``PATH`` variable. 745 variable is analogous to the ``PATH`` variable.
644 746
645 .. note:: 747 .. note::
646 748
647 If you run BitBake from a directory outside of the 749 If you run BitBake from a directory outside of the
648 Build Directory 750 Build Directory
649 , you must be sure to set 751 , you must be sure to set
@@ -651,24 +753,27 @@ system and gives an overview of their function and contents.
651 to point to the Build Directory. Set the variable as you would any 753 to point to the Build Directory. Set the variable as you would any
652 environment variable and then run BitBake: 754 environment variable and then run BitBake:
653 :: 755 ::
654 756
655 $ BBPATH = "build_directory" 757 $ BBPATH = "build_directory"
656 $ export BBPATH 758 $ export BBPATH
657 $ bitbake target 759 $ bitbake target
658 760
659 761
660 BBSERVER 762 BBSERVER
661 If defined in the BitBake environment, ``BBSERVER`` points to the 763 If defined in the BitBake environment, ``BBSERVER`` points to the
662 BitBake remote server. 764 BitBake remote server.
663 765
664 Use the following format to export the variable to the BitBake 766 Use the following format to export the variable to the BitBake
665 environment: export BBSERVER=localhost:$port 767 environment:
666 768 ::
769
770 export BBSERVER=localhost:$port
771
667 By default, ``BBSERVER`` also appears in 772 By default, ``BBSERVER`` also appears in
668 :term:`bitbake:BB_HASHBASE_WHITELIST`. 773 :term:`bitbake:BB_HASHBASE_WHITELIST`.
669 Consequently, ``BBSERVER`` is excluded from checksum and dependency 774 Consequently, ``BBSERVER`` is excluded from checksum and dependency
670 data. 775 data.
671 776
672 BINCONFIG 777 BINCONFIG
673 When inheriting the 778 When inheriting the
674 :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class, 779 :ref:`binconfig-disabled <ref-classes-binconfig-disabled>` class,
@@ -677,11 +782,13 @@ system and gives an overview of their function and contents.
677 ``binconfig-disabled`` class will modify the specified scripts to 782 ``binconfig-disabled`` class will modify the specified scripts to
678 return an error so that calls to them can be easily found and 783 return an error so that calls to them can be easily found and
679 replaced. 784 replaced.
680 785
681 To add multiple scripts, separate them by spaces. Here is an example 786 To add multiple scripts, separate them by spaces. Here is an example
682 from the ``libpng`` recipe: BINCONFIG = "${bindir}/libpng-config 787 from the ``libpng`` recipe:
683 ${bindir}/libpng16-config" 788 ::
684 789
790 BINCONFIG = "${bindir}/libpng-config ${bindir}/libpng16-config"
791
685 BINCONFIG_GLOB 792 BINCONFIG_GLOB
686 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, 793 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
687 this variable specifies a wildcard for configuration scripts that 794 this variable specifies a wildcard for configuration scripts that
@@ -689,9 +796,9 @@ system and gives an overview of their function and contents.
689 been set up during compilation so that they are correct for use when 796 been set up during compilation so that they are correct for use when
690 installed into the sysroot and called by the build processes of other 797 installed into the sysroot and called by the build processes of other
691 recipes. 798 recipes.
692 799
693 .. note:: 800 .. note::
694 801
695 The 802 The
696 BINCONFIG_GLOB 803 BINCONFIG_GLOB
697 variable uses 804 variable uses
@@ -702,18 +809,21 @@ system and gives an overview of their function and contents.
702 and 809 and
703 glob 810 glob
704 . 811 .
705 812
706 For more information on how this variable works, see 813 For more information on how this variable works, see
707 ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`. 814 ``meta/classes/binconfig.bbclass`` in the :term:`Source Directory`.
708 You can also find general 815 You can also find general
709 information on the class in the 816 information on the class in the
710 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. 817 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
711 818
712 BP 819 BP
713 The base recipe name and version but without any special recipe name 820 The base recipe name and version but without any special recipe name
714 suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is 821 suffix (i.e. ``-native``, ``lib64-``, and so forth). ``BP`` is
715 comprised of the following: ${BPN}-${PV} 822 comprised of the following:
716 823 ::
824
825 ${BPN}-${PV}
826
717 BPN 827 BPN
718 This variable is a version of the :term:`PN` variable with 828 This variable is a version of the :term:`PN` variable with
719 common prefixes and suffixes removed, such as ``nativesdk-``, 829 common prefixes and suffixes removed, such as ``nativesdk-``,
@@ -722,115 +832,115 @@ system and gives an overview of their function and contents.
722 :term:`MLPREFIX` and 832 :term:`MLPREFIX` and
723 :term:`SPECIAL_PKGSUFFIX` variables, 833 :term:`SPECIAL_PKGSUFFIX` variables,
724 respectively. 834 respectively.
725 835
726 BUGTRACKER 836 BUGTRACKER
727 Specifies a URL for an upstream bug tracking website for a recipe. 837 Specifies a URL for an upstream bug tracking website for a recipe.
728 The OpenEmbedded build system does not use this variable. Rather, the 838 The OpenEmbedded build system does not use this variable. Rather, the
729 variable is a useful pointer in case a bug in the software being 839 variable is a useful pointer in case a bug in the software being
730 built needs to be manually reported. 840 built needs to be manually reported.
731 841
732 BUILD_ARCH 842 BUILD_ARCH
733 Specifies the architecture of the build host (e.g. ``i686``). The 843 Specifies the architecture of the build host (e.g. ``i686``). The
734 OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the 844 OpenEmbedded build system sets the value of ``BUILD_ARCH`` from the
735 machine name reported by the ``uname`` command. 845 machine name reported by the ``uname`` command.
736 846
737 BUILD_AS_ARCH 847 BUILD_AS_ARCH
738 Specifies the architecture-specific assembler flags for the build 848 Specifies the architecture-specific assembler flags for the build
739 host. By default, the value of ``BUILD_AS_ARCH`` is empty. 849 host. By default, the value of ``BUILD_AS_ARCH`` is empty.
740 850
741 BUILD_CC_ARCH 851 BUILD_CC_ARCH
742 Specifies the architecture-specific C compiler flags for the build 852 Specifies the architecture-specific C compiler flags for the build
743 host. By default, the value of ``BUILD_CC_ARCH`` is empty. 853 host. By default, the value of ``BUILD_CC_ARCH`` is empty.
744 854
745 BUILD_CCLD 855 BUILD_CCLD
746 Specifies the linker command to be used for the build host when the C 856 Specifies the linker command to be used for the build host when the C
747 compiler is being used as the linker. By default, ``BUILD_CCLD`` 857 compiler is being used as the linker. By default, ``BUILD_CCLD``
748 points to GCC and passes as arguments the value of 858 points to GCC and passes as arguments the value of
749 :term:`BUILD_CC_ARCH`, assuming 859 :term:`BUILD_CC_ARCH`, assuming
750 ``BUILD_CC_ARCH`` is set. 860 ``BUILD_CC_ARCH`` is set.
751 861
752 BUILD_CFLAGS 862 BUILD_CFLAGS
753 Specifies the flags to pass to the C compiler when building for the 863 Specifies the flags to pass to the C compiler when building for the
754 build host. When building in the ``-native`` context, 864 build host. When building in the ``-native`` context,
755 :term:`CFLAGS` is set to the value of this variable by 865 :term:`CFLAGS` is set to the value of this variable by
756 default. 866 default.
757 867
758 BUILD_CPPFLAGS 868 BUILD_CPPFLAGS
759 Specifies the flags to pass to the C preprocessor (i.e. to both the C 869 Specifies the flags to pass to the C preprocessor (i.e. to both the C
760 and the C++ compilers) when building for the build host. When 870 and the C++ compilers) when building for the build host. When
761 building in the ``-native`` context, :term:`CPPFLAGS` 871 building in the ``-native`` context, :term:`CPPFLAGS`
762 is set to the value of this variable by default. 872 is set to the value of this variable by default.
763 873
764 BUILD_CXXFLAGS 874 BUILD_CXXFLAGS
765 Specifies the flags to pass to the C++ compiler when building for the 875 Specifies the flags to pass to the C++ compiler when building for the
766 build host. When building in the ``-native`` context, 876 build host. When building in the ``-native`` context,
767 :term:`CXXFLAGS` is set to the value of this variable 877 :term:`CXXFLAGS` is set to the value of this variable
768 by default. 878 by default.
769 879
770 BUILD_FC 880 BUILD_FC
771 Specifies the Fortran compiler command for the build host. By 881 Specifies the Fortran compiler command for the build host. By
772 default, ``BUILD_FC`` points to Gfortran and passes as arguments the 882 default, ``BUILD_FC`` points to Gfortran and passes as arguments the
773 value of :term:`BUILD_CC_ARCH`, assuming 883 value of :term:`BUILD_CC_ARCH`, assuming
774 ``BUILD_CC_ARCH`` is set. 884 ``BUILD_CC_ARCH`` is set.
775 885
776 BUILD_LD 886 BUILD_LD
777 Specifies the linker command for the build host. By default, 887 Specifies the linker command for the build host. By default,
778 ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments 888 ``BUILD_LD`` points to the GNU linker (ld) and passes as arguments
779 the value of :term:`BUILD_LD_ARCH`, assuming 889 the value of :term:`BUILD_LD_ARCH`, assuming
780 ``BUILD_LD_ARCH`` is set. 890 ``BUILD_LD_ARCH`` is set.
781 891
782 BUILD_LD_ARCH 892 BUILD_LD_ARCH
783 Specifies architecture-specific linker flags for the build host. By 893 Specifies architecture-specific linker flags for the build host. By
784 default, the value of ``BUILD_LD_ARCH`` is empty. 894 default, the value of ``BUILD_LD_ARCH`` is empty.
785 895
786 BUILD_LDFLAGS 896 BUILD_LDFLAGS
787 Specifies the flags to pass to the linker when building for the build 897 Specifies the flags to pass to the linker when building for the build
788 host. When building in the ``-native`` context, 898 host. When building in the ``-native`` context,
789 :term:`LDFLAGS` is set to the value of this variable 899 :term:`LDFLAGS` is set to the value of this variable
790 by default. 900 by default.
791 901
792 BUILD_OPTIMIZATION 902 BUILD_OPTIMIZATION
793 Specifies the optimization flags passed to the C compiler when 903 Specifies the optimization flags passed to the C compiler when
794 building for the build host or the SDK. The flags are passed through 904 building for the build host or the SDK. The flags are passed through
795 the :term:`BUILD_CFLAGS` and 905 the :term:`BUILD_CFLAGS` and
796 :term:`BUILDSDK_CFLAGS` default values. 906 :term:`BUILDSDK_CFLAGS` default values.
797 907
798 The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2 908 The default value of the ``BUILD_OPTIMIZATION`` variable is "-O2
799 -pipe". 909 -pipe".
800 910
801 BUILD_OS 911 BUILD_OS
802 Specifies the operating system in use on the build host (e.g. 912 Specifies the operating system in use on the build host (e.g.
803 "linux"). The OpenEmbedded build system sets the value of 913 "linux"). The OpenEmbedded build system sets the value of
804 ``BUILD_OS`` from the OS reported by the ``uname`` command - the 914 ``BUILD_OS`` from the OS reported by the ``uname`` command - the
805 first word, converted to lower-case characters. 915 first word, converted to lower-case characters.
806 916
807 BUILD_PREFIX 917 BUILD_PREFIX
808 The toolchain binary prefix used for native recipes. The OpenEmbedded 918 The toolchain binary prefix used for native recipes. The OpenEmbedded
809 build system uses the ``BUILD_PREFIX`` value to set the 919 build system uses the ``BUILD_PREFIX`` value to set the
810 :term:`TARGET_PREFIX` when building for 920 :term:`TARGET_PREFIX` when building for
811 ``native`` recipes. 921 ``native`` recipes.
812 922
813 BUILD_STRIP 923 BUILD_STRIP
814 Specifies the command to be used to strip debugging symbols from 924 Specifies the command to be used to strip debugging symbols from
815 binaries produced for the build host. By default, ``BUILD_STRIP`` 925 binaries produced for the build host. By default, ``BUILD_STRIP``
816 points to 926 points to
817 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``. 927 ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
818 928
819 BUILD_SYS 929 BUILD_SYS
820 Specifies the system, including the architecture and the operating 930 Specifies the system, including the architecture and the operating
821 system, to use when building for the build host (i.e. when building 931 system, to use when building for the build host (i.e. when building
822 ``native`` recipes). 932 ``native`` recipes).
823 933
824 The OpenEmbedded build system automatically sets this variable based 934 The OpenEmbedded build system automatically sets this variable based
825 on :term:`BUILD_ARCH`, 935 on :term:`BUILD_ARCH`,
826 :term:`BUILD_VENDOR`, and 936 :term:`BUILD_VENDOR`, and
827 :term:`BUILD_OS`. You do not need to set the 937 :term:`BUILD_OS`. You do not need to set the
828 ``BUILD_SYS`` variable yourself. 938 ``BUILD_SYS`` variable yourself.
829 939
830 BUILD_VENDOR 940 BUILD_VENDOR
831 Specifies the vendor name to use when building for the build host. 941 Specifies the vendor name to use when building for the build host.
832 The default value is an empty string (""). 942 The default value is an empty string ("").
833 943
834 BUILDDIR 944 BUILDDIR
835 Points to the location of the :term:`Build Directory`. 945 Points to the location of the :term:`Build Directory`.
836 You can define this directory indirectly through the 946 You can define this directory indirectly through the
@@ -838,7 +948,7 @@ system and gives an overview of their function and contents.
838 Directory path when you run the script. If you run the script and do 948 Directory path when you run the script. If you run the script and do
839 not provide a Build Directory path, the ``BUILDDIR`` defaults to 949 not provide a Build Directory path, the ``BUILDDIR`` defaults to
840 ``build`` in the current directory. 950 ``build`` in the current directory.
841 951
842 BUILDHISTORY_COMMIT 952 BUILDHISTORY_COMMIT
843 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 953 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
844 class, this variable specifies whether or not to commit the build 954 class, this variable specifies whether or not to commit the build
@@ -848,60 +958,70 @@ system and gives an overview of their function and contents.
848 top-level subdirectory of the build history output (images, packages, 958 top-level subdirectory of the build history output (images, packages,
849 and sdk). If you want to track changes to build history over time, 959 and sdk). If you want to track changes to build history over time,
850 you should set this value to "1". 960 you should set this value to "1".
851 961
852 By default, the ``buildhistory`` class does not commit the build 962 By default, the ``buildhistory`` class does not commit the build
853 history output in a local Git repository: BUILDHISTORY_COMMIT ?= "0" 963 history output in a local Git repository:
854 964 ::
965
966 BUILDHISTORY_COMMIT ?= "0"
967
855 BUILDHISTORY_COMMIT_AUTHOR 968 BUILDHISTORY_COMMIT_AUTHOR
856 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 969 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
857 class, this variable specifies the author to use for each Git commit. 970 class, this variable specifies the author to use for each Git commit.
858 In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the 971 In order for the ``BUILDHISTORY_COMMIT_AUTHOR`` variable to work, the
859 :term:`BUILDHISTORY_COMMIT` variable must 972 :term:`BUILDHISTORY_COMMIT` variable must
860 be set to "1". 973 be set to "1".
861 974
862 Git requires that the value you provide for the 975 Git requires that the value you provide for the
863 ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name 976 ``BUILDHISTORY_COMMIT_AUTHOR`` variable takes the form of "name
864 email@host". Providing an email address or host that is not valid 977 email@host". Providing an email address or host that is not valid
865 does not produce an error. 978 does not produce an error.
866 979
867 By default, the ``buildhistory`` class sets the variable as follows: 980 By default, the ``buildhistory`` class sets the variable as follows:
868 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>" 981 ::
869 982
983 BUILDHISTORY_COMMIT_AUTHOR ?= "buildhistory <buildhistory@${DISTRO}>"
984
870 BUILDHISTORY_DIR 985 BUILDHISTORY_DIR
871 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 986 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
872 class, this variable specifies the directory in which build history 987 class, this variable specifies the directory in which build history
873 information is kept. For more information on how the variable works, 988 information is kept. For more information on how the variable works,
874 see the ``buildhistory.class``. 989 see the ``buildhistory.class``.
875 990
876 By default, the ``buildhistory`` class sets the directory as follows: 991 By default, the ``buildhistory`` class sets the directory as follows:
877 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory" 992 ::
878 993
994 BUILDHISTORY_DIR ?= "${TOPDIR}/buildhistory"
995
879 BUILDHISTORY_FEATURES 996 BUILDHISTORY_FEATURES
880 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 997 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
881 class, this variable specifies the build history features to be 998 class, this variable specifies the build history features to be
882 enabled. For more information on how build history works, see the 999 enabled. For more information on how build history works, see the
883 "`Maintaining Build Output 1000 ":ref:`dev-manual/dev-manual-common-tasks:maintaining build output quality`"
884 Quality <&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality>`__"
885 section in the Yocto Project Development Tasks Manual. 1001 section in the Yocto Project Development Tasks Manual.
886 1002
887 You can specify these features in the form of a space-separated list: 1003 You can specify these features in the form of a space-separated list:
888 1004
889 - *image:* Analysis of the contents of images, which includes the 1005 - *image:* Analysis of the contents of images, which includes the
890 list of installed packages among other things. 1006 list of installed packages among other things.
891 1007
892 - *package:* Analysis of the contents of individual packages. 1008 - *package:* Analysis of the contents of individual packages.
893 1009
894 - *sdk:* Analysis of the contents of the software development kit 1010 - *sdk:* Analysis of the contents of the software development kit
895 (SDK). 1011 (SDK).
896 1012
897 - *task:* Save output file signatures for `shared 1013 - *task:* Save output file signatures for
898 state <&YOCTO_DOCS_OM_URL;#shared-state-cache>`__ (sstate) tasks. 1014 :ref:`shared state <overview-manual/overview-manual-concepts:shared state cache>`
1015 (sstate) tasks.
899 This saves one file per task and lists the SHA-256 checksums for 1016 This saves one file per task and lists the SHA-256 checksums for
900 each file staged (i.e. the output of the task). 1017 each file staged (i.e. the output of the task).
901 1018
902 By default, the ``buildhistory`` class enables the following 1019 By default, the ``buildhistory`` class enables the following
903 features: BUILDHISTORY_FEATURES ?= "image package sdk" 1020 features:
904 1021 ::
1022
1023 BUILDHISTORY_FEATURES ?= "image package sdk"
1024
905 BUILDHISTORY_IMAGE_FILES 1025 BUILDHISTORY_IMAGE_FILES
906 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1026 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
907 class, this variable specifies a list of paths to files copied from 1027 class, this variable specifies a list of paths to files copied from
@@ -912,10 +1032,13 @@ system and gives an overview of their function and contents.
912 changes in user and group entries. You can modify the list to include 1032 changes in user and group entries. You can modify the list to include
913 any file. Specifying an invalid path does not produce an error. 1033 any file. Specifying an invalid path does not produce an error.
914 Consequently, you can include files that might not always be present. 1034 Consequently, you can include files that might not always be present.
915 1035
916 By default, the ``buildhistory`` class provides paths to the 1036 By default, the ``buildhistory`` class provides paths to the
917 following files: BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group" 1037 following files:
918 1038 ::
1039
1040 BUILDHISTORY_IMAGE_FILES ?= "/etc/passwd /etc/group"
1041
919 BUILDHISTORY_PUSH_REPO 1042 BUILDHISTORY_PUSH_REPO
920 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>` 1043 When inheriting the :ref:`buildhistory <ref-classes-buildhistory>`
921 class, this variable optionally specifies a remote repository to 1044 class, this variable optionally specifies a remote repository to
@@ -923,81 +1046,83 @@ system and gives an overview of their function and contents.
923 ``BUILDHISTORY_PUSH_REPO`` to work, 1046 ``BUILDHISTORY_PUSH_REPO`` to work,
924 :term:`BUILDHISTORY_COMMIT` must be set to 1047 :term:`BUILDHISTORY_COMMIT` must be set to
925 "1". 1048 "1".
926 1049
927 The repository should correspond to a remote address that specifies a 1050 The repository should correspond to a remote address that specifies a
928 repository as understood by Git, or alternatively to a remote name 1051 repository as understood by Git, or alternatively to a remote name
929 that you have set up manually using ``git remote`` within the local 1052 that you have set up manually using ``git remote`` within the local
930 repository. 1053 repository.
931 1054
932 By default, the ``buildhistory`` class sets the variable as follows: 1055 By default, the ``buildhistory`` class sets the variable as follows:
933 BUILDHISTORY_PUSH_REPO ?= "" 1056 ::
934 1057
1058 BUILDHISTORY_PUSH_REPO ?= ""
1059
935 BUILDSDK_CFLAGS 1060 BUILDSDK_CFLAGS
936 Specifies the flags to pass to the C compiler when building for the 1061 Specifies the flags to pass to the C compiler when building for the
937 SDK. When building in the ``nativesdk-`` context, 1062 SDK. When building in the ``nativesdk-`` context,
938 :term:`CFLAGS` is set to the value of this variable by 1063 :term:`CFLAGS` is set to the value of this variable by
939 default. 1064 default.
940 1065
941 BUILDSDK_CPPFLAGS 1066 BUILDSDK_CPPFLAGS
942 Specifies the flags to pass to the C pre-processor (i.e. to both the 1067 Specifies the flags to pass to the C pre-processor (i.e. to both the
943 C and the C++ compilers) when building for the SDK. When building in 1068 C and the C++ compilers) when building for the SDK. When building in
944 the ``nativesdk-`` context, :term:`CPPFLAGS` is set 1069 the ``nativesdk-`` context, :term:`CPPFLAGS` is set
945 to the value of this variable by default. 1070 to the value of this variable by default.
946 1071
947 BUILDSDK_CXXFLAGS 1072 BUILDSDK_CXXFLAGS
948 Specifies the flags to pass to the C++ compiler when building for the 1073 Specifies the flags to pass to the C++ compiler when building for the
949 SDK. When building in the ``nativesdk-`` context, 1074 SDK. When building in the ``nativesdk-`` context,
950 :term:`CXXFLAGS` is set to the value of this variable 1075 :term:`CXXFLAGS` is set to the value of this variable
951 by default. 1076 by default.
952 1077
953 BUILDSDK_LDFLAGS 1078 BUILDSDK_LDFLAGS
954 Specifies the flags to pass to the linker when building for the SDK. 1079 Specifies the flags to pass to the linker when building for the SDK.
955 When building in the ``nativesdk-`` context, 1080 When building in the ``nativesdk-`` context,
956 :term:`LDFLAGS` is set to the value of this variable 1081 :term:`LDFLAGS` is set to the value of this variable
957 by default. 1082 by default.
958 1083
959 BUILDSTATS_BASE 1084 BUILDSTATS_BASE
960 Points to the location of the directory that holds build statistics 1085 Points to the location of the directory that holds build statistics
961 when you use and enable the 1086 when you use and enable the
962 :ref:`buildstats <ref-classes-buildstats>` class. The 1087 :ref:`buildstats <ref-classes-buildstats>` class. The
963 ``BUILDSTATS_BASE`` directory defaults to 1088 ``BUILDSTATS_BASE`` directory defaults to
964 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``. 1089 ``${``\ :term:`TMPDIR`\ ``}/buildstats/``.
965 1090
966 BUSYBOX_SPLIT_SUID 1091 BUSYBOX_SPLIT_SUID
967 For the BusyBox recipe, specifies whether to split the output 1092 For the BusyBox recipe, specifies whether to split the output
968 executable file into two parts: one for features that require 1093 executable file into two parts: one for features that require
969 ``setuid root``, and one for the remaining features (i.e. those that 1094 ``setuid root``, and one for the remaining features (i.e. those that
970 do not require ``setuid root``). 1095 do not require ``setuid root``).
971 1096
972 The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in 1097 The ``BUSYBOX_SPLIT_SUID`` variable defaults to "1", which results in
973 splitting the output executable file. Set the variable to "0" to get 1098 splitting the output executable file. Set the variable to "0" to get
974 a single output executable file. 1099 a single output executable file.
975 1100
976 CACHE 1101 CACHE
977 Specifies the directory BitBake uses to store a cache of the 1102 Specifies the directory BitBake uses to store a cache of the
978 :term:`Metadata` so it does not need to be parsed every time 1103 :term:`Metadata` so it does not need to be parsed every time
979 BitBake is started. 1104 BitBake is started.
980 1105
981 CC 1106 CC
982 The minimal command and arguments used to run the C compiler. 1107 The minimal command and arguments used to run the C compiler.
983 1108
984 CFLAGS 1109 CFLAGS
985 Specifies the flags to pass to the C compiler. This variable is 1110 Specifies the flags to pass to the C compiler. This variable is
986 exported to an environment variable and thus made visible to the 1111 exported to an environment variable and thus made visible to the
987 software being built during the compilation step. 1112 software being built during the compilation step.
988 1113
989 Default initialization for ``CFLAGS`` varies depending on what is 1114 Default initialization for ``CFLAGS`` varies depending on what is
990 being built: 1115 being built:
991 1116
992 - :term:`TARGET_CFLAGS` when building for the 1117 - :term:`TARGET_CFLAGS` when building for the
993 target 1118 target
994 1119
995 - :term:`BUILD_CFLAGS` when building for the 1120 - :term:`BUILD_CFLAGS` when building for the
996 build host (i.e. ``-native``) 1121 build host (i.e. ``-native``)
997 1122
998 - :term:`BUILDSDK_CFLAGS` when building for 1123 - :term:`BUILDSDK_CFLAGS` when building for
999 an SDK (i.e. ``nativesdk-``) 1124 an SDK (i.e. ``nativesdk-``)
1000 1125
1001 CLASSOVERRIDE 1126 CLASSOVERRIDE
1002 An internal variable specifying the special class override that 1127 An internal variable specifying the special class override that
1003 should currently apply (e.g. "class-target", "class-native", and so 1128 should currently apply (e.g. "class-target", "class-native", and so
@@ -1005,31 +1130,41 @@ system and gives an overview of their function and contents.
1005 :ref:`native <ref-classes-native>`, 1130 :ref:`native <ref-classes-native>`,
1006 :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the 1131 :ref:`nativesdk <ref-classes-nativesdk>`, and so forth) set the
1007 variable to appropriate values. 1132 variable to appropriate values.
1008 1133
1009 .. note:: 1134 .. note::
1010 1135
1011 CLASSOVERRIDE 1136 CLASSOVERRIDE
1012 gets its default "class-target" value from the 1137 gets its default "class-target" value from the
1013 bitbake.conf 1138 bitbake.conf
1014 file. 1139 file.
1015 1140
1016 As an example, the following override allows you to install extra 1141 As an example, the following override allows you to install extra
1017 files, but only when building for the target: 1142 files, but only when building for the target:
1018 do_install_append_class-target() { install my-extra-file 1143 ::
1019 ${D}${sysconfdir} } Here is an example where ``FOO`` is set to 1144
1145 do_install_append_class-target() {
1146 install my-extra-file ${D}${sysconfdir}
1147 }
1148
1149 Here is an example where ``FOO`` is set to
1020 "native" when building for the build host, and to "other" when not 1150 "native" when building for the build host, and to "other" when not
1021 building for the build host: FOO_class-native = "native" FOO = 1151 building for the build host:
1022 "other" The underlying mechanism behind ``CLASSOVERRIDE`` is simply 1152 ::
1153
1154 FOO_class-native = "native"
1155 FOO = "other"
1156
1157 The underlying mechanism behind ``CLASSOVERRIDE`` is simply
1023 that it is included in the default value of 1158 that it is included in the default value of
1024 :term:`OVERRIDES`. 1159 :term:`OVERRIDES`.
1025 1160
1026 CLEANBROKEN 1161 CLEANBROKEN
1027 If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the 1162 If set to "1" within a recipe, ``CLEANBROKEN`` specifies that the
1028 ``make clean`` command does not work for the software being built. 1163 ``make clean`` command does not work for the software being built.
1029 Consequently, the OpenEmbedded build system will not try to run 1164 Consequently, the OpenEmbedded build system will not try to run
1030 ``make clean`` during the :ref:`ref-tasks-configure` 1165 ``make clean`` during the :ref:`ref-tasks-configure`
1031 task, which is the default behavior. 1166 task, which is the default behavior.
1032 1167
1033 COMBINED_FEATURES 1168 COMBINED_FEATURES
1034 Provides a list of hardware features that are enabled in both 1169 Provides a list of hardware features that are enabled in both
1035 :term:`MACHINE_FEATURES` and 1170 :term:`MACHINE_FEATURES` and
@@ -1039,12 +1174,12 @@ system and gives an overview of their function and contents.
1039 "bluetooth" feature requires hardware support but should also be 1174 "bluetooth" feature requires hardware support but should also be
1040 optional at the distribution level, in case the hardware supports 1175 optional at the distribution level, in case the hardware supports
1041 Bluetooth but you do not ever intend to use it. 1176 Bluetooth but you do not ever intend to use it.
1042 1177
1043 COMMON_LICENSE_DIR 1178 COMMON_LICENSE_DIR
1044 Points to ``meta/files/common-licenses`` in the 1179 Points to ``meta/files/common-licenses`` in the
1045 :term:`Source Directory`, which is where generic license 1180 :term:`Source Directory`, which is where generic license
1046 files reside. 1181 files reside.
1047 1182
1048 COMPATIBLE_HOST 1183 COMPATIBLE_HOST
1049 A regular expression that resolves to one or more hosts (when the 1184 A regular expression that resolves to one or more hosts (when the
1050 recipe is native) or one or more targets (when the recipe is 1185 recipe is native) or one or more targets (when the recipe is
@@ -1055,7 +1190,7 @@ system and gives an overview of their function and contents.
1055 particularly useful with kernels. The variable also helps to increase 1190 particularly useful with kernels. The variable also helps to increase
1056 parsing speed since the build system skips parsing recipes not 1191 parsing speed since the build system skips parsing recipes not
1057 compatible with the current system. 1192 compatible with the current system.
1058 1193
1059 COMPATIBLE_MACHINE 1194 COMPATIBLE_MACHINE
1060 A regular expression that resolves to one or more target machines 1195 A regular expression that resolves to one or more target machines
1061 with which a recipe is compatible. The regular expression is matched 1196 with which a recipe is compatible. The regular expression is matched
@@ -1065,14 +1200,14 @@ system and gives an overview of their function and contents.
1065 useful with kernels. The variable also helps to increase parsing 1200 useful with kernels. The variable also helps to increase parsing
1066 speed since the build system skips parsing recipes not compatible 1201 speed since the build system skips parsing recipes not compatible
1067 with the current machine. 1202 with the current machine.
1068 1203
1069 COMPLEMENTARY_GLOB 1204 COMPLEMENTARY_GLOB
1070 Defines wildcards to match when installing a list of complementary 1205 Defines wildcards to match when installing a list of complementary
1071 packages for all the packages explicitly (or implicitly) installed in 1206 packages for all the packages explicitly (or implicitly) installed in
1072 an image. 1207 an image.
1073 1208
1074 .. note:: 1209 .. note::
1075 1210
1076 The 1211 The
1077 COMPLEMENTARY_GLOB 1212 COMPLEMENTARY_GLOB
1078 variable uses Unix filename pattern matching ( 1213 variable uses Unix filename pattern matching (
@@ -1080,33 +1215,36 @@ system and gives an overview of their function and contents.
1080 ), which is similar to the Unix style pathname pattern expansion ( 1215 ), which is similar to the Unix style pathname pattern expansion (
1081 glob 1216 glob
1082 ). 1217 ).
1083 1218
1084 The resulting list of complementary packages is associated with an 1219 The resulting list of complementary packages is associated with an
1085 item that can be added to 1220 item that can be added to
1086 :term:`IMAGE_FEATURES`. An example usage of 1221 :term:`IMAGE_FEATURES`. An example usage of
1087 this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES`` 1222 this is the "dev-pkgs" item that when added to ``IMAGE_FEATURES``
1088 will install -dev packages (containing headers and other development 1223 will install -dev packages (containing headers and other development
1089 files) for every package in the image. 1224 files) for every package in the image.
1090 1225
1091 To add a new feature item pointing to a wildcard, use a variable flag 1226 To add a new feature item pointing to a wildcard, use a variable flag
1092 to specify the feature item name and use the value to specify the 1227 to specify the feature item name and use the value to specify the
1093 wildcard. Here is an example: COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev' 1228 wildcard. Here is an example:
1094 1229 ::
1230
1231 COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
1232
1095 COMPONENTS_DIR 1233 COMPONENTS_DIR
1096 Stores sysroot components for each recipe. The OpenEmbedded build 1234 Stores sysroot components for each recipe. The OpenEmbedded build
1097 system uses ``COMPONENTS_DIR`` when constructing recipe-specific 1235 system uses ``COMPONENTS_DIR`` when constructing recipe-specific
1098 sysroots for other recipes. 1236 sysroots for other recipes.
1099 1237
1100 The default is 1238 The default is
1101 "``${``\ :term:`STAGING_DIR`\ ``}-components``." 1239 "``${``\ :term:`STAGING_DIR`\ ``}-components``."
1102 (i.e. 1240 (i.e.
1103 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``"). 1241 "``${``\ :term:`TMPDIR`\ ``}/sysroots-components``").
1104 1242
1105 CONF_VERSION 1243 CONF_VERSION
1106 Tracks the version of the local configuration file (i.e. 1244 Tracks the version of the local configuration file (i.e.
1107 ``local.conf``). The value for ``CONF_VERSION`` increments each time 1245 ``local.conf``). The value for ``CONF_VERSION`` increments each time
1108 ``build/conf/`` compatibility changes. 1246 ``build/conf/`` compatibility changes.
1109 1247
1110 CONFFILES 1248 CONFFILES
1111 Identifies editable or configurable files that are part of a package. 1249 Identifies editable or configurable files that are part of a package.
1112 If the Package Management System (PMS) is being used to update 1250 If the Package Management System (PMS) is being used to update
@@ -1117,12 +1255,15 @@ system and gives an overview of their function and contents.
1117 as part of the package update process. You can use the ``CONFFILES`` 1255 as part of the package update process. You can use the ``CONFFILES``
1118 variable to list the files in the package that you wish to prevent 1256 variable to list the files in the package that you wish to prevent
1119 the PMS from overwriting during this update process. 1257 the PMS from overwriting during this update process.
1120 1258
1121 To use the ``CONFFILES`` variable, provide a package name override 1259 To use the ``CONFFILES`` variable, provide a package name override
1122 that identifies the resulting package. Then, provide a 1260 that identifies the resulting package. Then, provide a
1123 space-separated list of files. Here is an example: CONFFILES_${PN} += 1261 space-separated list of files. Here is an example:
1124 "${sysconfdir}/file1 \\ ${sysconfdir}/file2 ${sysconfdir}/file3" 1262 ::
1125 1263
1264 CONFFILES_${PN} += "${sysconfdir}/file1 \
1265 ${sysconfdir}/file2 ${sysconfdir}/file3"
1266
1126 A relationship exists between the ``CONFFILES`` and ``FILES`` 1267 A relationship exists between the ``CONFFILES`` and ``FILES``
1127 variables. The files listed within ``CONFFILES`` must be a subset of 1268 variables. The files listed within ``CONFFILES`` must be a subset of
1128 the files listed within ``FILES``. Because the configuration files 1269 the files listed within ``FILES``. Because the configuration files
@@ -1130,9 +1271,9 @@ system and gives an overview of their function and contents.
1130 the PMS will not overwrite them, it makes sense that the files must 1271 the PMS will not overwrite them, it makes sense that the files must
1131 already be included as part of the package through the ``FILES`` 1272 already be included as part of the package through the ``FILES``
1132 variable. 1273 variable.
1133 1274
1134 .. note:: 1275 .. note::
1135 1276
1136 When specifying paths as part of the 1277 When specifying paths as part of the
1137 CONFFILES 1278 CONFFILES
1138 variable, it is good practice to use appropriate path variables. 1279 variable, it is good practice to use appropriate path variables.
@@ -1149,13 +1290,13 @@ system and gives an overview of their function and contents.
1149 file in the 1290 file in the
1150 Source Directory 1291 Source Directory
1151 . 1292 .
1152 1293
1153 CONFIG_INITRAMFS_SOURCE 1294 CONFIG_INITRAMFS_SOURCE
1154 Identifies the initial RAM filesystem (initramfs) source files. The 1295 Identifies the initial RAM filesystem (initramfs) source files. The
1155 OpenEmbedded build system receives and uses this kernel Kconfig 1296 OpenEmbedded build system receives and uses this kernel Kconfig
1156 variable as an environment variable. By default, the variable is set 1297 variable as an environment variable. By default, the variable is set
1157 to null (""). 1298 to null ("").
1158 1299
1159 The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive 1300 The ``CONFIG_INITRAMFS_SOURCE`` can be either a single cpio archive
1160 with a ``.cpio`` suffix or a space-separated list of directories and 1301 with a ``.cpio`` suffix or a space-separated list of directories and
1161 files for building the initramfs image. A cpio archive should contain 1302 files for building the initramfs image. A cpio archive should contain
@@ -1163,23 +1304,22 @@ system and gives an overview of their function and contents.
1163 should contain a filesystem layout to be included in the initramfs 1304 should contain a filesystem layout to be included in the initramfs
1164 image. Files should contain entries according to the format described 1305 image. Files should contain entries according to the format described
1165 by the ``usr/gen_init_cpio`` program in the kernel tree. 1306 by the ``usr/gen_init_cpio`` program in the kernel tree.
1166 1307
1167 If you specify multiple directories and files, the initramfs image 1308 If you specify multiple directories and files, the initramfs image
1168 will be the aggregate of all of them. 1309 will be the aggregate of all of them.
1169 1310
1170 For information on creating an initramfs, see the "`Building an 1311 For information on creating an initramfs, see the
1171 Initial RAM Filesystem (initramfs) 1312 ":ref:`building-an-initramfs-image`" section
1172 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
1173 in the Yocto Project Development Tasks Manual. 1313 in the Yocto Project Development Tasks Manual.
1174 1314
1175 CONFIG_SITE 1315 CONFIG_SITE
1176 A list of files that contains ``autoconf`` test results relevant to 1316 A list of files that contains ``autoconf`` test results relevant to
1177 the current build. This variable is used by the Autotools utilities 1317 the current build. This variable is used by the Autotools utilities
1178 when running ``configure``. 1318 when running ``configure``.
1179 1319
1180 CONFIGURE_FLAGS 1320 CONFIGURE_FLAGS
1181 The minimal arguments for GNU configure. 1321 The minimal arguments for GNU configure.
1182 1322
1183 CONFLICT_DISTRO_FEATURES 1323 CONFLICT_DISTRO_FEATURES
1184 When inheriting the 1324 When inheriting the
1185 :ref:`distro_features_check <ref-classes-distro_features_check>` 1325 :ref:`distro_features_check <ref-classes-distro_features_check>`
@@ -1188,7 +1328,7 @@ system and gives an overview of their function and contents.
1188 ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also 1328 ``CONFLICT_DISTRO_FEATURES`` variable lists a feature that also
1189 appears in ``DISTRO_FEATURES`` within the current configuration, an 1329 appears in ``DISTRO_FEATURES`` within the current configuration, an
1190 error occurs and the build stops. 1330 error occurs and the build stops.
1191 1331
1192 COPYLEFT_LICENSE_EXCLUDE 1332 COPYLEFT_LICENSE_EXCLUDE
1193 A space-separated list of licenses to exclude from the source 1333 A space-separated list of licenses to exclude from the source
1194 archived by the :ref:`archiver <ref-classes-archiver>` class. In 1334 archived by the :ref:`archiver <ref-classes-archiver>` class. In
@@ -1196,32 +1336,32 @@ system and gives an overview of their function and contents.
1196 :term:`LICENSE` value is in the value of 1336 :term:`LICENSE` value is in the value of
1197 ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the 1337 ``COPYLEFT_LICENSE_EXCLUDE``, then its source is not archived by the
1198 class. 1338 class.
1199 1339
1200 .. note:: 1340 .. note::
1201 1341
1202 The 1342 The
1203 COPYLEFT_LICENSE_EXCLUDE 1343 COPYLEFT_LICENSE_EXCLUDE
1204 variable takes precedence over the 1344 variable takes precedence over the
1205 COPYLEFT_LICENSE_INCLUDE 1345 COPYLEFT_LICENSE_INCLUDE
1206 variable. 1346 variable.
1207 1347
1208 The default value, which is "CLOSED Proprietary", for 1348 The default value, which is "CLOSED Proprietary", for
1209 ``COPYLEFT_LICENSE_EXCLUDE`` is set by the 1349 ``COPYLEFT_LICENSE_EXCLUDE`` is set by the
1210 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which 1350 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1211 is inherited by the ``archiver`` class. 1351 is inherited by the ``archiver`` class.
1212 1352
1213 COPYLEFT_LICENSE_INCLUDE 1353 COPYLEFT_LICENSE_INCLUDE
1214 A space-separated list of licenses to include in the source archived 1354 A space-separated list of licenses to include in the source archived
1215 by the :ref:`archiver <ref-classes-archiver>` class. In other 1355 by the :ref:`archiver <ref-classes-archiver>` class. In other
1216 words, if a license in a recipe's :term:`LICENSE` 1356 words, if a license in a recipe's :term:`LICENSE`
1217 value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its 1357 value is in the value of ``COPYLEFT_LICENSE_INCLUDE``, then its
1218 source is archived by the class. 1358 source is archived by the class.
1219 1359
1220 The default value is set by the 1360 The default value is set by the
1221 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which 1361 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1222 is inherited by the ``archiver`` class. The default value includes 1362 is inherited by the ``archiver`` class. The default value includes
1223 "GPL*", "LGPL*", and "AGPL*". 1363 "GPL*", "LGPL*", and "AGPL*".
1224 1364
1225 COPYLEFT_PN_EXCLUDE 1365 COPYLEFT_PN_EXCLUDE
1226 A list of recipes to exclude in the source archived by the 1366 A list of recipes to exclude in the source archived by the
1227 :ref:`archiver <ref-classes-archiver>` class. The 1367 :ref:`archiver <ref-classes-archiver>` class. The
@@ -1230,12 +1370,12 @@ system and gives an overview of their function and contents.
1230 :term:`COPYLEFT_LICENSE_INCLUDE` and 1370 :term:`COPYLEFT_LICENSE_INCLUDE` and
1231 :term:`COPYLEFT_LICENSE_EXCLUDE` 1371 :term:`COPYLEFT_LICENSE_EXCLUDE`
1232 variables, respectively. 1372 variables, respectively.
1233 1373
1234 The default value, which is "" indicating to not explicitly exclude 1374 The default value, which is "" indicating to not explicitly exclude
1235 any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the 1375 any recipes by name, for ``COPYLEFT_PN_EXCLUDE`` is set by the
1236 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which 1376 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1237 is inherited by the ``archiver`` class. 1377 is inherited by the ``archiver`` class.
1238 1378
1239 COPYLEFT_PN_INCLUDE 1379 COPYLEFT_PN_INCLUDE
1240 A list of recipes to include in the source archived by the 1380 A list of recipes to include in the source archived by the
1241 :ref:`archiver <ref-classes-archiver>` class. The 1381 :ref:`archiver <ref-classes-archiver>` class. The
@@ -1244,22 +1384,22 @@ system and gives an overview of their function and contents.
1244 :term:`COPYLEFT_LICENSE_INCLUDE` and 1384 :term:`COPYLEFT_LICENSE_INCLUDE` and
1245 :term:`COPYLEFT_LICENSE_EXCLUDE` 1385 :term:`COPYLEFT_LICENSE_EXCLUDE`
1246 variables, respectively. 1386 variables, respectively.
1247 1387
1248 The default value, which is "" indicating to not explicitly include 1388 The default value, which is "" indicating to not explicitly include
1249 any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the 1389 any recipes by name, for ``COPYLEFT_PN_INCLUDE`` is set by the
1250 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which 1390 :ref:`copyleft_filter <ref-classes-copyleft_filter>` class, which
1251 is inherited by the ``archiver`` class. 1391 is inherited by the ``archiver`` class.
1252 1392
1253 COPYLEFT_RECIPE_TYPES 1393 COPYLEFT_RECIPE_TYPES
1254 A space-separated list of recipe types to include in the source 1394 A space-separated list of recipe types to include in the source
1255 archived by the :ref:`archiver <ref-classes-archiver>` class. 1395 archived by the :ref:`archiver <ref-classes-archiver>` class.
1256 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``, 1396 Recipe types are ``target``, ``native``, ``nativesdk``, ``cross``,
1257 ``crosssdk``, and ``cross-canadian``. 1397 ``crosssdk``, and ``cross-canadian``.
1258 1398
1259 The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES`` 1399 The default value, which is "target*", for ``COPYLEFT_RECIPE_TYPES``
1260 is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>` 1400 is set by the :ref:`copyleft_filter <ref-classes-copyleft_filter>`
1261 class, which is inherited by the ``archiver`` class. 1401 class, which is inherited by the ``archiver`` class.
1262 1402
1263 COPY_LIC_DIRS 1403 COPY_LIC_DIRS
1264 If set to "1" along with the 1404 If set to "1" along with the
1265 :term:`COPY_LIC_MANIFEST` variable, the 1405 :term:`COPY_LIC_MANIFEST` variable, the
@@ -1267,9 +1407,9 @@ system and gives an overview of their function and contents.
1267 which are located in ``/usr/share/common-licenses``, for each 1407 which are located in ``/usr/share/common-licenses``, for each
1268 package. The license files are placed in directories within the image 1408 package. The license files are placed in directories within the image
1269 itself during build time. 1409 itself during build time.
1270 1410
1271 .. note:: 1411 .. note::
1272 1412
1273 The 1413 The
1274 COPY_LIC_DIRS 1414 COPY_LIC_DIRS
1275 does not offer a path for adding licenses for newly installed 1415 does not offer a path for adding licenses for newly installed
@@ -1280,15 +1420,15 @@ system and gives an overview of their function and contents.
1280 Providing License Text 1420 Providing License Text
1281 " section in the Yocto Project Development Tasks Manual for 1421 " section in the Yocto Project Development Tasks Manual for
1282 information on providing license text. 1422 information on providing license text.
1283 1423
1284 COPY_LIC_MANIFEST 1424 COPY_LIC_MANIFEST
1285 If set to "1", the OpenEmbedded build system copies the license 1425 If set to "1", the OpenEmbedded build system copies the license
1286 manifest for the image to 1426 manifest for the image to
1287 ``/usr/share/common-licenses/license.manifest`` within the image 1427 ``/usr/share/common-licenses/license.manifest`` within the image
1288 itself during build time. 1428 itself during build time.
1289 1429
1290 .. note:: 1430 .. note::
1291 1431
1292 The 1432 The
1293 COPY_LIC_MANIFEST 1433 COPY_LIC_MANIFEST
1294 does not offer a path for adding licenses for newly installed 1434 does not offer a path for adding licenses for newly installed
@@ -1299,177 +1439,190 @@ system and gives an overview of their function and contents.
1299 Providing License Text 1439 Providing License Text
1300 " section in the Yocto Project Development Tasks Manual for 1440 " section in the Yocto Project Development Tasks Manual for
1301 information on providing license text. 1441 information on providing license text.
1302 1442
1303 CORE_IMAGE_EXTRA_INSTALL 1443 CORE_IMAGE_EXTRA_INSTALL
1304 Specifies the list of packages to be added to the image. You should 1444 Specifies the list of packages to be added to the image. You should
1305 only set this variable in the ``local.conf`` configuration file found 1445 only set this variable in the ``local.conf`` configuration file found
1306 in the :term:`Build Directory`. 1446 in the :term:`Build Directory`.
1307 1447
1308 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer 1448 This variable replaces ``POKY_EXTRA_INSTALL``, which is no longer
1309 supported. 1449 supported.
1310 1450
1311 COREBASE 1451 COREBASE
1312 Specifies the parent directory of the OpenEmbedded-Core Metadata 1452 Specifies the parent directory of the OpenEmbedded-Core Metadata
1313 layer (i.e. ``meta``). 1453 layer (i.e. ``meta``).
1314 1454
1315 It is an important distinction that ``COREBASE`` points to the parent 1455 It is an important distinction that ``COREBASE`` points to the parent
1316 of this layer and not the layer itself. Consider an example where you 1456 of this layer and not the layer itself. Consider an example where you
1317 have cloned the Poky Git repository and retained the ``poky`` name 1457 have cloned the Poky Git repository and retained the ``poky`` name
1318 for your local copy of the repository. In this case, ``COREBASE`` 1458 for your local copy of the repository. In this case, ``COREBASE``
1319 points to the ``poky`` folder because it is the parent directory of 1459 points to the ``poky`` folder because it is the parent directory of
1320 the ``poky/meta`` layer. 1460 the ``poky/meta`` layer.
1321 1461
1322 COREBASE_FILES 1462 COREBASE_FILES
1323 Lists files from the :term:`COREBASE` directory that 1463 Lists files from the :term:`COREBASE` directory that
1324 should be copied other than the layers listed in the 1464 should be copied other than the layers listed in the
1325 ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for 1465 ``bblayers.conf`` file. The ``COREBASE_FILES`` variable exists for
1326 the purpose of copying metadata from the OpenEmbedded build system 1466 the purpose of copying metadata from the OpenEmbedded build system
1327 into the extensible SDK. 1467 into the extensible SDK.
1328 1468
1329 Explicitly listing files in ``COREBASE`` is needed because it 1469 Explicitly listing files in ``COREBASE`` is needed because it
1330 typically contains build directories and other files that should not 1470 typically contains build directories and other files that should not
1331 normally be copied into the extensible SDK. Consequently, the value 1471 normally be copied into the extensible SDK. Consequently, the value
1332 of ``COREBASE_FILES`` is used in order to only copy the files that 1472 of ``COREBASE_FILES`` is used in order to only copy the files that
1333 are actually needed. 1473 are actually needed.
1334 1474
1335 CPP 1475 CPP
1336 The minimal command and arguments used to run the C preprocessor. 1476 The minimal command and arguments used to run the C preprocessor.
1337 1477
1338 CPPFLAGS 1478 CPPFLAGS
1339 Specifies the flags to pass to the C pre-processor (i.e. to both the 1479 Specifies the flags to pass to the C pre-processor (i.e. to both the
1340 C and the C++ compilers). This variable is exported to an environment 1480 C and the C++ compilers). This variable is exported to an environment
1341 variable and thus made visible to the software being built during the 1481 variable and thus made visible to the software being built during the
1342 compilation step. 1482 compilation step.
1343 1483
1344 Default initialization for ``CPPFLAGS`` varies depending on what is 1484 Default initialization for ``CPPFLAGS`` varies depending on what is
1345 being built: 1485 being built:
1346 1486
1347 - :term:`TARGET_CPPFLAGS` when building for 1487 - :term:`TARGET_CPPFLAGS` when building for
1348 the target 1488 the target
1349 1489
1350 - :term:`BUILD_CPPFLAGS` when building for the 1490 - :term:`BUILD_CPPFLAGS` when building for the
1351 build host (i.e. ``-native``) 1491 build host (i.e. ``-native``)
1352 1492
1353 - :term:`BUILDSDK_CPPFLAGS` when building 1493 - :term:`BUILDSDK_CPPFLAGS` when building
1354 for an SDK (i.e. ``nativesdk-``) 1494 for an SDK (i.e. ``nativesdk-``)
1355 1495
1356 CROSS_COMPILE 1496 CROSS_COMPILE
1357 The toolchain binary prefix for the target tools. The 1497 The toolchain binary prefix for the target tools. The
1358 ``CROSS_COMPILE`` variable is the same as the 1498 ``CROSS_COMPILE`` variable is the same as the
1359 :term:`TARGET_PREFIX` variable. 1499 :term:`TARGET_PREFIX` variable.
1360 1500
1361 .. note:: 1501 .. note::
1362 1502
1363 The OpenEmbedded build system sets the 1503 The OpenEmbedded build system sets the
1364 CROSS_COMPILE 1504 CROSS_COMPILE
1365 variable only in certain contexts (e.g. when building for kernel 1505 variable only in certain contexts (e.g. when building for kernel
1366 and kernel module recipes). 1506 and kernel module recipes).
1367 1507
1368 CVSDIR 1508 CVSDIR
1369 The directory in which files checked out under the CVS system are 1509 The directory in which files checked out under the CVS system are
1370 stored. 1510 stored.
1371 1511
1372 CXX 1512 CXX
1373 The minimal command and arguments used to run the C++ compiler. 1513 The minimal command and arguments used to run the C++ compiler.
1374 1514
1375 CXXFLAGS 1515 CXXFLAGS
1376 Specifies the flags to pass to the C++ compiler. This variable is 1516 Specifies the flags to pass to the C++ compiler. This variable is
1377 exported to an environment variable and thus made visible to the 1517 exported to an environment variable and thus made visible to the
1378 software being built during the compilation step. 1518 software being built during the compilation step.
1379 1519
1380 Default initialization for ``CXXFLAGS`` varies depending on what is 1520 Default initialization for ``CXXFLAGS`` varies depending on what is
1381 being built: 1521 being built:
1382 1522
1383 - :term:`TARGET_CXXFLAGS` when building for 1523 - :term:`TARGET_CXXFLAGS` when building for
1384 the target 1524 the target
1385 1525
1386 - :term:`BUILD_CXXFLAGS` when building for the 1526 - :term:`BUILD_CXXFLAGS` when building for the
1387 build host (i.e. ``-native``) 1527 build host (i.e. ``-native``)
1388 1528
1389 - :term:`BUILDSDK_CXXFLAGS` when building 1529 - :term:`BUILDSDK_CXXFLAGS` when building
1390 for an SDK (i.e. ``nativesdk-``) 1530 for an SDK (i.e. ``nativesdk-``)
1391 1531
1392 D 1532 D
1393 The destination directory. The location in the :term:`Build Directory` 1533 The destination directory. The location in the :term:`Build Directory`
1394 where components are installed by the 1534 where components are installed by the
1395 :ref:`ref-tasks-install` task. This location defaults 1535 :ref:`ref-tasks-install` task. This location defaults
1396 to: ${WORKDIR}/image 1536 to:
1397 1537 ::
1538
1539 ${WORKDIR}/image
1540
1398 .. note:: 1541 .. note::
1399 1542
1400 Tasks that read from or write to this directory should run under 1543 Tasks that read from or write to this directory should run under
1401 fakeroot 1544 fakeroot
1402 . 1545 .
1403 1546
1404 DATE 1547 DATE
1405 The date the build was started. Dates appear using the year, month, 1548 The date the build was started. Dates appear using the year, month,
1406 and day (YMD) format (e.g. "20150209" for February 9th, 2015). 1549 and day (YMD) format (e.g. "20150209" for February 9th, 2015).
1407 1550
1408 DATETIME 1551 DATETIME
1409 The date and time on which the current build started. The format is 1552 The date and time on which the current build started. The format is
1410 suitable for timestamps. 1553 suitable for timestamps.
1411 1554
1412 DEBIAN_NOAUTONAME 1555 DEBIAN_NOAUTONAME
1413 When the :ref:`debian <ref-classes-debian>` class is inherited, 1556 When the :ref:`debian <ref-classes-debian>` class is inherited,
1414 which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a 1557 which is the default behavior, ``DEBIAN_NOAUTONAME`` specifies a
1415 particular package should not be renamed according to Debian library 1558 particular package should not be renamed according to Debian library
1416 package naming. You must use the package name as an override when you 1559 package naming. You must use the package name as an override when you
1417 set this variable. Here is an example from the ``fontconfig`` recipe: 1560 set this variable. Here is an example from the ``fontconfig`` recipe:
1418 DEBIAN_NOAUTONAME_fontconfig-utils = "1" 1561 ::
1419 1562
1563 DEBIAN_NOAUTONAME_fontconfig-utils = "1"
1564
1420 DEBIANNAME 1565 DEBIANNAME
1421 When the :ref:`debian <ref-classes-debian>` class is inherited, 1566 When the :ref:`debian <ref-classes-debian>` class is inherited,
1422 which is the default behavior, ``DEBIANNAME`` allows you to override 1567 which is the default behavior, ``DEBIANNAME`` allows you to override
1423 the library name for an individual package. Overriding the library 1568 the library name for an individual package. Overriding the library
1424 name in these cases is rare. You must use the package name as an 1569 name in these cases is rare. You must use the package name as an
1425 override when you set this variable. Here is an example from the 1570 override when you set this variable. Here is an example from the
1426 ``dbus`` recipe: DEBIANNAME_${PN} = "dbus-1" 1571 ``dbus`` recipe:
1427 1572 ::
1573
1574 DEBIANNAME_${PN} = "dbus-1"
1575
1428 DEBUG_BUILD 1576 DEBUG_BUILD
1429 Specifies to build packages with debugging information. This 1577 Specifies to build packages with debugging information. This
1430 influences the value of the ``SELECTED_OPTIMIZATION`` variable. 1578 influences the value of the ``SELECTED_OPTIMIZATION`` variable.
1431 1579
1432 DEBUG_OPTIMIZATION 1580 DEBUG_OPTIMIZATION
1433 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when 1581 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when
1434 compiling a system for debugging. This variable defaults to "-O 1582 compiling a system for debugging. This variable defaults to "-O
1435 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe". 1583 -fno-omit-frame-pointer ${DEBUG_FLAGS} -pipe".
1436 1584
1437 DEFAULT_PREFERENCE 1585 DEFAULT_PREFERENCE
1438 Specifies a weak bias for recipe selection priority. 1586 Specifies a weak bias for recipe selection priority.
1439 1587
1440 The most common usage of this is variable is to set it to "-1" within 1588 The most common usage of this is variable is to set it to "-1" within
1441 a recipe for a development version of a piece of software. Using the 1589 a recipe for a development version of a piece of software. Using the
1442 variable in this way causes the stable version of the recipe to build 1590 variable in this way causes the stable version of the recipe to build
1443 by default in the absence of ``PREFERRED_VERSION`` being used to 1591 by default in the absence of ``PREFERRED_VERSION`` being used to
1444 build the development version. 1592 build the development version.
1445 1593
1446 .. note:: 1594 .. note::
1447 1595
1448 The bias provided by 1596 The bias provided by
1449 DEFAULT_PREFERENCE 1597 DEFAULT_PREFERENCE
1450 is weak and is overridden by 1598 is weak and is overridden by
1451 BBFILE_PRIORITY 1599 BBFILE_PRIORITY
1452 if that variable is different between two layers that contain 1600 if that variable is different between two layers that contain
1453 different versions of the same recipe. 1601 different versions of the same recipe.
1454 1602
1455 DEFAULTTUNE 1603 DEFAULTTUNE
1456 The default CPU and Application Binary Interface (ABI) tunings (i.e. 1604 The default CPU and Application Binary Interface (ABI) tunings (i.e.
1457 the "tune") used by the OpenEmbedded build system. The 1605 the "tune") used by the OpenEmbedded build system. The
1458 ``DEFAULTTUNE`` helps define 1606 ``DEFAULTTUNE`` helps define
1459 :term:`TUNE_FEATURES`. 1607 :term:`TUNE_FEATURES`.
1460 1608
1461 The default tune is either implicitly or explicitly set by the 1609 The default tune is either implicitly or explicitly set by the
1462 machine (:term:`MACHINE`). However, you can override 1610 machine (:term:`MACHINE`). However, you can override
1463 the setting using available tunes as defined with 1611 the setting using available tunes as defined with
1464 :term:`AVAILTUNES`. 1612 :term:`AVAILTUNES`.
1465 1613
1466 DEPENDS 1614 DEPENDS
1467 Lists a recipe's build-time dependencies. These are dependencies on 1615 Lists a recipe's build-time dependencies. These are dependencies on
1468 other recipes whose contents (e.g. headers and shared libraries) are 1616 other recipes whose contents (e.g. headers and shared libraries) are
1469 needed by the recipe at build time. 1617 needed by the recipe at build time.
1470 1618
1471 As an example, consider a recipe ``foo`` that contains the following 1619 As an example, consider a recipe ``foo`` that contains the following
1472 assignment: DEPENDS = "bar" The practical effect of the previous 1620 assignment:
1621 ::
1622
1623 DEPENDS = "bar"
1624
1625 The practical effect of the previous
1473 assignment is that all files installed by bar will be available in 1626 assignment is that all files installed by bar will be available in
1474 the appropriate staging sysroot, given by the 1627 the appropriate staging sysroot, given by the
1475 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the 1628 :term:`STAGING_DIR* <STAGING_DIR>` variables, by the time the
@@ -1479,23 +1632,28 @@ system and gives an overview of their function and contents.
1479 each recipe listed in ``DEPENDS``, through a 1632 each recipe listed in ``DEPENDS``, through a
1480 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]`` 1633 ``[``\ :ref:`deptask <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:variable flags>`\ ``]``
1481 declaration in the :ref:`base <ref-classes-base>` class. 1634 declaration in the :ref:`base <ref-classes-base>` class.
1482 1635
1483 .. note:: 1636 .. note::
1484 1637
1485 It seldom is necessary to reference, for example, 1638 It seldom is necessary to reference, for example,
1486 STAGING_DIR_HOST 1639 STAGING_DIR_HOST
1487 explicitly. The standard classes and build-related variables are 1640 explicitly. The standard classes and build-related variables are
1488 configured to automatically use the appropriate staging sysroots. 1641 configured to automatically use the appropriate staging sysroots.
1489 1642
1490 As another example, ``DEPENDS`` can also be used to add utilities 1643 As another example, ``DEPENDS`` can also be used to add utilities
1491 that run on the build machine during the build. For example, a recipe 1644 that run on the build machine during the build. For example, a recipe
1492 that makes use of a code generator built by the recipe ``codegen`` 1645 that makes use of a code generator built by the recipe ``codegen``
1493 might have the following: DEPENDS = "codegen-native" For more 1646 might have the following:
1647 ::
1648
1649 DEPENDS = "codegen-native"
1650
1651 For more
1494 information, see the :ref:`native <ref-classes-native>` class and 1652 information, see the :ref:`native <ref-classes-native>` class and
1495 the :term:`EXTRANATIVEPATH` variable. 1653 the :term:`EXTRANATIVEPATH` variable.
1496 1654
1497 .. note:: 1655 .. note::
1498 1656
1499 - ``DEPENDS`` is a list of recipe names. Or, to be more precise, 1657 - ``DEPENDS`` is a list of recipe names. Or, to be more precise,
1500 it is a list of :term:`PROVIDES` names, which 1658 it is a list of :term:`PROVIDES` names, which
1501 usually match recipe names. Putting a package name such as 1659 usually match recipe names. Putting a package name such as
@@ -1503,16 +1661,15 @@ system and gives an overview of their function and contents.
1503 instead, as this will put files from all the packages that make 1661 instead, as this will put files from all the packages that make
1504 up ``foo``, which includes those from ``foo-dev``, into the 1662 up ``foo``, which includes those from ``foo-dev``, into the
1505 sysroot. 1663 sysroot.
1506 1664
1507 - One recipe having another recipe in ``DEPENDS`` does not by 1665 - One recipe having another recipe in ``DEPENDS`` does not by
1508 itself add any runtime dependencies between the packages 1666 itself add any runtime dependencies between the packages
1509 produced by the two recipes. However, as explained in the 1667 produced by the two recipes. However, as explained in the
1510 "`Automatically Added Runtime 1668 ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
1511 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__"
1512 section in the Yocto Project Overview and Concepts Manual, 1669 section in the Yocto Project Overview and Concepts Manual,
1513 runtime dependencies will often be added automatically, meaning 1670 runtime dependencies will often be added automatically, meaning
1514 ``DEPENDS`` alone is sufficient for most recipes. 1671 ``DEPENDS`` alone is sufficient for most recipes.
1515 1672
1516 - Counterintuitively, ``DEPENDS`` is often necessary even for 1673 - Counterintuitively, ``DEPENDS`` is often necessary even for
1517 recipes that install precompiled components. For example, if 1674 recipes that install precompiled components. For example, if
1518 ``libfoo`` is a precompiled library that links against 1675 ``libfoo`` is a precompiled library that links against
@@ -1521,50 +1678,51 @@ system and gives an overview of their function and contents.
1521 Without a ``DEPENDS`` from the recipe that installs ``libfoo`` 1678 Without a ``DEPENDS`` from the recipe that installs ``libfoo``
1522 to the recipe that installs ``libbar``, other recipes might 1679 to the recipe that installs ``libbar``, other recipes might
1523 fail to link against ``libfoo``. 1680 fail to link against ``libfoo``.
1524 1681
1525 For information on runtime dependencies, see the 1682 For information on runtime dependencies, see the
1526 :term:`RDEPENDS` variable. You can also see the 1683 :term:`RDEPENDS` variable. You can also see the
1527 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and 1684 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and
1528 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the 1685 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the
1529 BitBake User Manual for additional information on tasks and 1686 BitBake User Manual for additional information on tasks and
1530 dependencies. 1687 dependencies.
1531 1688
1532 DEPLOY_DIR 1689 DEPLOY_DIR
1533 Points to the general area that the OpenEmbedded build system uses to 1690 Points to the general area that the OpenEmbedded build system uses to
1534 place images, packages, SDKs, and other output files that are ready 1691 place images, packages, SDKs, and other output files that are ready
1535 to be used outside of the build system. By default, this directory 1692 to be used outside of the build system. By default, this directory
1536 resides within the :term:`Build Directory` as 1693 resides within the :term:`Build Directory` as
1537 ``${TMPDIR}/deploy``. 1694 ``${TMPDIR}/deploy``.
1538 1695
1539 For more information on the structure of the Build Directory, see 1696 For more information on the structure of the Build Directory, see
1540 "`The Build Directory - ``build/`` <#structure-build>`__" section. 1697 ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section.
1541 For more detail on the contents of the ``deploy`` directory, see the 1698 For more detail on the contents of the ``deploy`` directory, see the
1542 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__", "`Package 1699 ":ref:`Images <images-dev-environment>`", ":ref:`Package
1543 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__", and 1700 Feeds <package-feeds-dev-environment>`", and
1544 "`Application Development 1701 ":ref:`sdk-dev-environment`" sections all in the
1545 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections all in the
1546 Yocto Project Overview and Concepts Manual. 1702 Yocto Project Overview and Concepts Manual.
1547 1703
1548 DEPLOY_DIR_DEB 1704 DEPLOY_DIR_DEB
1549 Points to the area that the OpenEmbedded build system uses to place 1705 Points to the area that the OpenEmbedded build system uses to place
1550 Debian packages that are ready to be used outside of the build 1706 Debian packages that are ready to be used outside of the build
1551 system. This variable applies only when 1707 system. This variable applies only when
1552 :term:`PACKAGE_CLASSES` contains 1708 :term:`PACKAGE_CLASSES` contains
1553 "package_deb". 1709 "package_deb".
1554 1710
1555 The BitBake configuration file initially defines the 1711 The BitBake configuration file initially defines the
1556 ``DEPLOY_DIR_DEB`` variable as a sub-folder of 1712 ``DEPLOY_DIR_DEB`` variable as a sub-folder of
1557 :term:`DEPLOY_DIR`: DEPLOY_DIR_DEB = 1713 :term:`DEPLOY_DIR`:
1558 "${DEPLOY_DIR}/deb" 1714 ::
1559 1715
1716 DEPLOY_DIR_DEB = "${DEPLOY_DIR}/deb"
1717
1560 The :ref:`package_deb <ref-classes-package_deb>` class uses the 1718 The :ref:`package_deb <ref-classes-package_deb>` class uses the
1561 ``DEPLOY_DIR_DEB`` variable to make sure the 1719 ``DEPLOY_DIR_DEB`` variable to make sure the
1562 :ref:`ref-tasks-package_write_deb` task 1720 :ref:`ref-tasks-package_write_deb` task
1563 writes Debian packages into the appropriate folder. For more 1721 writes Debian packages into the appropriate folder. For more
1564 information on how packaging works, see the "`Package 1722 information on how packaging works, see the ":ref:`Package
1565 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1723 Feeds <package-feeds-dev-environment>`" section
1566 in the Yocto Project Overview and Concepts Manual. 1724 in the Yocto Project Overview and Concepts Manual.
1567 1725
1568 DEPLOY_DIR_IMAGE 1726 DEPLOY_DIR_IMAGE
1569 Points to the area that the OpenEmbedded build system uses to place 1727 Points to the area that the OpenEmbedded build system uses to place
1570 images and other associated output files that are ready to be 1728 images and other associated output files that are ready to be
@@ -1572,120 +1730,130 @@ system and gives an overview of their function and contents.
1572 as it contains the ``${MACHINE}`` name. By default, this directory 1730 as it contains the ``${MACHINE}`` name. By default, this directory
1573 resides within the :term:`Build Directory` as 1731 resides within the :term:`Build Directory` as
1574 ``${DEPLOY_DIR}/images/${MACHINE}/``. 1732 ``${DEPLOY_DIR}/images/${MACHINE}/``.
1575 1733
1576 For more information on the structure of the Build Directory, see 1734 For more information on the structure of the Build Directory, see
1577 "`The Build Directory - ``build/`` <#structure-build>`__" section. 1735 ":ref:`ref-manual/ref-structure:the build directory - \`\`build/\`\``" section.
1578 For more detail on the contents of the ``deploy`` directory, see the 1736 For more detail on the contents of the ``deploy`` directory, see the
1579 "`Images <&YOCTO_DOCS_OM_URL;#images-dev-environment>`__" and 1737 ":ref:`Images <images-dev-environment>`" and
1580 "`Application Development 1738 ":ref:`sdk-dev-environment`" sections both in
1581 SDK <&YOCTO_DOCS_OM_URL;#sdk-dev-environment>`__" sections both in
1582 the Yocto Project Overview and Concepts Manual. 1739 the Yocto Project Overview and Concepts Manual.
1583 1740
1584 DEPLOY_DIR_IPK 1741 DEPLOY_DIR_IPK
1585 Points to the area that the OpenEmbedded build system uses to place 1742 Points to the area that the OpenEmbedded build system uses to place
1586 IPK packages that are ready to be used outside of the build system. 1743 IPK packages that are ready to be used outside of the build system.
1587 This variable applies only when 1744 This variable applies only when
1588 :term:`PACKAGE_CLASSES` contains 1745 :term:`PACKAGE_CLASSES` contains
1589 "package_ipk". 1746 "package_ipk".
1590 1747
1591 The BitBake configuration file initially defines this variable as a 1748 The BitBake configuration file initially defines this variable as a
1592 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_IPK = 1749 sub-folder of :term:`DEPLOY_DIR`:
1593 "${DEPLOY_DIR}/ipk" 1750 ::
1594 1751
1752 DEPLOY_DIR_IPK = "${DEPLOY_DIR}/ipk"
1753
1595 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the 1754 The :ref:`package_ipk <ref-classes-package_ipk>` class uses the
1596 ``DEPLOY_DIR_IPK`` variable to make sure the 1755 ``DEPLOY_DIR_IPK`` variable to make sure the
1597 :ref:`ref-tasks-package_write_ipk` task 1756 :ref:`ref-tasks-package_write_ipk` task
1598 writes IPK packages into the appropriate folder. For more information 1757 writes IPK packages into the appropriate folder. For more information
1599 on how packaging works, see the "`Package 1758 on how packaging works, see the ":ref:`Package
1600 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1759 Feeds <package-feeds-dev-environment>`" section
1601 in the Yocto Project Overview and Concepts Manual. 1760 in the Yocto Project Overview and Concepts Manual.
1602 1761
1603 DEPLOY_DIR_RPM 1762 DEPLOY_DIR_RPM
1604 Points to the area that the OpenEmbedded build system uses to place 1763 Points to the area that the OpenEmbedded build system uses to place
1605 RPM packages that are ready to be used outside of the build system. 1764 RPM packages that are ready to be used outside of the build system.
1606 This variable applies only when 1765 This variable applies only when
1607 :term:`PACKAGE_CLASSES` contains 1766 :term:`PACKAGE_CLASSES` contains
1608 "package_rpm". 1767 "package_rpm".
1609 1768
1610 The BitBake configuration file initially defines this variable as a 1769 The BitBake configuration file initially defines this variable as a
1611 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_RPM = 1770 sub-folder of :term:`DEPLOY_DIR`:
1612 "${DEPLOY_DIR}/rpm" 1771 ::
1613 1772
1773 DEPLOY_DIR_RPM = "${DEPLOY_DIR}/rpm"
1774
1614 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the 1775 The :ref:`package_rpm <ref-classes-package_rpm>` class uses the
1615 ``DEPLOY_DIR_RPM`` variable to make sure the 1776 ``DEPLOY_DIR_RPM`` variable to make sure the
1616 :ref:`ref-tasks-package_write_rpm` task 1777 :ref:`ref-tasks-package_write_rpm` task
1617 writes RPM packages into the appropriate folder. For more information 1778 writes RPM packages into the appropriate folder. For more information
1618 on how packaging works, see the "`Package 1779 on how packaging works, see the ":ref:`Package
1619 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1780 Feeds <package-feeds-dev-environment>`" section
1620 in the Yocto Project Overview and Concepts Manual. 1781 in the Yocto Project Overview and Concepts Manual.
1621 1782
1622 DEPLOY_DIR_TAR 1783 DEPLOY_DIR_TAR
1623 Points to the area that the OpenEmbedded build system uses to place 1784 Points to the area that the OpenEmbedded build system uses to place
1624 tarballs that are ready to be used outside of the build system. This 1785 tarballs that are ready to be used outside of the build system. This
1625 variable applies only when 1786 variable applies only when
1626 :term:`PACKAGE_CLASSES` contains 1787 :term:`PACKAGE_CLASSES` contains
1627 "package_tar". 1788 "package_tar".
1628 1789
1629 The BitBake configuration file initially defines this variable as a 1790 The BitBake configuration file initially defines this variable as a
1630 sub-folder of :term:`DEPLOY_DIR`: DEPLOY_DIR_TAR = 1791 sub-folder of :term:`DEPLOY_DIR`:
1631 "${DEPLOY_DIR}/tar" 1792 ::
1632 1793
1794 DEPLOY_DIR_TAR = "${DEPLOY_DIR}/tar"
1795
1633 The :ref:`package_tar <ref-classes-package_tar>` class uses the 1796 The :ref:`package_tar <ref-classes-package_tar>` class uses the
1634 ``DEPLOY_DIR_TAR`` variable to make sure the 1797 ``DEPLOY_DIR_TAR`` variable to make sure the
1635 :ref:`ref-tasks-package_write_tar` task 1798 :ref:`ref-tasks-package_write_tar` task
1636 writes TAR packages into the appropriate folder. For more information 1799 writes TAR packages into the appropriate folder. For more information
1637 on how packaging works, see the "`Package 1800 on how packaging works, see the ":ref:`Package
1638 Feeds <&YOCTO_DOCS_OM_URL;#package-feeds-dev-environment>`__" section 1801 Feeds <package-feeds-dev-environment>`" section
1639 in the Yocto Project Overview and Concepts Manual. 1802 in the Yocto Project Overview and Concepts Manual.
1640 1803
1641 DEPLOYDIR 1804 DEPLOYDIR
1642 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the 1805 When inheriting the :ref:`deploy <ref-classes-deploy>` class, the
1643 ``DEPLOYDIR`` points to a temporary work area for deployed files that 1806 ``DEPLOYDIR`` points to a temporary work area for deployed files that
1644 is set in the ``deploy`` class as follows: DEPLOYDIR = 1807 is set in the ``deploy`` class as follows:
1645 "${WORKDIR}/deploy-${:term:`PN`}" 1808 ::
1646 1809
1810 DEPLOYDIR = "${WORKDIR}/deploy-${:term:`PN`}"
1811
1647 Recipes inheriting the ``deploy`` class should copy files to be 1812 Recipes inheriting the ``deploy`` class should copy files to be
1648 deployed into ``DEPLOYDIR``, and the class will take care of copying 1813 deployed into ``DEPLOYDIR``, and the class will take care of copying
1649 them into :term:`DEPLOY_DIR_IMAGE` 1814 them into :term:`DEPLOY_DIR_IMAGE`
1650 afterwards. 1815 afterwards.
1651 1816
1652 DESCRIPTION 1817 DESCRIPTION
1653 The package description used by package managers. If not set, 1818 The package description used by package managers. If not set,
1654 ``DESCRIPTION`` takes the value of the :term:`SUMMARY` 1819 ``DESCRIPTION`` takes the value of the :term:`SUMMARY`
1655 variable. 1820 variable.
1656 1821
1657 DISTRO 1822 DISTRO
1658 The short name of the distribution. For information on the long name 1823 The short name of the distribution. For information on the long name
1659 of the distribution, see the :term:`DISTRO_NAME` 1824 of the distribution, see the :term:`DISTRO_NAME`
1660 variable. 1825 variable.
1661 1826
1662 The ``DISTRO`` variable corresponds to a distribution configuration 1827 The ``DISTRO`` variable corresponds to a distribution configuration
1663 file whose root name is the same as the variable's argument and whose 1828 file whose root name is the same as the variable's argument and whose
1664 filename extension is ``.conf``. For example, the distribution 1829 filename extension is ``.conf``. For example, the distribution
1665 configuration file for the Poky distribution is named ``poky.conf`` 1830 configuration file for the Poky distribution is named ``poky.conf``
1666 and resides in the ``meta-poky/conf/distro`` directory of the 1831 and resides in the ``meta-poky/conf/distro`` directory of the
1667 :term:`Source Directory`. 1832 :term:`Source Directory`.
1668 1833
1669 Within that ``poky.conf`` file, the ``DISTRO`` variable is set as 1834 Within that ``poky.conf`` file, the ``DISTRO`` variable is set as
1670 follows: DISTRO = "poky" 1835 follows:
1671 1836 ::
1837
1838 DISTRO = "poky"
1839
1672 Distribution configuration files are located in a ``conf/distro`` 1840 Distribution configuration files are located in a ``conf/distro``
1673 directory within the :term:`Metadata` that contains the 1841 directory within the :term:`Metadata` that contains the
1674 distribution configuration. The value for ``DISTRO`` must not contain 1842 distribution configuration. The value for ``DISTRO`` must not contain
1675 spaces, and is typically all lower-case. 1843 spaces, and is typically all lower-case.
1676 1844
1677 .. note:: 1845 .. note::
1678 1846
1679 If the 1847 If the
1680 DISTRO 1848 DISTRO
1681 variable is blank, a set of default configurations are used, which 1849 variable is blank, a set of default configurations are used, which
1682 are specified within 1850 are specified within
1683 meta/conf/distro/defaultsetup.conf 1851 meta/conf/distro/defaultsetup.conf
1684 also in the Source Directory. 1852 also in the Source Directory.
1685 1853
1686 DISTRO_CODENAME 1854 DISTRO_CODENAME
1687 Specifies a codename for the distribution being built. 1855 Specifies a codename for the distribution being built.
1688 1856
1689 DISTRO_EXTRA_RDEPENDS 1857 DISTRO_EXTRA_RDEPENDS
1690 Specifies a list of distro-specific packages to add to all images. 1858 Specifies a list of distro-specific packages to add to all images.
1691 This variable takes affect through ``packagegroup-base`` so the 1859 This variable takes affect through ``packagegroup-base`` so the
@@ -1693,18 +1861,18 @@ system and gives an overview of their function and contents.
1693 include ``packagegroup-base``. You can use this variable to keep 1861 include ``packagegroup-base``. You can use this variable to keep
1694 distro policy out of generic images. As with all other distro 1862 distro policy out of generic images. As with all other distro
1695 variables, you set this variable in the distro ``.conf`` file. 1863 variables, you set this variable in the distro ``.conf`` file.
1696 1864
1697 DISTRO_EXTRA_RRECOMMENDS 1865 DISTRO_EXTRA_RRECOMMENDS
1698 Specifies a list of distro-specific packages to add to all images if 1866 Specifies a list of distro-specific packages to add to all images if
1699 the packages exist. The packages might not exist or be empty (e.g. 1867 the packages exist. The packages might not exist or be empty (e.g.
1700 kernel modules). The list of packages are automatically installed but 1868 kernel modules). The list of packages are automatically installed but
1701 you can remove them. 1869 you can remove them.
1702 1870
1703 DISTRO_FEATURES 1871 DISTRO_FEATURES
1704 The software support you want in your distribution for various 1872 The software support you want in your distribution for various
1705 features. You define your distribution features in the distribution 1873 features. You define your distribution features in the distribution
1706 configuration file. 1874 configuration file.
1707 1875
1708 In most cases, the presence or absence of a feature in 1876 In most cases, the presence or absence of a feature in
1709 ``DISTRO_FEATURES`` is translated to the appropriate option supplied 1877 ``DISTRO_FEATURES`` is translated to the appropriate option supplied
1710 to the configure script during the 1878 to the configure script during the
@@ -1713,41 +1881,43 @@ system and gives an overview of their function and contents.
1713 ``DISTRO_FEATURES``, causes every piece of software built for the 1881 ``DISTRO_FEATURES``, causes every piece of software built for the
1714 target that can optionally support X11 to have its X11 support 1882 target that can optionally support X11 to have its X11 support
1715 enabled. 1883 enabled.
1716 1884
1717 Two more examples are Bluetooth and NFS support. For a more complete 1885 Two more examples are Bluetooth and NFS support. For a more complete
1718 list of features that ships with the Yocto Project and that you can 1886 list of features that ships with the Yocto Project and that you can
1719 provide with this variable, see the "`Distro 1887 provide with this variable, see the "`Distro
1720 Features <#ref-features-distro>`__" section. 1888 Features <#ref-features-distro>`__" section.
1721 1889
1722 DISTRO_FEATURES_BACKFILL 1890 DISTRO_FEATURES_BACKFILL
1723 Features to be added to ``DISTRO_FEATURES`` if not also present in 1891 Features to be added to ``DISTRO_FEATURES`` if not also present in
1724 ``DISTRO_FEATURES_BACKFILL_CONSIDERED``. 1892 ``DISTRO_FEATURES_BACKFILL_CONSIDERED``.
1725 1893
1726 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 1894 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
1727 not intended to be user-configurable. It is best to just reference 1895 not intended to be user-configurable. It is best to just reference
1728 the variable to see which distro features are being backfilled for 1896 the variable to see which distro features are being backfilled for
1729 all distro configurations. See the "`Feature 1897 all distro configurations. See the "`Feature
1730 Backfilling <#ref-features-backfill>`__" section for more 1898 Backfilling <#ref-features-backfill>`__" section for more
1731 information. 1899 information.
1732 1900
1733 DISTRO_FEATURES_BACKFILL_CONSIDERED 1901 DISTRO_FEATURES_BACKFILL_CONSIDERED
1734 Features from ``DISTRO_FEATURES_BACKFILL`` that should not be 1902 Features from ``DISTRO_FEATURES_BACKFILL`` that should not be
1735 backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See 1903 backfilled (i.e. added to ``DISTRO_FEATURES``) during the build. See
1736 the "`Feature Backfilling <#ref-features-backfill>`__" section for 1904 the "`Feature Backfilling <#ref-features-backfill>`__" section for
1737 more information. 1905 more information.
1738 1906
1739 DISTRO_FEATURES_DEFAULT 1907 DISTRO_FEATURES_DEFAULT
1740 A convenience variable that gives you the default list of distro 1908 A convenience variable that gives you the default list of distro
1741 features with the exception of any features specific to the C library 1909 features with the exception of any features specific to the C library
1742 (``libc``). 1910 (``libc``).
1743 1911
1744 When creating a custom distribution, you might find it useful to be 1912 When creating a custom distribution, you might find it useful to be
1745 able to reuse the default 1913 able to reuse the default
1746 :term:`DISTRO_FEATURES` options without the 1914 :term:`DISTRO_FEATURES` options without the
1747 need to write out the full set. Here is an example that uses 1915 need to write out the full set. Here is an example that uses
1748 ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file: 1916 ``DISTRO_FEATURES_DEFAULT`` from a custom distro configuration file:
1749 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature" 1917 ::
1750 1918
1919 DISTRO_FEATURES ?= "${DISTRO_FEATURES_DEFAULT} myfeature"
1920
1751 DISTRO_FEATURES_FILTER_NATIVE 1921 DISTRO_FEATURES_FILTER_NATIVE
1752 Specifies a list of features that if present in the target 1922 Specifies a list of features that if present in the target
1753 :term:`DISTRO_FEATURES` value should be 1923 :term:`DISTRO_FEATURES` value should be
@@ -1755,7 +1925,7 @@ system and gives an overview of their function and contents.
1755 variable is used in addition to the features filtered using the 1925 variable is used in addition to the features filtered using the
1756 :term:`DISTRO_FEATURES_NATIVE` 1926 :term:`DISTRO_FEATURES_NATIVE`
1757 variable. 1927 variable.
1758 1928
1759 DISTRO_FEATURES_FILTER_NATIVESDK 1929 DISTRO_FEATURES_FILTER_NATIVESDK
1760 Specifies a list of features that if present in the target 1930 Specifies a list of features that if present in the target
1761 :term:`DISTRO_FEATURES` value should be 1931 :term:`DISTRO_FEATURES` value should be
@@ -1763,7 +1933,7 @@ system and gives an overview of their function and contents.
1763 variable is used in addition to the features filtered using the 1933 variable is used in addition to the features filtered using the
1764 :term:`DISTRO_FEATURES_NATIVESDK` 1934 :term:`DISTRO_FEATURES_NATIVESDK`
1765 variable. 1935 variable.
1766 1936
1767 DISTRO_FEATURES_NATIVE 1937 DISTRO_FEATURES_NATIVE
1768 Specifies a list of features that should be included in 1938 Specifies a list of features that should be included in
1769 :term:`DISTRO_FEATURES` when building native 1939 :term:`DISTRO_FEATURES` when building native
@@ -1771,7 +1941,7 @@ system and gives an overview of their function and contents.
1771 using the 1941 using the
1772 :term:`DISTRO_FEATURES_FILTER_NATIVE` 1942 :term:`DISTRO_FEATURES_FILTER_NATIVE`
1773 variable. 1943 variable.
1774 1944
1775 DISTRO_FEATURES_NATIVESDK 1945 DISTRO_FEATURES_NATIVESDK
1776 Specifies a list of features that should be included in 1946 Specifies a list of features that should be included in
1777 :term:`DISTRO_FEATURES` when building 1947 :term:`DISTRO_FEATURES` when building
@@ -1779,49 +1949,52 @@ system and gives an overview of their function and contents.
1779 filtered using the 1949 filtered using the
1780 :term:`DISTRO_FEATURES_FILTER_NATIVESDK` 1950 :term:`DISTRO_FEATURES_FILTER_NATIVESDK`
1781 variable. 1951 variable.
1782 1952
1783 DISTRO_NAME 1953 DISTRO_NAME
1784 The long name of the distribution. For information on the short name 1954 The long name of the distribution. For information on the short name
1785 of the distribution, see the :term:`DISTRO` variable. 1955 of the distribution, see the :term:`DISTRO` variable.
1786 1956
1787 The ``DISTRO_NAME`` variable corresponds to a distribution 1957 The ``DISTRO_NAME`` variable corresponds to a distribution
1788 configuration file whose root name is the same as the variable's 1958 configuration file whose root name is the same as the variable's
1789 argument and whose filename extension is ``.conf``. For example, the 1959 argument and whose filename extension is ``.conf``. For example, the
1790 distribution configuration file for the Poky distribution is named 1960 distribution configuration file for the Poky distribution is named
1791 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory 1961 ``poky.conf`` and resides in the ``meta-poky/conf/distro`` directory
1792 of the :term:`Source Directory`. 1962 of the :term:`Source Directory`.
1793 1963
1794 Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set 1964 Within that ``poky.conf`` file, the ``DISTRO_NAME`` variable is set
1795 as follows: DISTRO_NAME = "Poky (Yocto Project Reference Distro)" 1965 as follows:
1796 1966 ::
1967
1968 DISTRO_NAME = "Poky (Yocto Project Reference Distro)"
1969
1797 Distribution configuration files are located in a ``conf/distro`` 1970 Distribution configuration files are located in a ``conf/distro``
1798 directory within the :term:`Metadata` that contains the 1971 directory within the :term:`Metadata` that contains the
1799 distribution configuration. 1972 distribution configuration.
1800 1973
1801 .. note:: 1974 .. note::
1802 1975
1803 If the 1976 If the
1804 DISTRO_NAME 1977 DISTRO_NAME
1805 variable is blank, a set of default configurations are used, which 1978 variable is blank, a set of default configurations are used, which
1806 are specified within 1979 are specified within
1807 meta/conf/distro/defaultsetup.conf 1980 meta/conf/distro/defaultsetup.conf
1808 also in the Source Directory. 1981 also in the Source Directory.
1809 1982
1810 DISTRO_VERSION 1983 DISTRO_VERSION
1811 The version of the distribution. 1984 The version of the distribution.
1812 1985
1813 DISTROOVERRIDES 1986 DISTROOVERRIDES
1814 A colon-separated list of overrides specific to the current 1987 A colon-separated list of overrides specific to the current
1815 distribution. By default, this list includes the value of 1988 distribution. By default, this list includes the value of
1816 :term:`DISTRO`. 1989 :term:`DISTRO`.
1817 1990
1818 You can extend ``DISTROOVERRIDES`` to add extra overrides that should 1991 You can extend ``DISTROOVERRIDES`` to add extra overrides that should
1819 apply to the distribution. 1992 apply to the distribution.
1820 1993
1821 The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it 1994 The underlying mechanism behind ``DISTROOVERRIDES`` is simply that it
1822 is included in the default value of 1995 is included in the default value of
1823 :term:`OVERRIDES`. 1996 :term:`OVERRIDES`.
1824 1997
1825 DL_DIR 1998 DL_DIR
1826 The central download directory used by the build process to store 1999 The central download directory used by the build process to store
1827 downloads. By default, ``DL_DIR`` gets files suitable for mirroring 2000 downloads. By default, ``DL_DIR`` gets files suitable for mirroring
@@ -1829,25 +2002,29 @@ system and gives an overview of their function and contents.
1829 repositories, use the 2002 repositories, use the
1830 :term:`BB_GENERATE_MIRROR_TARBALLS` 2003 :term:`BB_GENERATE_MIRROR_TARBALLS`
1831 variable. 2004 variable.
1832 2005
1833 You can set this directory by defining the ``DL_DIR`` variable in the 2006 You can set this directory by defining the ``DL_DIR`` variable in the
1834 ``conf/local.conf`` file. This directory is self-maintaining and you 2007 ``conf/local.conf`` file. This directory is self-maintaining and you
1835 should not have to touch it. By default, the directory is 2008 should not have to touch it. By default, the directory is
1836 ``downloads`` in the :term:`Build Directory`. #DL_DIR 2009 ``downloads`` in the :term:`Build Directory`.
1837 ?= "${TOPDIR}/downloads" To specify a different download directory, 2010 ::
2011
2012 #DL_DIR ?= "${TOPDIR}/downloads"
2013
2014 To specify a different download directory,
1838 simply remove the comment from the line and provide your directory. 2015 simply remove the comment from the line and provide your directory.
1839 2016
1840 During a first build, the system downloads many different source code 2017 During a first build, the system downloads many different source code
1841 tarballs from various upstream projects. Downloading can take a 2018 tarballs from various upstream projects. Downloading can take a
1842 while, particularly if your network connection is slow. Tarballs are 2019 while, particularly if your network connection is slow. Tarballs are
1843 all stored in the directory defined by ``DL_DIR`` and the build 2020 all stored in the directory defined by ``DL_DIR`` and the build
1844 system looks there first to find source tarballs. 2021 system looks there first to find source tarballs.
1845 2022
1846 .. note:: 2023 .. note::
1847 2024
1848 When wiping and rebuilding, you can preserve this directory to 2025 When wiping and rebuilding, you can preserve this directory to
1849 speed up this part of subsequent builds. 2026 speed up this part of subsequent builds.
1850 2027
1851 You can safely share this directory between multiple builds on the 2028 You can safely share this directory between multiple builds on the
1852 same development machine. For additional information on how the build 2029 same development machine. For additional information on how the build
1853 process gets source files when working behind a firewall or proxy 2030 process gets source files when working behind a firewall or proxy
@@ -1856,58 +2033,61 @@ system and gives an overview of their function and contents.
1856 chapter. You can also refer to the 2033 chapter. You can also refer to the
1857 ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`" 2034 ":yocto_wiki:`Working Behind a Network Proxy </wiki/Working_Behind_a_Network_Proxy>`"
1858 Wiki page. 2035 Wiki page.
1859 2036
1860 DOC_COMPRESS 2037 DOC_COMPRESS
1861 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>` 2038 When inheriting the :ref:`compress_doc <ref-classes-compress_doc>`
1862 class, this variable sets the compression policy used when the 2039 class, this variable sets the compression policy used when the
1863 OpenEmbedded build system compresses man pages and info pages. By 2040 OpenEmbedded build system compresses man pages and info pages. By
1864 default, the compression method used is gz (gzip). Other policies 2041 default, the compression method used is gz (gzip). Other policies
1865 available are xz and bz2. 2042 available are xz and bz2.
1866 2043
1867 For information on policies and on how to use this variable, see the 2044 For information on policies and on how to use this variable, see the
1868 comments in the ``meta/classes/compress_doc.bbclass`` file. 2045 comments in the ``meta/classes/compress_doc.bbclass`` file.
1869 2046
1870 EFI_PROVIDER 2047 EFI_PROVIDER
1871 When building bootable images (i.e. where ``hddimg``, ``iso``, or 2048 When building bootable images (i.e. where ``hddimg``, ``iso``, or
1872 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the 2049 ``wic.vmdk`` is in :term:`IMAGE_FSTYPES`), the
1873 ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The 2050 ``EFI_PROVIDER`` variable specifies the EFI bootloader to use. The
1874 default is "grub-efi", but "systemd-boot" can be used instead. 2051 default is "grub-efi", but "systemd-boot" can be used instead.
1875 2052
1876 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and 2053 See the :ref:`systemd-boot <ref-classes-systemd-boot>` and
1877 :ref:`image-live <ref-classes-image-live>` classes for more 2054 :ref:`image-live <ref-classes-image-live>` classes for more
1878 information. 2055 information.
1879 2056
1880 ENABLE_BINARY_LOCALE_GENERATION 2057 ENABLE_BINARY_LOCALE_GENERATION
1881 Variable that controls which locales for ``glibc`` are generated 2058 Variable that controls which locales for ``glibc`` are generated
1882 during the build (useful if the target device has 64Mbytes of RAM or 2059 during the build (useful if the target device has 64Mbytes of RAM or
1883 less). 2060 less).
1884 2061
1885 ERR_REPORT_DIR 2062 ERR_REPORT_DIR
1886 When used with the :ref:`report-error <ref-classes-report-error>` 2063 When used with the :ref:`report-error <ref-classes-report-error>`
1887 class, specifies the path used for storing the debug files created by 2064 class, specifies the path used for storing the debug files created by
1888 the `error reporting 2065 the :ref:`error reporting
1889 tool <&YOCTO_DOCS_DEV_URL;#using-the-error-reporting-tool>`__, which 2066 tool <dev-manual/dev-manual-common-tasks:using the error reporting tool>`, which
1890 allows you to submit build errors you encounter to a central 2067 allows you to submit build errors you encounter to a central
1891 database. By default, the value of this variable is 2068 database. By default, the value of this variable is
1892 ``${``\ :term:`LOG_DIR`\ ``}/error-report``. 2069 ``${``\ :term:`LOG_DIR`\ ``}/error-report``.
1893 2070
1894 You can set ``ERR_REPORT_DIR`` to the path you want the error 2071 You can set ``ERR_REPORT_DIR`` to the path you want the error
1895 reporting tool to store the debug files as follows in your 2072 reporting tool to store the debug files as follows in your
1896 ``local.conf`` file: ERR_REPORT_DIR = "path" 2073 ``local.conf`` file:
1897 2074 ::
2075
2076 ERR_REPORT_DIR = "path"
2077
1898 ERROR_QA 2078 ERROR_QA
1899 Specifies the quality assurance checks whose failures are reported as 2079 Specifies the quality assurance checks whose failures are reported as
1900 errors by the OpenEmbedded build system. You set this variable in 2080 errors by the OpenEmbedded build system. You set this variable in
1901 your distribution configuration file. For a list of the checks you 2081 your distribution configuration file. For a list of the checks you
1902 can control with this variable, see the 2082 can control with this variable, see the
1903 ":ref:`insane.bbclass <ref-classes-insane>`" section. 2083 ":ref:`insane.bbclass <ref-classes-insane>`" section.
1904 2084
1905 EXCLUDE_FROM_SHLIBS 2085 EXCLUDE_FROM_SHLIBS
1906 Triggers the OpenEmbedded build system's shared libraries resolver to 2086 Triggers the OpenEmbedded build system's shared libraries resolver to
1907 exclude an entire package when scanning for shared libraries. 2087 exclude an entire package when scanning for shared libraries.
1908 2088
1909 .. note:: 2089 .. note::
1910 2090
1911 The shared libraries resolver's functionality results in part from 2091 The shared libraries resolver's functionality results in part from
1912 the internal function 2092 the internal function
1913 package_do_shlibs 2093 package_do_shlibs
@@ -1915,25 +2095,28 @@ system and gives an overview of their function and contents.
1915 do_package 2095 do_package
1916 task. You should be aware that the shared libraries resolver might 2096 task. You should be aware that the shared libraries resolver might
1917 implicitly define some dependencies between packages. 2097 implicitly define some dependencies between packages.
1918 2098
1919 The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the 2099 The ``EXCLUDE_FROM_SHLIBS`` variable is similar to the
1920 :term:`PRIVATE_LIBS` variable, which excludes a 2100 :term:`PRIVATE_LIBS` variable, which excludes a
1921 package's particular libraries only and not the whole package. 2101 package's particular libraries only and not the whole package.
1922 2102
1923 Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a 2103 Use the ``EXCLUDE_FROM_SHLIBS`` variable by setting it to "1" for a
1924 particular package: EXCLUDE_FROM_SHLIBS = "1" 2104 particular package:
1925 2105 ::
2106
2107 EXCLUDE_FROM_SHLIBS = "1"
2108
1926 EXCLUDE_FROM_WORLD 2109 EXCLUDE_FROM_WORLD
1927 Directs BitBake to exclude a recipe from world builds (i.e. 2110 Directs BitBake to exclude a recipe from world builds (i.e.
1928 ``bitbake world``). During world builds, BitBake locates, parses and 2111 ``bitbake world``). During world builds, BitBake locates, parses and
1929 builds all recipes found in every layer exposed in the 2112 builds all recipes found in every layer exposed in the
1930 ``bblayers.conf`` configuration file. 2113 ``bblayers.conf`` configuration file.
1931 2114
1932 To exclude a recipe from a world build using this variable, set the 2115 To exclude a recipe from a world build using this variable, set the
1933 variable to "1" in the recipe. 2116 variable to "1" in the recipe.
1934 2117
1935 .. note:: 2118 .. note::
1936 2119
1937 Recipes added to 2120 Recipes added to
1938 EXCLUDE_FROM_WORLD 2121 EXCLUDE_FROM_WORLD
1939 may still be built during a world build in order to satisfy 2122 may still be built during a world build in order to satisfy
@@ -1941,52 +2124,53 @@ system and gives an overview of their function and contents.
1941 EXCLUDE_FROM_WORLD 2124 EXCLUDE_FROM_WORLD
1942 only ensures that the recipe is not explicitly added to the list 2125 only ensures that the recipe is not explicitly added to the list
1943 of build targets in a world build. 2126 of build targets in a world build.
1944 2127
1945 EXTENDPE 2128 EXTENDPE
1946 Used with file and pathnames to create a prefix for a recipe's 2129 Used with file and pathnames to create a prefix for a recipe's
1947 version based on the recipe's :term:`PE` value. If ``PE`` 2130 version based on the recipe's :term:`PE` value. If ``PE``
1948 is set and greater than zero for a recipe, ``EXTENDPE`` becomes that 2131 is set and greater than zero for a recipe, ``EXTENDPE`` becomes that
1949 value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1_"). 2132 value (e.g if ``PE`` is equal to "1" then ``EXTENDPE`` becomes "1").
1950 If a recipe's ``PE`` is not set (the default) or is equal to zero, 2133 If a recipe's ``PE`` is not set (the default) or is equal to zero,
1951 ``EXTENDPE`` becomes "". 2134 ``EXTENDPE`` becomes "".
1952 2135
1953 See the :term:`STAMP` variable for an example. 2136 See the :term:`STAMP` variable for an example.
1954 2137
1955 EXTENDPKGV 2138 EXTENDPKGV
1956 The full package version specification as it appears on the final 2139 The full package version specification as it appears on the final
1957 packages produced by a recipe. The variable's value is normally used 2140 packages produced by a recipe. The variable's value is normally used
1958 to fix a runtime dependency to the exact same version of another 2141 to fix a runtime dependency to the exact same version of another
1959 package in the same recipe: RDEPENDS_${PN}-additional-module = "${PN} 2142 package in the same recipe:
1960 (= ${EXTENDPKGV})" 2143 ::
1961 2144
2145 RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
2146
1962 The dependency relationships are intended to force the package 2147 The dependency relationships are intended to force the package
1963 manager to upgrade these types of packages in lock-step. 2148 manager to upgrade these types of packages in lock-step.
1964 2149
1965 EXTERNAL_KERNEL_TOOLS 2150 EXTERNAL_KERNEL_TOOLS
1966 When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these 2151 When set, the ``EXTERNAL_KERNEL_TOOLS`` variable indicates that these
1967 tools are not in the source tree. 2152 tools are not in the source tree.
1968 2153
1969 When kernel tools are available in the tree, they are preferred over 2154 When kernel tools are available in the tree, they are preferred over
1970 any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS`` 2155 any externally installed tools. Setting the ``EXTERNAL_KERNEL_TOOLS``
1971 variable tells the OpenEmbedded build system to prefer the installed 2156 variable tells the OpenEmbedded build system to prefer the installed
1972 external tools. See the 2157 external tools. See the
1973 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in 2158 :ref:`kernel-yocto <ref-classes-kernel-yocto>` class in
1974 ``meta/classes`` to see how the variable is used. 2159 ``meta/classes`` to see how the variable is used.
1975 2160
1976 EXTERNALSRC 2161 EXTERNALSRC
1977 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` 2162 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
1978 class, this variable points to the source tree, which is outside of 2163 class, this variable points to the source tree, which is outside of
1979 the OpenEmbedded build system. When set, this variable sets the 2164 the OpenEmbedded build system. When set, this variable sets the
1980 :term:`S` variable, which is what the OpenEmbedded build 2165 :term:`S` variable, which is what the OpenEmbedded build
1981 system uses to locate unpacked recipe source code. 2166 system uses to locate unpacked recipe source code.
1982 2167
1983 For more information on ``externalsrc.bbclass``, see the 2168 For more information on ``externalsrc.bbclass``, see the
1984 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You 2169 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
1985 can also find information on how to use this variable in the 2170 can also find information on how to use this variable in the
1986 "`Building Software from an External 2171 ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`"
1987 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
1988 section in the Yocto Project Development Tasks Manual. 2172 section in the Yocto Project Development Tasks Manual.
1989 2173
1990 EXTERNALSRC_BUILD 2174 EXTERNALSRC_BUILD
1991 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>` 2175 When inheriting the :ref:`externalsrc <ref-classes-externalsrc>`
1992 class, this variable points to the directory in which the recipe's 2176 class, this variable points to the directory in which the recipe's
@@ -1994,121 +2178,124 @@ system and gives an overview of their function and contents.
1994 system. When set, this variable sets the :term:`B` variable, 2178 system. When set, this variable sets the :term:`B` variable,
1995 which is what the OpenEmbedded build system uses to locate the Build 2179 which is what the OpenEmbedded build system uses to locate the Build
1996 Directory. 2180 Directory.
1997 2181
1998 For more information on ``externalsrc.bbclass``, see the 2182 For more information on ``externalsrc.bbclass``, see the
1999 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You 2183 ":ref:`externalsrc.bbclass <ref-classes-externalsrc>`" section. You
2000 can also find information on how to use this variable in the 2184 can also find information on how to use this variable in the
2001 "`Building Software from an External 2185 ":ref:`dev-manual/dev-manual-common-tasks:building software from an external source`"
2002 Source <&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source>`__"
2003 section in the Yocto Project Development Tasks Manual. 2186 section in the Yocto Project Development Tasks Manual.
2004 2187
2005 EXTRA_AUTORECONF 2188 EXTRA_AUTORECONF
2006 For recipes inheriting the :ref:`autotools <ref-classes-autotools>` 2189 For recipes inheriting the :ref:`autotools <ref-classes-autotools>`
2007 class, you can use ``EXTRA_AUTORECONF`` to specify extra options to 2190 class, you can use ``EXTRA_AUTORECONF`` to specify extra options to
2008 pass to the ``autoreconf`` command that is executed during the 2191 pass to the ``autoreconf`` command that is executed during the
2009 :ref:`ref-tasks-configure` task. 2192 :ref:`ref-tasks-configure` task.
2010 2193
2011 The default value is "--exclude=autopoint". 2194 The default value is "--exclude=autopoint".
2012 2195
2013 EXTRA_IMAGE_FEATURES 2196 EXTRA_IMAGE_FEATURES
2014 A list of additional features to include in an image. When listing 2197 A list of additional features to include in an image. When listing
2015 more than one feature, separate them with a space. 2198 more than one feature, separate them with a space.
2016 2199
2017 Typically, you configure this variable in your ``local.conf`` file, 2200 Typically, you configure this variable in your ``local.conf`` file,
2018 which is found in the :term:`Build Directory`. 2201 which is found in the :term:`Build Directory`.
2019 Although you can use this variable from within a recipe, best 2202 Although you can use this variable from within a recipe, best
2020 practices dictate that you do not. 2203 practices dictate that you do not.
2021 2204
2022 .. note:: 2205 .. note::
2023 2206
2024 To enable primary features from within the image recipe, use the 2207 To enable primary features from within the image recipe, use the
2025 IMAGE_FEATURES 2208 IMAGE_FEATURES
2026 variable. 2209 variable.
2027 2210
2028 Here are some examples of features you can add: "dbg-pkgs" - Adds 2211 Here are some examples of features you can add:
2029 -dbg packages for all installed packages including symbol information 2212
2030 for debugging and profiling. "debug-tweaks" - Makes an image suitable 2213 - "dbg-pkgs" - Adds -dbg packages for all installed packages including
2031 for debugging. For example, allows root logins without passwords and 2214 symbol information for debugging and profiling.
2032 enables post-installation logging. See the 'allow-empty-password' and 2215
2033 'post-install-logging' features in the "`Image 2216 - "debug-tweaks" - Makes an image suitable for debugging. For example, allows root logins without passwords and
2034 Features <#ref-features-image>`__" section for more information. 2217 enables post-installation logging. See the 'allow-empty-password' and
2035 "dev-pkgs" - Adds -dev packages for all installed packages. This is 2218 'post-install-logging' features in the "`Image
2036 useful if you want to develop against the libraries in the image. 2219 Features <#ref-features-image>`__" section for more information.
2037 "read-only-rootfs" - Creates an image whose root filesystem is 2220 - "dev-pkgs" - Adds -dev packages for all installed packages. This is
2038 read-only. See the "`Creating a Read-Only Root 2221 useful if you want to develop against the libraries in the image.
2039 Filesystem <&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem>`__" 2222 - "read-only-rootfs" - Creates an image whose root filesystem is
2040 section in the Yocto Project Development Tasks Manual for more 2223 read-only. See the
2041 information "tools-debug" - Adds debugging tools such as gdb and 2224 ":ref:`dev-manual/dev-manual-common-tasks:creating a read-only root filesystem`"
2042 strace. "tools-sdk" - Adds development tools such as gcc, make, 2225 section in the Yocto Project Development Tasks Manual for more
2043 pkgconfig and so forth. "tools-testapps" - Adds useful testing tools 2226 information
2044 such as ts_print, aplay, arecord and so forth. 2227 - "tools-debug" - Adds debugging tools such as gdb and strace.
2045 2228 - "tools-sdk" - Adds development tools such as gcc, make,
2229 pkgconfig and so forth.
2230 - "tools-testapps" - Adds useful testing tools
2231 such as ts_print, aplay, arecord and so forth.
2232
2046 For a complete list of image features that ships with the Yocto 2233 For a complete list of image features that ships with the Yocto
2047 Project, see the "`Image Features <#ref-features-image>`__" section. 2234 Project, see the "`Image Features <#ref-features-image>`__" section.
2048 2235
2049 For an example that shows how to customize your image by using this 2236 For an example that shows how to customize your image by using this
2050 variable, see the "`Customizing Images Using Custom 2237 variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`"
2051 ``IMAGE_FEATURES`` and
2052 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__"
2053 section in the Yocto Project Development Tasks Manual. 2238 section in the Yocto Project Development Tasks Manual.
2054 2239
2055 EXTRA_IMAGECMD 2240 EXTRA_IMAGECMD
2056 Specifies additional options for the image creation command that has 2241 Specifies additional options for the image creation command that has
2057 been specified in :term:`IMAGE_CMD`. When setting 2242 been specified in :term:`IMAGE_CMD`. When setting
2058 this variable, use an override for the associated image type. Here is 2243 this variable, use an override for the associated image type. Here is
2059 an example: EXTRA_IMAGECMD_ext3 ?= "-i 4096" 2244 an example:
2060 2245 ::
2246
2247 EXTRA_IMAGECMD_ext3 ?= "-i 4096"
2248
2061 EXTRA_IMAGEDEPENDS 2249 EXTRA_IMAGEDEPENDS
2062 A list of recipes to build that do not provide packages for 2250 A list of recipes to build that do not provide packages for
2063 installing into the root filesystem. 2251 installing into the root filesystem.
2064 2252
2065 Sometimes a recipe is required to build the final image but is not 2253 Sometimes a recipe is required to build the final image but is not
2066 needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS`` 2254 needed in the root filesystem. You can use the ``EXTRA_IMAGEDEPENDS``
2067 variable to list these recipes and thus specify the dependencies. A 2255 variable to list these recipes and thus specify the dependencies. A
2068 typical example is a required bootloader in a machine configuration. 2256 typical example is a required bootloader in a machine configuration.
2069 2257
2070 .. note:: 2258 .. note::
2071 2259
2072 To add packages to the root filesystem, see the various 2260 To add packages to the root filesystem, see the various
2073 \* 2261 \*RDEPENDS and \*RRECOMMENDS
2074 RDEPENDS
2075 and
2076 \*
2077 RRECOMMENDS
2078 variables. 2262 variables.
2079 2263
2080 EXTRANATIVEPATH 2264 EXTRANATIVEPATH
2081 A list of subdirectories of 2265 A list of subdirectories of
2082 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}`` 2266 ``${``\ :term:`STAGING_BINDIR_NATIVE`\ ``}``
2083 added to the beginning of the environment variable ``PATH``. As an 2267 added to the beginning of the environment variable ``PATH``. As an
2084 example, the following prepends 2268 example, the following prepends
2085 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to 2269 "${STAGING_BINDIR_NATIVE}/foo:${STAGING_BINDIR_NATIVE}/bar:" to
2086 ``PATH``: EXTRANATIVEPATH = "foo bar" 2270 ``PATH``:
2087 2271 ::
2272
2273 EXTRANATIVEPATH = "foo bar"
2274
2088 EXTRA_OECMAKE 2275 EXTRA_OECMAKE
2089 Additional `CMake <https://cmake.org/overview/>`__ options. See the 2276 Additional `CMake <https://cmake.org/overview/>`__ options. See the
2090 :ref:`cmake <ref-classes-cmake>` class for additional information. 2277 :ref:`cmake <ref-classes-cmake>` class for additional information.
2091 2278
2092 EXTRA_OECONF 2279 EXTRA_OECONF
2093 Additional ``configure`` script options. See 2280 Additional ``configure`` script options. See
2094 :term:`PACKAGECONFIG_CONFARGS` for 2281 :term:`PACKAGECONFIG_CONFARGS` for
2095 additional information on passing configure script options. 2282 additional information on passing configure script options.
2096 2283
2097 EXTRA_OEMAKE 2284 EXTRA_OEMAKE
2098 Additional GNU ``make`` options. 2285 Additional GNU ``make`` options.
2099 2286
2100 Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the 2287 Because the ``EXTRA_OEMAKE`` defaults to "", you need to set the
2101 variable to specify any required GNU options. 2288 variable to specify any required GNU options.
2102 2289
2103 :term:`PARALLEL_MAKE` and 2290 :term:`PARALLEL_MAKE` and
2104 :term:`PARALLEL_MAKEINST` also make use of 2291 :term:`PARALLEL_MAKEINST` also make use of
2105 ``EXTRA_OEMAKE`` to pass the required flags. 2292 ``EXTRA_OEMAKE`` to pass the required flags.
2106 2293
2107 EXTRA_OESCONS 2294 EXTRA_OESCONS
2108 When inheriting the :ref:`scons <ref-classes-scons>` class, this 2295 When inheriting the :ref:`scons <ref-classes-scons>` class, this
2109 variable specifies additional configuration options you want to pass 2296 variable specifies additional configuration options you want to pass
2110 to the ``scons`` command line. 2297 to the ``scons`` command line.
2111 2298
2112 EXTRA_USERS_PARAMS 2299 EXTRA_USERS_PARAMS
2113 When inheriting the :ref:`extrausers <ref-classes-extrausers>` 2300 When inheriting the :ref:`extrausers <ref-classes-extrausers>`
2114 class, this variable provides image level user and group operations. 2301 class, this variable provides image level user and group operations.
@@ -2116,26 +2303,35 @@ system and gives an overview of their function and contents.
2116 configuration as compared to using the 2303 configuration as compared to using the
2117 :ref:`useradd <ref-classes-useradd>` class, which ties user and 2304 :ref:`useradd <ref-classes-useradd>` class, which ties user and
2118 group configurations to a specific recipe. 2305 group configurations to a specific recipe.
2119 2306
2120 The set list of commands you can configure using the 2307 The set list of commands you can configure using the
2121 ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These 2308 ``EXTRA_USERS_PARAMS`` is shown in the ``extrausers`` class. These
2122 commands map to the normal Unix commands of the same names: # 2309 commands map to the normal Unix commands of the same names:
2123 EXTRA_USERS_PARAMS = "\\ # useradd -p '' tester; \\ # groupadd 2310 ::
2124 developers; \\ # userdel nobody; \\ # groupdel -g video; \\ # 2311
2125 groupmod -g 1020 developers; \\ # usermod -s /bin/sh tester; \\ # " 2312 # EXTRA_USERS_PARAMS = "\
2126 2313 # useradd -p '' tester; \
2314 # groupadd developers; \
2315 # userdel nobody; \
2316 # groupdel -g video; \
2317 # groupmod -g 1020 developers; \
2318 # usermod -s /bin/sh tester; \
2319 # "
2320
2127 FEATURE_PACKAGES 2321 FEATURE_PACKAGES
2128 Defines one or more packages to include in an image when a specific 2322 Defines one or more packages to include in an image when a specific
2129 item is included in :term:`IMAGE_FEATURES`. 2323 item is included in :term:`IMAGE_FEATURES`.
2130 When setting the value, ``FEATURE_PACKAGES`` should have the name of 2324 When setting the value, ``FEATURE_PACKAGES`` should have the name of
2131 the feature item as an override. Here is an example: 2325 the feature item as an override. Here is an example:
2132 FEATURE_PACKAGES_widget = "package1 package2" 2326 ::
2133 2327
2328 FEATURE_PACKAGES_widget = "package1 package2"
2329
2134 In this example, if "widget" were added to ``IMAGE_FEATURES``, 2330 In this example, if "widget" were added to ``IMAGE_FEATURES``,
2135 package1 and package2 would be included in the image. 2331 package1 and package2 would be included in the image.
2136 2332
2137 .. note:: 2333 .. note::
2138 2334
2139 Packages installed by features defined through 2335 Packages installed by features defined through
2140 FEATURE_PACKAGES 2336 FEATURE_PACKAGES
2141 are often package groups. While similarly named, you should not 2337 are often package groups. While similarly named, you should not
@@ -2143,40 +2339,46 @@ system and gives an overview of their function and contents.
2143 FEATURE_PACKAGES 2339 FEATURE_PACKAGES
2144 variable with package groups, which are discussed elsewhere in the 2340 variable with package groups, which are discussed elsewhere in the
2145 documentation. 2341 documentation.
2146 2342
2147 FEED_DEPLOYDIR_BASE_URI 2343 FEED_DEPLOYDIR_BASE_URI
2148 Points to the base URL of the server and location within the 2344 Points to the base URL of the server and location within the
2149 document-root that provides the metadata and packages required by 2345 document-root that provides the metadata and packages required by
2150 OPKG to support runtime package management of IPK packages. You set 2346 OPKG to support runtime package management of IPK packages. You set
2151 this variable in your ``local.conf`` file. 2347 this variable in your ``local.conf`` file.
2152 2348
2153 Consider the following example: FEED_DEPLOYDIR_BASE_URI = 2349 Consider the following example:
2154 "http://192.168.7.1/BOARD-dir" This example assumes you are serving 2350 ::
2351
2352 FEED_DEPLOYDIR_BASE_URI = "http://192.168.7.1/BOARD-dir"
2353
2354 This example assumes you are serving
2155 your packages over HTTP and your databases are located in a directory 2355 your packages over HTTP and your databases are located in a directory
2156 named ``BOARD-dir``, which is underneath your HTTP server's 2356 named ``BOARD-dir``, which is underneath your HTTP server's
2157 document-root. In this case, the OpenEmbedded build system generates 2357 document-root. In this case, the OpenEmbedded build system generates
2158 a set of configuration files for you in your target that work with 2358 a set of configuration files for you in your target that work with
2159 the feed. 2359 the feed.
2160 2360
2161 FILES 2361 FILES
2162 The list of files and directories that are placed in a package. The 2362 The list of files and directories that are placed in a package. The
2163 :term:`PACKAGES` variable lists the packages 2363 :term:`PACKAGES` variable lists the packages
2164 generated by a recipe. 2364 generated by a recipe.
2165 2365
2166 To use the ``FILES`` variable, provide a package name override that 2366 To use the ``FILES`` variable, provide a package name override that
2167 identifies the resulting package. Then, provide a space-separated 2367 identifies the resulting package. Then, provide a space-separated
2168 list of files or paths that identify the files you want included as 2368 list of files or paths that identify the files you want included as
2169 part of the resulting package. Here is an example: FILES_${PN} += 2369 part of the resulting package. Here is an example:
2170 "${bindir}/mydir1 ${bindir}/mydir2/myfile" 2370 ::
2171 2371
2372 FILES_${PN} += "${bindir}/mydir1 ${bindir}/mydir2/myfile"
2373
2172 .. note:: 2374 .. note::
2173 2375
2174 - When specifying files or paths, you can pattern match using 2376 - When specifying files or paths, you can pattern match using
2175 Python's 2377 Python's
2176 ```glob`https://docs.python.org/2/library/glob.html 2378 `glob <https://docs.python.org/3/library/glob.html>`_
2177 syntax. For details on the syntax, see the documentation by 2379 syntax. For details on the syntax, see the documentation by
2178 following the previous link. 2380 following the previous link.
2179 2381
2180 - When specifying paths as part of the ``FILES`` variable, it is 2382 - When specifying paths as part of the ``FILES`` variable, it is
2181 good practice to use appropriate path variables. For example, 2383 good practice to use appropriate path variables. For example,
2182 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}`` 2384 use ``${sysconfdir}`` rather than ``/etc``, or ``${bindir}``
@@ -2185,24 +2387,26 @@ system and gives an overview of their function and contents.
2185 the :term:`Source Directory`. You will also 2387 the :term:`Source Directory`. You will also
2186 find the default values of the various ``FILES_*`` variables in 2388 find the default values of the various ``FILES_*`` variables in
2187 this file. 2389 this file.
2188 2390
2189 If some of the files you provide with the ``FILES`` variable are 2391 If some of the files you provide with the ``FILES`` variable are
2190 editable and you know they should not be overwritten during the 2392 editable and you know they should not be overwritten during the
2191 package update process by the Package Management System (PMS), you 2393 package update process by the Package Management System (PMS), you
2192 can identify these files so that the PMS will not overwrite them. See 2394 can identify these files so that the PMS will not overwrite them. See
2193 the :term:`CONFFILES` variable for information on 2395 the :term:`CONFFILES` variable for information on
2194 how to identify these files to the PMS. 2396 how to identify these files to the PMS.
2195 2397
2196 FILES_SOLIBSDEV 2398 FILES_SOLIBSDEV
2197 Defines the file specification to match 2399 Defines the file specification to match
2198 :term:`SOLIBSDEV`. In other words, 2400 :term:`SOLIBSDEV`. In other words,
2199 ``FILES_SOLIBSDEV`` defines the full path name of the development 2401 ``FILES_SOLIBSDEV`` defines the full path name of the development
2200 symbolic link (symlink) for shared libraries on the target platform. 2402 symbolic link (symlink) for shared libraries on the target platform.
2201 2403
2202 The following statement from the ``bitbake.conf`` shows how it is 2404 The following statement from the ``bitbake.conf`` shows how it is
2203 set: FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} 2405 set:
2204 ${libdir}/lib*${SOLIBSDEV}" 2406 ::
2205 2407
2408 FILES_SOLIBSDEV ?= "${base_libdir}/lib*${SOLIBSDEV} ${libdir}/lib*${SOLIBSDEV}"
2409
2206 FILESEXTRAPATHS 2410 FILESEXTRAPATHS
2207 Extends the search path the OpenEmbedded build system uses when 2411 Extends the search path the OpenEmbedded build system uses when
2208 looking for files and patches as it processes recipes and append 2412 looking for files and patches as it processes recipes and append
@@ -2210,58 +2414,71 @@ system and gives an overview of their function and contents.
2210 are initially defined by the :term:`FILESPATH` 2414 are initially defined by the :term:`FILESPATH`
2211 variable. You can extend ``FILESPATH`` variable by using 2415 variable. You can extend ``FILESPATH`` variable by using
2212 ``FILESEXTRAPATHS``. 2416 ``FILESEXTRAPATHS``.
2213 2417
2214 Best practices dictate that you accomplish this by using 2418 Best practices dictate that you accomplish this by using
2215 ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you 2419 ``FILESEXTRAPATHS`` from within a ``.bbappend`` file and that you
2216 prepend paths as follows: FILESEXTRAPATHS_prepend := 2420 prepend paths as follows:
2217 "${THISDIR}/${PN}:" In the above example, the build system first 2421 ::
2422
2423 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
2424
2425 In the above example, the build system first
2218 looks for files in a directory that has the same name as the 2426 looks for files in a directory that has the same name as the
2219 corresponding append file. 2427 corresponding append file.
2220 2428
2221 .. note:: 2429 .. note::
2222 2430
2223 When extending ``FILESEXTRAPATHS``, be sure to use the immediate 2431 When extending ``FILESEXTRAPATHS``, be sure to use the immediate
2224 expansion (``:=``) operator. Immediate expansion makes sure that 2432 expansion (``:=``) operator. Immediate expansion makes sure that
2225 BitBake evaluates :term:`THISDIR` at the time the 2433 BitBake evaluates :term:`THISDIR` at the time the
2226 directive is encountered rather than at some later time when 2434 directive is encountered rather than at some later time when
2227 expansion might result in a directory that does not contain the 2435 expansion might result in a directory that does not contain the
2228 files you need. 2436 files you need.
2229 2437
2230 Also, include the trailing separating colon character if you are 2438 Also, include the trailing separating colon character if you are
2231 prepending. The trailing colon character is necessary because you 2439 prepending. The trailing colon character is necessary because you
2232 are directing BitBake to extend the path by prepending directories 2440 are directing BitBake to extend the path by prepending directories
2233 to the search path. 2441 to the search path.
2234 2442
2235 Here is another common use: FILESEXTRAPATHS_prepend := 2443 Here is another common use:
2236 "${THISDIR}/files:" In this example, the build system extends the 2444 ::
2445
2446 FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
2447
2448 In this example, the build system extends the
2237 ``FILESPATH`` variable to include a directory named ``files`` that is 2449 ``FILESPATH`` variable to include a directory named ``files`` that is
2238 in the same directory as the corresponding append file. 2450 in the same directory as the corresponding append file.
2239 2451
2240 This next example specifically adds three paths: 2452 This next example specifically adds three paths:
2241 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:" 2453 ::
2242 2454
2455 FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
2456
2243 A final example shows how you can extend the search path and include 2457 A final example shows how you can extend the search path and include
2244 a :term:`MACHINE`-specific override, which is useful 2458 a :term:`MACHINE`-specific override, which is useful
2245 in a BSP layer: FILESEXTRAPATHS_prepend_intel-x86-common := 2459 in a BSP layer:
2246 "${THISDIR}/${PN}:" The previous statement appears in the 2460 ::
2247 ``linux-yocto-dev.bbappend`` file, which is found in the Yocto 2461
2248 Project `Source 2462 FILESEXTRAPATHS_prepend_intel-x86-common := "${THISDIR}/${PN}:"
2249 Repositories <&YOCTO_DOCS_OM_URL;#source-repositories>`__ in 2463
2464 The previous statement appears in the
2465 ``linux-yocto-dev.bbappend`` file, which is found in the
2466 :ref:`overview-manual/overview-manual-development-environment:yocto project source repositories` in
2250 ``meta-intel/common/recipes-kernel/linux``. Here, the machine 2467 ``meta-intel/common/recipes-kernel/linux``. Here, the machine
2251 override is a special :term:`PACKAGE_ARCH` 2468 override is a special :term:`PACKAGE_ARCH`
2252 definition for multiple ``meta-intel`` machines. 2469 definition for multiple ``meta-intel`` machines.
2253 2470
2254 .. note:: 2471 .. note::
2255 2472
2256 For a layer that supports a single BSP, the override could just be 2473 For a layer that supports a single BSP, the override could just be
2257 the value of 2474 the value of
2258 MACHINE 2475 MACHINE
2259 . 2476 .
2260 2477
2261 By prepending paths in ``.bbappend`` files, you allow multiple append 2478 By prepending paths in ``.bbappend`` files, you allow multiple append
2262 files that reside in different layers but are used for the same 2479 files that reside in different layers but are used for the same
2263 recipe to correctly extend the path. 2480 recipe to correctly extend the path.
2264 2481
2265 FILESOVERRIDES 2482 FILESOVERRIDES
2266 A subset of :term:`OVERRIDES` used by the 2483 A subset of :term:`OVERRIDES` used by the
2267 OpenEmbedded build system for creating 2484 OpenEmbedded build system for creating
@@ -2273,53 +2490,63 @@ system and gives an overview of their function and contents.
2273 are handled in the 2490 are handled in the
2274 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 2491 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
2275 section of the BitBake User Manual. 2492 section of the BitBake User Manual.
2276 2493
2277 By default, the ``FILESOVERRIDES`` variable is defined as: 2494 By default, the ``FILESOVERRIDES`` variable is defined as:
2278 FILESOVERRIDES = 2495 ::
2279 "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}" 2496
2280 2497 FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
2498
2281 .. note:: 2499 .. note::
2282 2500
2283 Do not hand-edit the 2501 Do not hand-edit the
2284 FILESOVERRIDES 2502 FILESOVERRIDES
2285 variable. The values match up with expected overrides and are used 2503 variable. The values match up with expected overrides and are used
2286 in an expected manner by the build system. 2504 in an expected manner by the build system.
2287 2505
2288 FILESPATH 2506 FILESPATH
2289 The default set of directories the OpenEmbedded build system uses 2507 The default set of directories the OpenEmbedded build system uses
2290 when searching for patches and files. 2508 when searching for patches and files.
2291 2509
2292 During the build process, BitBake searches each directory in 2510 During the build process, BitBake searches each directory in
2293 ``FILESPATH`` in the specified order when looking for files and 2511 ``FILESPATH`` in the specified order when looking for files and
2294 patches specified by each ``file://`` URI in a recipe's 2512 patches specified by each ``file://`` URI in a recipe's
2295 :term:`SRC_URI` statements. 2513 :term:`SRC_URI` statements.
2296 2514
2297 The default value for the ``FILESPATH`` variable is defined in the 2515 The default value for the ``FILESPATH`` variable is defined in the
2298 ``base.bbclass`` class found in ``meta/classes`` in the 2516 ``base.bbclass`` class found in ``meta/classes`` in the
2299 :term:`Source Directory`: FILESPATH = 2517 :term:`Source Directory`:
2300 "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \\ 2518 ::
2301 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}" The 2519
2520 FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
2521 "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
2522
2523 The
2302 ``FILESPATH`` variable is automatically extended using the overrides 2524 ``FILESPATH`` variable is automatically extended using the overrides
2303 from the :term:`FILESOVERRIDES` variable. 2525 from the :term:`FILESOVERRIDES` variable.
2304 2526
2305 .. note:: 2527 .. note::
2306 2528
2307 - Do not hand-edit the ``FILESPATH`` variable. If you want the 2529 - Do not hand-edit the ``FILESPATH`` variable. If you want the
2308 build system to look in directories other than the defaults, 2530 build system to look in directories other than the defaults,
2309 extend the ``FILESPATH`` variable by using the 2531 extend the ``FILESPATH`` variable by using the
2310 :term:`FILESEXTRAPATHS` variable. 2532 :term:`FILESEXTRAPATHS` variable.
2311 2533
2312 - Be aware that the default ``FILESPATH`` directories do not map 2534 - Be aware that the default ``FILESPATH`` directories do not map
2313 to directories in custom layers where append files 2535 to directories in custom layers where append files
2314 (``.bbappend``) are used. If you want the build system to find 2536 (``.bbappend``) are used. If you want the build system to find
2315 patches or files that reside with your append files, you need 2537 patches or files that reside with your append files, you need
2316 to extend the ``FILESPATH`` variable by using the 2538 to extend the ``FILESPATH`` variable by using the
2317 ``FILESEXTRAPATHS`` variable. 2539 ``FILESEXTRAPATHS`` variable.
2318 2540
2319 You can take advantage of this searching behavior in useful ways. For 2541 You can take advantage of this searching behavior in useful ways. For
2320 example, consider a case where the following directory structure 2542 example, consider a case where the following directory structure
2321 exists for general and machine-specific configurations: 2543 exists for general and machine-specific configurations:
2322 files/defconfig files/MACHINEA/defconfig files/MACHINEB/defconfig 2544 ::
2545
2546 files/defconfig
2547 files/MACHINEA/defconfig
2548 files/MACHINEB/defconfig
2549
2323 Also in the example, the ``SRC_URI`` statement contains 2550 Also in the example, the ``SRC_URI`` statement contains
2324 "file://defconfig". Given this scenario, you can set 2551 "file://defconfig". Given this scenario, you can set
2325 :term:`MACHINE` to "MACHINEA" and cause the build 2552 :term:`MACHINE` to "MACHINEA" and cause the build
@@ -2327,37 +2554,37 @@ system and gives an overview of their function and contents.
2327 "MACHINEB" and the build system uses files from ``files/MACHINEB``. 2554 "MACHINEB" and the build system uses files from ``files/MACHINEB``.
2328 Finally, for any machine other than "MACHINEA" and "MACHINEB", the 2555 Finally, for any machine other than "MACHINEA" and "MACHINEB", the
2329 build system uses files from ``files/defconfig``. 2556 build system uses files from ``files/defconfig``.
2330 2557
2331 You can find out more about the patching process in the 2558 You can find out more about the patching process in the
2332 "`Patching <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__" section 2559 ":ref:`patching-dev-environment`" section
2333 in the Yocto Project Overview and Concepts Manual and the "`Patching 2560 in the Yocto Project Overview and Concepts Manual and the
2334 Code <&YOCTO_DOCS_DEV_URL;#new-recipe-patching-code>`__" section in 2561 ":ref:`new-recipe-patching-code`" section in
2335 the Yocto Project Development Tasks Manual. See the 2562 the Yocto Project Development Tasks Manual. See the
2336 :ref:`ref-tasks-patch` task as well. 2563 :ref:`ref-tasks-patch` task as well.
2337 2564
2338 FILESYSTEM_PERMS_TABLES 2565 FILESYSTEM_PERMS_TABLES
2339 Allows you to define your own file permissions settings table as part 2566 Allows you to define your own file permissions settings table as part
2340 of your configuration for the packaging process. For example, suppose 2567 of your configuration for the packaging process. For example, suppose
2341 you need a consistent set of custom permissions for a set of groups 2568 you need a consistent set of custom permissions for a set of groups
2342 and users across an entire work project. It is best to do this in the 2569 and users across an entire work project. It is best to do this in the
2343 packages themselves but this is not always possible. 2570 packages themselves but this is not always possible.
2344 2571
2345 By default, the OpenEmbedded build system uses the ``fs-perms.txt``, 2572 By default, the OpenEmbedded build system uses the ``fs-perms.txt``,
2346 which is located in the ``meta/files`` folder in the :term:`Source Directory`. 2573 which is located in the ``meta/files`` folder in the :term:`Source Directory`.
2347 If you create your own file 2574 If you create your own file
2348 permissions setting table, you should place it in your layer or the 2575 permissions setting table, you should place it in your layer or the
2349 distro's layer. 2576 distro's layer.
2350 2577
2351 You define the ``FILESYSTEM_PERMS_TABLES`` variable in the 2578 You define the ``FILESYSTEM_PERMS_TABLES`` variable in the
2352 ``conf/local.conf`` file, which is found in the :term:`Build Directory`, 2579 ``conf/local.conf`` file, which is found in the :term:`Build Directory`,
2353 to point to your custom 2580 to point to your custom
2354 ``fs-perms.txt``. You can specify more than a single file permissions 2581 ``fs-perms.txt``. You can specify more than a single file permissions
2355 setting table. The paths you specify to these files must be defined 2582 setting table. The paths you specify to these files must be defined
2356 within the :term:`BBPATH` variable. 2583 within the :term:`BBPATH` variable.
2357 2584
2358 For guidance on how to create your own file permissions settings 2585 For guidance on how to create your own file permissions settings
2359 table file, examine the existing ``fs-perms.txt``. 2586 table file, examine the existing ``fs-perms.txt``.
2360 2587
2361 FIT_HASH_ALG 2588 FIT_HASH_ALG
2362 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256. 2589 Specifies the hash algorithm used in creating the FIT Image. For e.g. sha256.
2363 2590
@@ -2369,7 +2596,7 @@ system and gives an overview of their function and contents.
2369 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, 2596 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2370 this variable specifies the runtime dependencies for font packages. 2597 this variable specifies the runtime dependencies for font packages.
2371 By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils". 2598 By default, the ``FONT_EXTRA_RDEPENDS`` is set to "fontconfig-utils".
2372 2599
2373 FONT_PACKAGES 2600 FONT_PACKAGES
2374 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class, 2601 When inheriting the :ref:`fontcache <ref-classes-fontcache>` class,
2375 this variable identifies packages containing font files that need to 2602 this variable identifies packages containing font files that need to
@@ -2377,168 +2604,189 @@ system and gives an overview of their function and contents.
2377 that fonts are in the recipe's main package (i.e. 2604 that fonts are in the recipe's main package (i.e.
2378 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you 2605 ``${``\ :term:`PN`\ ``}``). Use this variable if fonts you
2379 need are in a package other than that main package. 2606 need are in a package other than that main package.
2380 2607
2381 FORCE_RO_REMOVE 2608 FORCE_RO_REMOVE
2382 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED`` 2609 Forces the removal of the packages listed in ``ROOTFS_RO_UNNEEDED``
2383 during the generation of the root filesystem. 2610 during the generation of the root filesystem.
2384 2611
2385 Set the variable to "1" to force the removal of these packages. 2612 Set the variable to "1" to force the removal of these packages.
2386 2613
2387 FULL_OPTIMIZATION 2614 FULL_OPTIMIZATION
2388 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when 2615 The options to pass in ``TARGET_CFLAGS`` and ``CFLAGS`` when
2389 compiling an optimized system. This variable defaults to "-O2 -pipe 2616 compiling an optimized system. This variable defaults to "-O2 -pipe
2390 ${DEBUG_FLAGS}". 2617 ${DEBUG_FLAGS}".
2391 2618
2392 GCCPIE 2619 GCCPIE
2393 Enables Position Independent Executables (PIE) within the GNU C 2620 Enables Position Independent Executables (PIE) within the GNU C
2394 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented 2621 Compiler (GCC). Enabling PIE in the GCC makes Return Oriented
2395 Programming (ROP) attacks much more difficult to execute. 2622 Programming (ROP) attacks much more difficult to execute.
2396 2623
2397 By default the ``security_flags.inc`` file enables PIE by setting the 2624 By default the ``security_flags.inc`` file enables PIE by setting the
2398 variable as follows: GCCPIE ?= "--enable-default-pie" 2625 variable as follows:
2399 2626 ::
2627
2628 GCCPIE ?= "--enable-default-pie"
2629
2400 GCCVERSION 2630 GCCVERSION
2401 Specifies the default version of the GNU C Compiler (GCC) used for 2631 Specifies the default version of the GNU C Compiler (GCC) used for
2402 compilation. By default, ``GCCVERSION`` is set to "8.x" in the 2632 compilation. By default, ``GCCVERSION`` is set to "8.x" in the
2403 ``meta/conf/distro/include/tcmode-default.inc`` include file: 2633 ``meta/conf/distro/include/tcmode-default.inc`` include file:
2404 GCCVERSION ?= "8.%" You can override this value by setting it in a 2634 ::
2635
2636 GCCVERSION ?= "8.%"
2637
2638 You can override this value by setting it in a
2405 configuration file such as the ``local.conf``. 2639 configuration file such as the ``local.conf``.
2406 2640
2407 GDB 2641 GDB
2408 The minimal command and arguments to run the GNU Debugger. 2642 The minimal command and arguments to run the GNU Debugger.
2409 2643
2410 GITDIR 2644 GITDIR
2411 The directory in which a local copy of a Git repository is stored 2645 The directory in which a local copy of a Git repository is stored
2412 when it is cloned. 2646 when it is cloned.
2413 2647
2414 GLIBC_GENERATE_LOCALES 2648 GLIBC_GENERATE_LOCALES
2415 Specifies the list of GLIBC locales to generate should you not wish 2649 Specifies the list of GLIBC locales to generate should you not wish
2416 to generate all LIBC locals, which can be time consuming. 2650 to generate all LIBC locals, which can be time consuming.
2417 2651
2418 .. note:: 2652 .. note::
2419 2653
2420 If you specifically remove the locale 2654 If you specifically remove the locale
2421 en_US.UTF-8 2655 en_US.UTF-8
2422 , you must set 2656 , you must set
2423 IMAGE_LINGUAS 2657 IMAGE_LINGUAS
2424 appropriately. 2658 appropriately.
2425 2659
2426 You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file. 2660 You can set ``GLIBC_GENERATE_LOCALES`` in your ``local.conf`` file.
2427 By default, all locales are generated. GLIBC_GENERATE_LOCALES = 2661 By default, all locales are generated.
2428 "en_GB.UTF-8 en_US.UTF-8" 2662 ::
2429 2663
2664 GLIBC_GENERATE_LOCALES = "en_GB.UTF-8 en_US.UTF-8"
2665
2430 GROUPADD_PARAM 2666 GROUPADD_PARAM
2431 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 2667 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2432 this variable specifies for a package what parameters should be 2668 this variable specifies for a package what parameters should be
2433 passed to the ``groupadd`` command if you wish to add a group to the 2669 passed to the ``groupadd`` command if you wish to add a group to the
2434 system when the package is installed. 2670 system when the package is installed.
2435 2671
2436 Here is an example from the ``dbus`` recipe: GROUPADD_PARAM_${PN} = 2672 Here is an example from the ``dbus`` recipe:
2437 "-r netdev" For information on the standard Linux shell command 2673 ::
2674
2675 GROUPADD_PARAM_${PN} = "-r netdev"
2676
2677 For information on the standard Linux shell command
2438 ``groupadd``, see http://linux.die.net/man/8/groupadd. 2678 ``groupadd``, see http://linux.die.net/man/8/groupadd.
2439 2679
2440 GROUPMEMS_PARAM 2680 GROUPMEMS_PARAM
2441 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 2681 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
2442 this variable specifies for a package what parameters should be 2682 this variable specifies for a package what parameters should be
2443 passed to the ``groupmems`` command if you wish to modify the members 2683 passed to the ``groupmems`` command if you wish to modify the members
2444 of a group when the package is installed. 2684 of a group when the package is installed.
2445 2685
2446 For information on the standard Linux shell command ``groupmems``, 2686 For information on the standard Linux shell command ``groupmems``,
2447 see http://linux.die.net/man/8/groupmems. 2687 see http://linux.die.net/man/8/groupmems.
2448 2688
2449 GRUB_GFXSERIAL 2689 GRUB_GFXSERIAL
2450 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics 2690 Configures the GNU GRand Unified Bootloader (GRUB) to have graphics
2451 and serial in the boot menu. Set this variable to "1" in your 2691 and serial in the boot menu. Set this variable to "1" in your
2452 ``local.conf`` or distribution configuration file to enable graphics 2692 ``local.conf`` or distribution configuration file to enable graphics
2453 and serial in the menu. 2693 and serial in the menu.
2454 2694
2455 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 2695 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
2456 information on how this variable is used. 2696 information on how this variable is used.
2457 2697
2458 GRUB_OPTS 2698 GRUB_OPTS
2459 Additional options to add to the GNU GRand Unified Bootloader (GRUB) 2699 Additional options to add to the GNU GRand Unified Bootloader (GRUB)
2460 configuration. Use a semi-colon character (``;``) to separate 2700 configuration. Use a semi-colon character (``;``) to separate
2461 multiple options. 2701 multiple options.
2462 2702
2463 The ``GRUB_OPTS`` variable is optional. See the 2703 The ``GRUB_OPTS`` variable is optional. See the
2464 :ref:`grub-efi <ref-classes-grub-efi>` class for more information 2704 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2465 on how this variable is used. 2705 on how this variable is used.
2466 2706
2467 GRUB_TIMEOUT 2707 GRUB_TIMEOUT
2468 Specifies the timeout before executing the default ``LABEL`` in the 2708 Specifies the timeout before executing the default ``LABEL`` in the
2469 GNU GRand Unified Bootloader (GRUB). 2709 GNU GRand Unified Bootloader (GRUB).
2470 2710
2471 The ``GRUB_TIMEOUT`` variable is optional. See the 2711 The ``GRUB_TIMEOUT`` variable is optional. See the
2472 :ref:`grub-efi <ref-classes-grub-efi>` class for more information 2712 :ref:`grub-efi <ref-classes-grub-efi>` class for more information
2473 on how this variable is used. 2713 on how this variable is used.
2474 2714
2475 GTKIMMODULES_PACKAGES 2715 GTKIMMODULES_PACKAGES
2476 When inheriting the 2716 When inheriting the
2477 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class, 2717 :ref:`gtk-immodules-cache <ref-classes-gtk-immodules-cache>` class,
2478 this variable specifies the packages that contain the GTK+ input 2718 this variable specifies the packages that contain the GTK+ input
2479 method modules being installed when the modules are in packages other 2719 method modules being installed when the modules are in packages other
2480 than the main package. 2720 than the main package.
2481 2721
2482 HOMEPAGE 2722 HOMEPAGE
2483 Website where more information about the software the recipe is 2723 Website where more information about the software the recipe is
2484 building can be found. 2724 building can be found.
2485 2725
2486 HOST_ARCH 2726 HOST_ARCH
2487 The name of the target architecture, which is normally the same as 2727 The name of the target architecture, which is normally the same as
2488 :term:`TARGET_ARCH`. The OpenEmbedded build system 2728 :term:`TARGET_ARCH`. The OpenEmbedded build system
2489 supports many architectures. Here is an example list of architectures 2729 supports many architectures. Here is an example list of architectures
2490 supported. This list is by no means complete as the architecture is 2730 supported. This list is by no means complete as the architecture is
2491 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel 2731 configurable:
2492 2732
2733 - arm
2734 - i586
2735 - x86_64
2736 - powerpc
2737 - powerpc64
2738 - mips
2739 - mipsel
2740
2493 HOST_CC_ARCH 2741 HOST_CC_ARCH
2494 Specifies architecture-specific compiler flags that are passed to the 2742 Specifies architecture-specific compiler flags that are passed to the
2495 C compiler. 2743 C compiler.
2496 2744
2497 Default initialization for ``HOST_CC_ARCH`` varies depending on what 2745 Default initialization for ``HOST_CC_ARCH`` varies depending on what
2498 is being built: 2746 is being built:
2499 2747
2500 - :term:`TARGET_CC_ARCH` when building for the 2748 - :term:`TARGET_CC_ARCH` when building for the
2501 target 2749 target
2502 2750
2503 - ``BUILD_CC_ARCH`` when building for the build host (i.e. 2751 - ``BUILD_CC_ARCH`` when building for the build host (i.e.
2504 ``-native``) 2752 ``-native``)
2505 2753
2506 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e. 2754 - ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
2507 ``nativesdk-``) 2755 ``nativesdk-``)
2508 2756
2509 HOST_OS 2757 HOST_OS
2510 Specifies the name of the target operating system, which is normally 2758 Specifies the name of the target operating system, which is normally
2511 the same as the :term:`TARGET_OS`. The variable can 2759 the same as the :term:`TARGET_OS`. The variable can
2512 be set to "linux" for ``glibc``-based systems and to "linux-musl" for 2760 be set to "linux" for ``glibc``-based systems and to "linux-musl" for
2513 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and 2761 ``musl``. For ARM/EABI targets, there are also "linux-gnueabi" and
2514 "linux-musleabi" values possible. 2762 "linux-musleabi" values possible.
2515 2763
2516 HOST_PREFIX 2764 HOST_PREFIX
2517 Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX`` 2765 Specifies the prefix for the cross-compile toolchain. ``HOST_PREFIX``
2518 is normally the same as :term:`TARGET_PREFIX`. 2766 is normally the same as :term:`TARGET_PREFIX`.
2519 2767
2520 HOST_SYS 2768 HOST_SYS
2521 Specifies the system, including the architecture and the operating 2769 Specifies the system, including the architecture and the operating
2522 system, for which the build is occurring in the context of the 2770 system, for which the build is occurring in the context of the
2523 current recipe. 2771 current recipe.
2524 2772
2525 The OpenEmbedded build system automatically sets this variable based 2773 The OpenEmbedded build system automatically sets this variable based
2526 on :term:`HOST_ARCH`, 2774 on :term:`HOST_ARCH`,
2527 :term:`HOST_VENDOR`, and 2775 :term:`HOST_VENDOR`, and
2528 :term:`HOST_OS` variables. 2776 :term:`HOST_OS` variables.
2529 2777
2530 .. note:: 2778 .. note::
2531 2779
2532 You do not need to set the variable yourself. 2780 You do not need to set the variable yourself.
2533 2781
2534 Consider these two examples: 2782 Consider these two examples:
2535 2783
2536 - Given a native recipe on a 32-bit x86 machine running Linux, the 2784 - Given a native recipe on a 32-bit x86 machine running Linux, the
2537 value is "i686-linux". 2785 value is "i686-linux".
2538 2786
2539 - Given a recipe being built for a little-endian MIPS target running 2787 - Given a recipe being built for a little-endian MIPS target running
2540 Linux, the value might be "mipsel-linux". 2788 Linux, the value might be "mipsel-linux".
2541 2789
2542 HOSTTOOLS 2790 HOSTTOOLS
2543 A space-separated list (filter) of tools on the build host that 2791 A space-separated list (filter) of tools on the build host that
2544 should be allowed to be called from within build tasks. Using this 2792 should be allowed to be called from within build tasks. Using this
@@ -2546,10 +2794,10 @@ system and gives an overview of their function and contents.
2546 specified in the value of ``HOSTTOOLS`` is not found on the build 2794 specified in the value of ``HOSTTOOLS`` is not found on the build
2547 host, the OpenEmbedded build system produces an error and the build 2795 host, the OpenEmbedded build system produces an error and the build
2548 is not started. 2796 is not started.
2549 2797
2550 For additional information, see 2798 For additional information, see
2551 :term:`HOSTTOOLS_NONFATAL`. 2799 :term:`HOSTTOOLS_NONFATAL`.
2552 2800
2553 HOSTTOOLS_NONFATAL 2801 HOSTTOOLS_NONFATAL
2554 A space-separated list (filter) of tools on the build host that 2802 A space-separated list (filter) of tools on the build host that
2555 should be allowed to be called from within build tasks. Using this 2803 should be allowed to be called from within build tasks. Using this
@@ -2558,44 +2806,51 @@ system and gives an overview of their function and contents.
2558 does not produce an error if a tool specified in the value of 2806 does not produce an error if a tool specified in the value of
2559 ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can 2807 ``HOSTTOOLS_NONFATAL`` is not found on the build host. Thus, you can
2560 use ``HOSTTOOLS_NONFATAL`` to filter optional host tools. 2808 use ``HOSTTOOLS_NONFATAL`` to filter optional host tools.
2561 2809
2562 HOST_VENDOR 2810 HOST_VENDOR
2563 Specifies the name of the vendor. ``HOST_VENDOR`` is normally the 2811 Specifies the name of the vendor. ``HOST_VENDOR`` is normally the
2564 same as :term:`TARGET_VENDOR`. 2812 same as :term:`TARGET_VENDOR`.
2565 2813
2566 ICECC_DISABLED 2814 ICECC_DISABLED
2567 Disables or enables the ``icecc`` (Icecream) function. For more 2815 Disables or enables the ``icecc`` (Icecream) function. For more
2568 information on this function and best practices for using this 2816 information on this function and best practices for using this
2569 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`" 2817 variable, see the ":ref:`icecc.bbclass <ref-classes-icecc>`"
2570 section. 2818 section.
2571 2819
2572 Setting this variable to "1" in your ``local.conf`` disables the 2820 Setting this variable to "1" in your ``local.conf`` disables the
2573 function: ICECC_DISABLED ??= "1" To enable the function, set the 2821 function:
2574 variable as follows: ICECC_DISABLED = "" 2822 ::
2575 2823
2824 ICECC_DISABLED ??= "1"
2825
2826 To enable the function, set the variable as follows:
2827 ::
2828
2829 ICECC_DISABLED = ""
2830
2576 ICECC_ENV_EXEC 2831 ICECC_ENV_EXEC
2577 Points to the ``icecc-create-env`` script that you provide. This 2832 Points to the ``icecc-create-env`` script that you provide. This
2578 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You 2833 variable is used by the :ref:`icecc <ref-classes-icecc>` class. You
2579 set this variable in your ``local.conf`` file. 2834 set this variable in your ``local.conf`` file.
2580 2835
2581 If you do not point to a script that you provide, the OpenEmbedded 2836 If you do not point to a script that you provide, the OpenEmbedded
2582 build system uses the default script provided by the 2837 build system uses the default script provided by the
2583 ``icecc-create-env.bb`` recipe, which is a modified version and not 2838 ``icecc-create-env.bb`` recipe, which is a modified version and not
2584 the one that comes with ``icecc``. 2839 the one that comes with ``icecc``.
2585 2840
2586 ICECC_PARALLEL_MAKE 2841 ICECC_PARALLEL_MAKE
2587 Extra options passed to the ``make`` command during the 2842 Extra options passed to the ``make`` command during the
2588 :ref:`ref-tasks-compile` task that specify parallel 2843 :ref:`ref-tasks-compile` task that specify parallel
2589 compilation. This variable usually takes the form of "-j x", where x 2844 compilation. This variable usually takes the form of "-j x", where x
2590 represents the maximum number of parallel threads ``make`` can run. 2845 represents the maximum number of parallel threads ``make`` can run.
2591 2846
2592 .. note:: 2847 .. note::
2593 2848
2594 The options passed affect builds on all enabled machines on the 2849 The options passed affect builds on all enabled machines on the
2595 network, which are machines running the 2850 network, which are machines running the
2596 iceccd 2851 iceccd
2597 daemon. 2852 daemon.
2598 2853
2599 If your enabled machines support multiple cores, coming up with the 2854 If your enabled machines support multiple cores, coming up with the
2600 maximum number of parallel threads that gives you the best 2855 maximum number of parallel threads that gives you the best
2601 performance could take some experimentation since machine speed, 2856 performance could take some experimentation since machine speed,
@@ -2604,37 +2859,37 @@ system and gives an overview of their function and contents.
2604 :term:`PARALLEL_MAKE` variable, there is no 2859 :term:`PARALLEL_MAKE` variable, there is no
2605 rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal 2860 rule-of-thumb for setting ``ICECC_PARALLEL_MAKE`` to achieve optimal
2606 performance. 2861 performance.
2607 2862
2608 If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not 2863 If you do not set ``ICECC_PARALLEL_MAKE``, the build system does not
2609 use it (i.e. the system does not detect and assign the number of 2864 use it (i.e. the system does not detect and assign the number of
2610 cores as is done with ``PARALLEL_MAKE``). 2865 cores as is done with ``PARALLEL_MAKE``).
2611 2866
2612 ICECC_PATH 2867 ICECC_PATH
2613 The location of the ``icecc`` binary. You can set this variable in 2868 The location of the ``icecc`` binary. You can set this variable in
2614 your ``local.conf`` file. If your ``local.conf`` file does not define 2869 your ``local.conf`` file. If your ``local.conf`` file does not define
2615 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts 2870 this variable, the :ref:`icecc <ref-classes-icecc>` class attempts
2616 to define it by locating ``icecc`` using ``which``. 2871 to define it by locating ``icecc`` using ``which``.
2617 2872
2618 ICECC_USER_CLASS_BL 2873 ICECC_USER_CLASS_BL
2619 Identifies user classes that you do not want the Icecream distributed 2874 Identifies user classes that you do not want the Icecream distributed
2620 compile support to consider. This variable is used by the 2875 compile support to consider. This variable is used by the
2621 :ref:`icecc <ref-classes-icecc>` class. You set this variable in 2876 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2622 your ``local.conf`` file. 2877 your ``local.conf`` file.
2623 2878
2624 When you list classes using this variable, you are "blacklisting" 2879 When you list classes using this variable, you are "blacklisting"
2625 them from distributed compilation across remote hosts. Any classes 2880 them from distributed compilation across remote hosts. Any classes
2626 you list will be distributed and compiled locally. 2881 you list will be distributed and compiled locally.
2627 2882
2628 ICECC_USER_PACKAGE_BL 2883 ICECC_USER_PACKAGE_BL
2629 Identifies user recipes that you do not want the Icecream distributed 2884 Identifies user recipes that you do not want the Icecream distributed
2630 compile support to consider. This variable is used by the 2885 compile support to consider. This variable is used by the
2631 :ref:`icecc <ref-classes-icecc>` class. You set this variable in 2886 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2632 your ``local.conf`` file. 2887 your ``local.conf`` file.
2633 2888
2634 When you list packages using this variable, you are "blacklisting" 2889 When you list packages using this variable, you are "blacklisting"
2635 them from distributed compilation across remote hosts. Any packages 2890 them from distributed compilation across remote hosts. Any packages
2636 you list will be distributed and compiled locally. 2891 you list will be distributed and compiled locally.
2637 2892
2638 ICECC_USER_PACKAGE_WL 2893 ICECC_USER_PACKAGE_WL
2639 Identifies user recipes that use an empty 2894 Identifies user recipes that use an empty
2640 :term:`PARALLEL_MAKE` variable that you want to 2895 :term:`PARALLEL_MAKE` variable that you want to
@@ -2642,67 +2897,76 @@ system and gives an overview of their function and contents.
2642 distributed compile support. This variable is used by the 2897 distributed compile support. This variable is used by the
2643 :ref:`icecc <ref-classes-icecc>` class. You set this variable in 2898 :ref:`icecc <ref-classes-icecc>` class. You set this variable in
2644 your ``local.conf`` file. 2899 your ``local.conf`` file.
2645 2900
2646 IMAGE_BASENAME 2901 IMAGE_BASENAME
2647 The base name of image output files. This variable defaults to the 2902 The base name of image output files. This variable defaults to the
2648 recipe name (``${``\ :term:`PN`\ ``}``). 2903 recipe name (``${``\ :term:`PN`\ ``}``).
2649 2904
2650 IMAGE_BOOT_FILES 2905 IMAGE_BOOT_FILES
2651 A space-separated list of files installed into the boot partition 2906 A space-separated list of files installed into the boot partition
2652 when preparing an image using the Wic tool with the 2907 when preparing an image using the Wic tool with the
2653 ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default, 2908 ``bootimg-partition`` or ``bootimg-efi`` source plugin. By default,
2654 the files are 2909 the files are
2655 installed under the same name as the source files. To change the 2910 installed under the same name as the source files. To change the
2656 installed name, separate it from the original name with a semi-colon 2911 installed name, separate it from the original name with a semi-colon
2657 (;). Source files need to be located in 2912 (;). Source files need to be located in
2658 :term:`DEPLOY_DIR_IMAGE`. Here are two 2913 :term:`DEPLOY_DIR_IMAGE`. Here are two
2659 examples: IMAGE_BOOT_FILES = "u-boot.img uImage;kernel" 2914 examples:
2660 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}" 2915 ::
2661 2916
2917 IMAGE_BOOT_FILES = "u-boot.img uImage;kernel"
2918 IMAGE_BOOT_FILES = "u-boot.${UBOOT_SUFFIX} ${KERNEL_IMAGETYPE}"
2919
2662 Alternatively, source files can be picked up using a glob pattern. In 2920 Alternatively, source files can be picked up using a glob pattern. In
2663 this case, the destination file must have the same name as the base 2921 this case, the destination file must have the same name as the base
2664 name of the source file path. To install files into a directory 2922 name of the source file path. To install files into a directory
2665 within the target location, pass its name after a semi-colon (;). 2923 within the target location, pass its name after a semi-colon (;).
2666 Here are two examples: IMAGE_BOOT_FILES = "bcm2835-bootfiles/*" 2924 Here are two examples:
2667 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/" The first example 2925 ::
2926
2927 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*"
2928 IMAGE_BOOT_FILES = "bcm2835-bootfiles/*;boot/"
2929
2930 The first example
2668 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles`` 2931 installs all files from ``${DEPLOY_DIR_IMAGE}/bcm2835-bootfiles``
2669 into the root of the target partition. The second example installs 2932 into the root of the target partition. The second example installs
2670 the same files into a ``boot`` directory within the target partition. 2933 the same files into a ``boot`` directory within the target partition.
2671 2934
2672 You can find information on how to use the Wic tool in the "`Creating 2935 You can find information on how to use the Wic tool in the
2673 Partitioned Images Using 2936 ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`"
2674 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__"
2675 section of the Yocto Project Development Tasks Manual. Reference 2937 section of the Yocto Project Development Tasks Manual. Reference
2676 material for Wic is located in the "`OpenEmbedded Kickstart (.wks) 2938 material for Wic is located in the
2677 Reference <&YOCTO_DOCS_REF_URL;#ref-kickstart>`__" chapter. 2939 ":doc:`../ref-manual/ref-kickstart`" chapter.
2678 2940
2679 IMAGE_CLASSES 2941 IMAGE_CLASSES
2680 A list of classes that all images should inherit. You typically use 2942 A list of classes that all images should inherit. You typically use
2681 this variable to specify the list of classes that register the 2943 this variable to specify the list of classes that register the
2682 different types of images the OpenEmbedded build system creates. 2944 different types of images the OpenEmbedded build system creates.
2683 2945
2684 The default value for ``IMAGE_CLASSES`` is ``image_types``. You can 2946 The default value for ``IMAGE_CLASSES`` is ``image_types``. You can
2685 set this variable in your ``local.conf`` or in a distribution 2947 set this variable in your ``local.conf`` or in a distribution
2686 configuration file. 2948 configuration file.
2687 2949
2688 For more information, see ``meta/classes/image_types.bbclass`` in the 2950 For more information, see ``meta/classes/image_types.bbclass`` in the
2689 :term:`Source Directory`. 2951 :term:`Source Directory`.
2690 2952
2691 IMAGE_CMD 2953 IMAGE_CMD
2692 Specifies the command to create the image file for a specific image 2954 Specifies the command to create the image file for a specific image
2693 type, which corresponds to the value set set in 2955 type, which corresponds to the value set set in
2694 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``, 2956 :term:`IMAGE_FSTYPES`, (e.g. ``ext3``,
2695 ``btrfs``, and so forth). When setting this variable, you should use 2957 ``btrfs``, and so forth). When setting this variable, you should use
2696 an override for the associated type. Here is an example: 2958 an override for the associated type. Here is an example:
2697 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \\ --faketime 2959 ::
2698 --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \\ 2960
2699 ${EXTRA_IMAGECMD}" 2961 IMAGE_CMD_jffs2 = "mkfs.jffs2 --root=${IMAGE_ROOTFS} \
2700 2962 --faketime --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
2963 ${EXTRA_IMAGECMD}"
2964
2701 You typically do not need to set this variable unless you are adding 2965 You typically do not need to set this variable unless you are adding
2702 support for a new image type. For more examples on how to set this 2966 support for a new image type. For more examples on how to set this
2703 variable, see the :ref:`image_types <ref-classes-image_types>` 2967 variable, see the :ref:`image_types <ref-classes-image_types>`
2704 class file, which is ``meta/classes/image_types.bbclass``. 2968 class file, which is ``meta/classes/image_types.bbclass``.
2705 2969
2706 IMAGE_DEVICE_TABLES 2970 IMAGE_DEVICE_TABLES
2707 Specifies one or more files that contain custom device tables that 2971 Specifies one or more files that contain custom device tables that
2708 are passed to the ``makedevs`` command as part of creating an image. 2972 are passed to the ``makedevs`` command as part of creating an image.
@@ -2712,55 +2976,55 @@ system and gives an overview of their function and contents.
2712 :term:`BBPATH`. For details on how you should write 2976 :term:`BBPATH`. For details on how you should write
2713 device table files, see ``meta/files/device_table-minimal.txt`` as an 2977 device table files, see ``meta/files/device_table-minimal.txt`` as an
2714 example. 2978 example.
2715 2979
2716 IMAGE_FEATURES 2980 IMAGE_FEATURES
2717 The primary list of features to include in an image. Typically, you 2981 The primary list of features to include in an image. Typically, you
2718 configure this variable in an image recipe. Although you can use this 2982 configure this variable in an image recipe. Although you can use this
2719 variable from your ``local.conf`` file, which is found in the 2983 variable from your ``local.conf`` file, which is found in the
2720 :term:`Build Directory`, best practices dictate that you do 2984 :term:`Build Directory`, best practices dictate that you do
2721 not. 2985 not.
2722 2986
2723 .. note:: 2987 .. note::
2724 2988
2725 To enable extra features from outside the image recipe, use the 2989 To enable extra features from outside the image recipe, use the
2726 EXTRA_IMAGE_FEATURES 2990 EXTRA_IMAGE_FEATURES
2727 variable. 2991 variable.
2728 2992
2729 For a list of image features that ships with the Yocto Project, see 2993 For a list of image features that ships with the Yocto Project, see
2730 the "`Image Features <#ref-features-image>`__" section. 2994 the "`Image Features <#ref-features-image>`__" section.
2731 2995
2732 For an example that shows how to customize your image by using this 2996 For an example that shows how to customize your image by using this
2733 variable, see the "`Customizing Images Using Custom 2997 variable, see the ":ref:`usingpoky-extend-customimage-imagefeatures`"
2734 ``IMAGE_FEATURES`` and
2735 ``EXTRA_IMAGE_FEATURES`` <&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures>`__"
2736 section in the Yocto Project Development Tasks Manual. 2998 section in the Yocto Project Development Tasks Manual.
2737 2999
2738 IMAGE_FSTYPES 3000 IMAGE_FSTYPES
2739 Specifies the formats the OpenEmbedded build system uses during the 3001 Specifies the formats the OpenEmbedded build system uses during the
2740 build when creating the root filesystem. For example, setting 3002 build when creating the root filesystem. For example, setting
2741 ``IMAGE_FSTYPES`` as follows causes the build system to create root 3003 ``IMAGE_FSTYPES`` as follows causes the build system to create root
2742 filesystems using two formats: ``.ext3`` and ``.tar.bz2``: 3004 filesystems using two formats: ``.ext3`` and ``.tar.bz2``:
2743 IMAGE_FSTYPES = "ext3 tar.bz2" 3005 ::
2744 3006
3007 IMAGE_FSTYPES = "ext3 tar.bz2"
3008
2745 For the complete list of supported image formats from which you can 3009 For the complete list of supported image formats from which you can
2746 choose, see :term:`IMAGE_TYPES`. 3010 choose, see :term:`IMAGE_TYPES`.
2747 3011
2748 .. note:: 3012 .. note::
2749 3013
2750 - If an image recipe uses the "inherit image" line and you are 3014 - If an image recipe uses the "inherit image" line and you are
2751 setting ``IMAGE_FSTYPES`` inside the recipe, you must set 3015 setting ``IMAGE_FSTYPES`` inside the recipe, you must set
2752 ``IMAGE_FSTYPES`` prior to using the "inherit image" line. 3016 ``IMAGE_FSTYPES`` prior to using the "inherit image" line.
2753 3017
2754 - Due to the way the OpenEmbedded build system processes this 3018 - Due to the way the OpenEmbedded build system processes this
2755 variable, you cannot update its contents by using ``_append`` 3019 variable, you cannot update its contents by using ``_append``
2756 or ``_prepend``. You must use the ``+=`` operator to add one or 3020 or ``_prepend``. You must use the ``+=`` operator to add one or
2757 more options to the ``IMAGE_FSTYPES`` variable. 3021 more options to the ``IMAGE_FSTYPES`` variable.
2758 3022
2759 IMAGE_INSTALL 3023 IMAGE_INSTALL
2760 Used by recipes to specify the packages to install into an image 3024 Used by recipes to specify the packages to install into an image
2761 through the :ref:`image <ref-classes-image>` class. Use the 3025 through the :ref:`image <ref-classes-image>` class. Use the
2762 ``IMAGE_INSTALL`` variable with care to avoid ordering issues. 3026 ``IMAGE_INSTALL`` variable with care to avoid ordering issues.
2763 3027
2764 Image recipes set ``IMAGE_INSTALL`` to specify the packages to 3028 Image recipes set ``IMAGE_INSTALL`` to specify the packages to
2765 install into an image through ``image.bbclass``. Additionally, 3029 install into an image through ``image.bbclass``. Additionally,
2766 "helper" classes such as the 3030 "helper" classes such as the
@@ -2768,14 +3032,18 @@ system and gives an overview of their function and contents.
2768 take lists used with ``IMAGE_FEATURES`` and turn them into 3032 take lists used with ``IMAGE_FEATURES`` and turn them into
2769 auto-generated entries in ``IMAGE_INSTALL`` in addition to its 3033 auto-generated entries in ``IMAGE_INSTALL`` in addition to its
2770 default contents. 3034 default contents.
2771 3035
2772 When you use this variable, it is best to use it as follows: 3036 When you use this variable, it is best to use it as follows:
2773 IMAGE_INSTALL_append = " package-name" Be sure to include the space 3037 ::
3038
3039 IMAGE_INSTALL_append = " package-name"
3040
3041 Be sure to include the space
2774 between the quotation character and the start of the package name or 3042 between the quotation character and the start of the package name or
2775 names. 3043 names.
2776 3044
2777 .. note:: 3045 .. note::
2778 3046
2779 - When working with a 3047 - When working with a
2780 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ 3048 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__
2781 image, do not use the ``IMAGE_INSTALL`` variable to specify 3049 image, do not use the ``IMAGE_INSTALL`` variable to specify
@@ -2783,11 +3051,10 @@ system and gives an overview of their function and contents.
2783 :term:`PACKAGE_INSTALL` variable, which 3051 :term:`PACKAGE_INSTALL` variable, which
2784 allows the initial RAM filesystem (initramfs) recipe to use a 3052 allows the initial RAM filesystem (initramfs) recipe to use a
2785 fixed set of packages and not be affected by ``IMAGE_INSTALL``. 3053 fixed set of packages and not be affected by ``IMAGE_INSTALL``.
2786 For information on creating an initramfs, see the "`Building an 3054 For information on creating an initramfs, see the
2787 Initial RAM Filesystem (initramfs) 3055 ":ref:`building-an-initramfs-image`"
2788 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__"
2789 section in the Yocto Project Development Tasks Manual. 3056 section in the Yocto Project Development Tasks Manual.
2790 3057
2791 - Using ``IMAGE_INSTALL`` with the 3058 - Using ``IMAGE_INSTALL`` with the
2792 :ref:`+= <bitbake:appending-and-prepending>` 3059 :ref:`+= <bitbake:appending-and-prepending>`
2793 BitBake operator within the ``/conf/local.conf`` file or from 3060 BitBake operator within the ``/conf/local.conf`` file or from
@@ -2802,7 +3069,7 @@ system and gives an overview of their function and contents.
2802 within an image recipe may or may not succeed depending on the 3069 within an image recipe may or may not succeed depending on the
2803 specific situation. In both these cases, the behavior is 3070 specific situation. In both these cases, the behavior is
2804 contrary to how most users expect the ``+=`` operator to work. 3071 contrary to how most users expect the ``+=`` operator to work.
2805 3072
2806 IMAGE_LINGUAS 3073 IMAGE_LINGUAS
2807 Specifies the list of locales to install into the image during the 3074 Specifies the list of locales to install into the image during the
2808 root filesystem construction process. The OpenEmbedded build system 3075 root filesystem construction process. The OpenEmbedded build system
@@ -2810,39 +3077,50 @@ system and gives an overview of their function and contents.
2810 into separate packages. Setting the ``IMAGE_LINGUAS`` variable 3077 into separate packages. Setting the ``IMAGE_LINGUAS`` variable
2811 ensures that any locale packages that correspond to packages already 3078 ensures that any locale packages that correspond to packages already
2812 selected for installation into the image are also installed. Here is 3079 selected for installation into the image are also installed. Here is
2813 an example: IMAGE_LINGUAS = "pt-br de-de" 3080 an example:
2814 3081 ::
3082
3083 IMAGE_LINGUAS = "pt-br de-de"
3084
2815 In this example, the build system ensures any Brazilian Portuguese 3085 In this example, the build system ensures any Brazilian Portuguese
2816 and German locale files that correspond to packages in the image are 3086 and German locale files that correspond to packages in the image are
2817 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as 3087 installed (i.e. ``*-locale-pt-br`` and ``*-locale-de-de`` as well as
2818 ``*-locale-pt`` and ``*-locale-de``, since some software packages 3088 ``*-locale-pt`` and ``*-locale-de``, since some software packages
2819 only provide locale files by language and not by country-specific 3089 only provide locale files by language and not by country-specific
2820 language). 3090 language).
2821 3091
2822 See the :term:`GLIBC_GENERATE_LOCALES` 3092 See the :term:`GLIBC_GENERATE_LOCALES`
2823 variable for information on generating GLIBC locales. 3093 variable for information on generating GLIBC locales.
2824 3094
2825 IMAGE_MANIFEST 3095 IMAGE_MANIFEST
2826 The manifest file for the image. This file lists all the installed 3096 The manifest file for the image. This file lists all the installed
2827 packages that make up the image. The file contains package 3097 packages that make up the image. The file contains package
2828 information on a line-per-package basis as follows: packagename 3098 information on a line-per-package basis as follows:
2829 packagearch version 3099 ::
2830 3100
3101 packagename packagearch version
3102
2831 The :ref:`image <ref-classes-image>` class defines the manifest 3103 The :ref:`image <ref-classes-image>` class defines the manifest
2832 file as follows: IMAGE_MANIFEST = 3104 file as follows:
2833 "${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest" The location is 3105 ::
3106
3107 IMAGE_MANIFEST ="${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.manifest"
3108
3109 The location is
2834 derived using the :term:`DEPLOY_DIR_IMAGE` 3110 derived using the :term:`DEPLOY_DIR_IMAGE`
2835 and :term:`IMAGE_NAME` variables. You can find 3111 and :term:`IMAGE_NAME` variables. You can find
2836 information on how the image is created in the "`Image 3112 information on how the image is created in the ":ref:`image-generation-dev-environment`"
2837 Generation <&YOCTO_DOCS_OM_URL;#image-generation-dev-environment>`__"
2838 section in the Yocto Project Overview and Concepts Manual. 3113 section in the Yocto Project Overview and Concepts Manual.
2839 3114
2840 IMAGE_NAME 3115 IMAGE_NAME
2841 The name of the output image files minus the extension. This variable 3116 The name of the output image files minus the extension. This variable
2842 is derived using the :term:`IMAGE_BASENAME`, 3117 is derived using the :term:`IMAGE_BASENAME`,
2843 :term:`MACHINE`, and :term:`DATETIME` 3118 :term:`MACHINE`, and :term:`DATETIME`
2844 variables: IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}" 3119 variables:
2845 3120 ::
3121
3122 IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
3123
2846 IMAGE_OVERHEAD_FACTOR 3124 IMAGE_OVERHEAD_FACTOR
2847 Defines a multiplier that the build system applies to the initial 3125 Defines a multiplier that the build system applies to the initial
2848 image size for cases when the multiplier times the returned disk 3126 image size for cases when the multiplier times the returned disk
@@ -2858,18 +3136,20 @@ system and gives an overview of their function and contents.
2858 not produce an image with all the theoretical free disk space. See 3136 not produce an image with all the theoretical free disk space. See
2859 ``IMAGE_ROOTFS_SIZE`` for information on how the build system 3137 ``IMAGE_ROOTFS_SIZE`` for information on how the build system
2860 determines the overall image size. 3138 determines the overall image size.
2861 3139
2862 The default 30% free disk space typically gives the image enough room 3140 The default 30% free disk space typically gives the image enough room
2863 to boot and allows for basic post installs while still leaving a 3141 to boot and allows for basic post installs while still leaving a
2864 small amount of free disk space. If 30% free space is inadequate, you 3142 small amount of free disk space. If 30% free space is inadequate, you
2865 can increase the default value. For example, the following setting 3143 can increase the default value. For example, the following setting
2866 gives you 50% free space added to the image: IMAGE_OVERHEAD_FACTOR = 3144 gives you 50% free space added to the image:
2867 "1.5" 3145 ::
2868 3146
3147 IMAGE_OVERHEAD_FACTOR = "1.5"
3148
2869 Alternatively, you can ensure a specific amount of free disk space is 3149 Alternatively, you can ensure a specific amount of free disk space is
2870 added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE`` 3150 added to the image by using the ``IMAGE_ROOTFS_EXTRA_SPACE``
2871 variable. 3151 variable.
2872 3152
2873 IMAGE_PKGTYPE 3153 IMAGE_PKGTYPE
2874 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the 3154 Defines the package type (i.e. DEB, RPM, IPK, or TAR) used by the
2875 OpenEmbedded build system. The variable is defined appropriately by 3155 OpenEmbedded build system. The variable is defined appropriately by
@@ -2877,84 +3157,92 @@ system and gives an overview of their function and contents.
2877 :ref:`package_rpm <ref-classes-package_rpm>`, 3157 :ref:`package_rpm <ref-classes-package_rpm>`,
2878 :ref:`package_ipk <ref-classes-package_ipk>`, or 3158 :ref:`package_ipk <ref-classes-package_ipk>`, or
2879 :ref:`package_tar <ref-classes-package_tar>` class. 3159 :ref:`package_tar <ref-classes-package_tar>` class.
2880 3160
2881 .. note:: 3161 .. note::
2882 3162
2883 The 3163 The
2884 package_tar 3164 package_tar
2885 class is broken and is not supported. It is recommended that you 3165 class is broken and is not supported. It is recommended that you
2886 do not use it. 3166 do not use it.
2887 3167
2888 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and 3168 The :ref:`populate_sdk_* <ref-classes-populate-sdk-*>` and
2889 :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE`` 3169 :ref:`image <ref-classes-image>` classes use the ``IMAGE_PKGTYPE``
2890 for packaging up images and SDKs. 3170 for packaging up images and SDKs.
2891 3171
2892 You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the 3172 You should not set the ``IMAGE_PKGTYPE`` manually. Rather, the
2893 variable is set indirectly through the appropriate 3173 variable is set indirectly through the appropriate
2894 :ref:`package_* <ref-classes-package>` class using the 3174 :ref:`package_* <ref-classes-package>` class using the
2895 :term:`PACKAGE_CLASSES` variable. The 3175 :term:`PACKAGE_CLASSES` variable. The
2896 OpenEmbedded build system uses the first package type (e.g. DEB, RPM, 3176 OpenEmbedded build system uses the first package type (e.g. DEB, RPM,
2897 or IPK) that appears with the variable 3177 or IPK) that appears with the variable
2898 3178
2899 .. note:: 3179 .. note::
2900 3180
2901 Files using the 3181 Files using the
2902 .tar 3182 .tar
2903 format are never used as a substitute packaging format for DEB, 3183 format are never used as a substitute packaging format for DEB,
2904 RPM, and IPK formatted files for your image or SDK. 3184 RPM, and IPK formatted files for your image or SDK.
2905 3185
2906 IMAGE_POSTPROCESS_COMMAND 3186 IMAGE_POSTPROCESS_COMMAND
2907 Specifies a list of functions to call once the OpenEmbedded build 3187 Specifies a list of functions to call once the OpenEmbedded build
2908 system creates the final image output files. You can specify 3188 system creates the final image output files. You can specify
2909 functions separated by semicolons: IMAGE_POSTPROCESS_COMMAND += 3189 functions separated by semicolons:
2910 "function; ... " 3190 ::
2911 3191
3192 IMAGE_POSTPROCESS_COMMAND += "function; ... "
3193
2912 If you need to pass the root filesystem path to a command within the 3194 If you need to pass the root filesystem path to a command within the
2913 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3195 function, you can use ``${IMAGE_ROOTFS}``, which points to the
2914 directory that becomes the root filesystem image. See the 3196 directory that becomes the root filesystem image. See the
2915 :term:`IMAGE_ROOTFS` variable for more 3197 :term:`IMAGE_ROOTFS` variable for more
2916 information. 3198 information.
2917 3199
2918 IMAGE_PREPROCESS_COMMAND 3200 IMAGE_PREPROCESS_COMMAND
2919 Specifies a list of functions to call before the OpenEmbedded build 3201 Specifies a list of functions to call before the OpenEmbedded build
2920 system creates the final image output files. You can specify 3202 system creates the final image output files. You can specify
2921 functions separated by semicolons: IMAGE_PREPROCESS_COMMAND += 3203 functions separated by semicolons:
2922 "function; ... " 3204 ::
2923 3205
3206 IMAGE_PREPROCESS_COMMAND += "function; ... "
3207
2924 If you need to pass the root filesystem path to a command within the 3208 If you need to pass the root filesystem path to a command within the
2925 function, you can use ``${IMAGE_ROOTFS}``, which points to the 3209 function, you can use ``${IMAGE_ROOTFS}``, which points to the
2926 directory that becomes the root filesystem image. See the 3210 directory that becomes the root filesystem image. See the
2927 :term:`IMAGE_ROOTFS` variable for more 3211 :term:`IMAGE_ROOTFS` variable for more
2928 information. 3212 information.
2929 3213
2930 IMAGE_ROOTFS 3214 IMAGE_ROOTFS
2931 The location of the root filesystem while it is under construction 3215 The location of the root filesystem while it is under construction
2932 (i.e. during the :ref:`ref-tasks-rootfs` task). This 3216 (i.e. during the :ref:`ref-tasks-rootfs` task). This
2933 variable is not configurable. Do not change it. 3217 variable is not configurable. Do not change it.
2934 3218
2935 IMAGE_ROOTFS_ALIGNMENT 3219 IMAGE_ROOTFS_ALIGNMENT
2936 Specifies the alignment for the output image file in Kbytes. If the 3220 Specifies the alignment for the output image file in Kbytes. If the
2937 size of the image is not a multiple of this value, then the size is 3221 size of the image is not a multiple of this value, then the size is
2938 rounded up to the nearest multiple of the value. The default value is 3222 rounded up to the nearest multiple of the value. The default value is
2939 "1". See :term:`IMAGE_ROOTFS_SIZE` for 3223 "1". See :term:`IMAGE_ROOTFS_SIZE` for
2940 additional information. 3224 additional information.
2941 3225
2942 IMAGE_ROOTFS_EXTRA_SPACE 3226 IMAGE_ROOTFS_EXTRA_SPACE
2943 Defines additional free disk space created in the image in Kbytes. By 3227 Defines additional free disk space created in the image in Kbytes. By
2944 default, this variable is set to "0". This free disk space is added 3228 default, this variable is set to "0". This free disk space is added
2945 to the image after the build system determines the image size as 3229 to the image after the build system determines the image size as
2946 described in ``IMAGE_ROOTFS_SIZE``. 3230 described in ``IMAGE_ROOTFS_SIZE``.
2947 3231
2948 This variable is particularly useful when you want to ensure that a 3232 This variable is particularly useful when you want to ensure that a
2949 specific amount of free disk space is available on a device after an 3233 specific amount of free disk space is available on a device after an
2950 image is installed and running. For example, to be sure 5 Gbytes of 3234 image is installed and running. For example, to be sure 5 Gbytes of
2951 free disk space is available, set the variable as follows: 3235 free disk space is available, set the variable as follows:
2952 IMAGE_ROOTFS_EXTRA_SPACE = "5242880" 3236 ::
2953 3237
3238 IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
3239
2954 For example, the Yocto Project Build Appliance specifically requests 3240 For example, the Yocto Project Build Appliance specifically requests
2955 40 Gbytes of extra space with the line: IMAGE_ROOTFS_EXTRA_SPACE = 3241 40 Gbytes of extra space with the line:
2956 "41943040" 3242 ::
2957 3243
3244 IMAGE_ROOTFS_EXTRA_SPACE = "41943040"
3245
2958 IMAGE_ROOTFS_SIZE 3246 IMAGE_ROOTFS_SIZE
2959 Defines the size in Kbytes for the generated image. The OpenEmbedded 3247 Defines the size in Kbytes for the generated image. The OpenEmbedded
2960 build system determines the final size for the generated image using 3248 build system determines the final size for the generated image using
@@ -2962,45 +3250,87 @@ system and gives an overview of their function and contents.
2962 the generated image, a requested size for the image, and requested 3250 the generated image, a requested size for the image, and requested
2963 additional free disk space to be added to the image. Programatically, 3251 additional free disk space to be added to the image. Programatically,
2964 the build system determines the final size of the generated image as 3252 the build system determines the final size of the generated image as
2965 follows: if (image-du \* overhead) < rootfs-size: 3253 follows:
2966 internal-rootfs-size = rootfs-size + xspace else: 3254 ::
2967 internal-rootfs-size = (image-du \* overhead) + xspace where: 3255
2968 image-du = Returned value of the du command on the image. overhead = 3256 if (image-du * overhead) < rootfs-size:
2969 IMAGE_OVERHEAD_FACTOR rootfs-size = IMAGE_ROOTFS_SIZE 3257 internal-rootfs-size = rootfs-size + xspace
2970 internal-rootfs-size = Initial root filesystem size before any 3258 else:
2971 modifications. xspace = IMAGE_ROOTFS_EXTRA_SPACE 3259 internal-rootfs-size = (image-du * overhead) + xspace
2972 3260 where:
3261 image-du = Returned value of the du command on the image.
3262 overhead = IMAGE_OVERHEAD_FACTOR
3263 rootfs-size = IMAGE_ROOTFS_SIZE
3264 internal-rootfs-size = Initial root filesystem size before any modifications.
3265 xspace = IMAGE_ROOTFS_EXTRA_SPACE
3266
2973 See the :term:`IMAGE_OVERHEAD_FACTOR` 3267 See the :term:`IMAGE_OVERHEAD_FACTOR`
2974 and :term:`IMAGE_ROOTFS_EXTRA_SPACE` 3268 and :term:`IMAGE_ROOTFS_EXTRA_SPACE`
2975 variables for related information. 3269 variables for related information.
2976 3270
2977 IMAGE_TYPEDEP 3271 IMAGE_TYPEDEP
2978 Specifies a dependency from one image type on another. Here is an 3272 Specifies a dependency from one image type on another. Here is an
2979 example from the :ref:`image-live <ref-classes-image-live>` class: 3273 example from the :ref:`image-live <ref-classes-image-live>` class:
2980 IMAGE_TYPEDEP_live = "ext3" 3274 ::
2981 3275
3276 IMAGE_TYPEDEP_live = "ext3"
3277
2982 In the previous example, the variable ensures that when "live" is 3278 In the previous example, the variable ensures that when "live" is
2983 listed with the :term:`IMAGE_FSTYPES` variable, 3279 listed with the :term:`IMAGE_FSTYPES` variable,
2984 the OpenEmbedded build system produces an ``ext3`` image first since 3280 the OpenEmbedded build system produces an ``ext3`` image first since
2985 one of the components of the live image is an ``ext3`` formatted 3281 one of the components of the live image is an ``ext3`` formatted
2986 partition containing the root filesystem. 3282 partition containing the root filesystem.
2987 3283
2988 IMAGE_TYPES 3284 IMAGE_TYPES
2989 Specifies the complete list of supported image types by default: 3285 Specifies the complete list of supported image types by default:
2990 btrfs container cpio cpio.gz cpio.lz4 cpio.lzma cpio.xz cramfs ext2 3286
2991 ext2.bz2 ext2.gz ext2.lzma ext3 ext3.gz ext4 ext4.gz f2fs hddimg iso 3287 - btrfs
2992 jffs2 jffs2.sum multiubi squashfs squashfs-lz4 squashfs-lzo 3288 - container
2993 squashfs-xz tar tar.bz2 tar.gz tar.lz4 tar.xz tar.zst ubi ubifs wic 3289 - cpio
2994 wic.bz2 wic.gz wic.lzma 3290 - cpio.gz
2995 3291 - cpio.lz4
3292 - cpio.lzma
3293 - cpio.xz
3294 - cramfs
3295 - ext2
3296 - ext2.bz2
3297 - ext2.gz
3298 - ext2.lzma
3299 - ext3
3300 - ext3.gz
3301 - ext4
3302 - ext4.gz
3303 - f2fs
3304 - hddimg
3305 - iso
3306 - jffs2
3307 - jffs2.sum
3308 - multiubi
3309 - squashfs
3310 - squashfs-lz4
3311 - squashfs-lzo
3312 - squashfs-xz
3313 - tar
3314 - tar.bz2
3315 - tar.gz
3316 - tar.lz4
3317 - tar.xz
3318 - tar.zst
3319 - ubi
3320 - ubifs
3321 - wic
3322 - wic.bz2
3323 - wic.gz
3324 - wic.lzma
3325
2996 For more information about these types of images, see 3326 For more information about these types of images, see
2997 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`. 3327 ``meta/classes/image_types*.bbclass`` in the :term:`Source Directory`.
2998 3328
2999 INC_PR 3329 INC_PR
3000 Helps define the recipe revision for recipes that share a common 3330 Helps define the recipe revision for recipes that share a common
3001 ``include`` file. You can think of this variable as part of the 3331 ``include`` file. You can think of this variable as part of the
3002 recipe revision as set from within an include file. 3332 recipe revision as set from within an include file.
3003 3333
3004 Suppose, for example, you have a set of recipes that are used across 3334 Suppose, for example, you have a set of recipes that are used across
3005 several projects. And, within each of those recipes the revision (its 3335 several projects. And, within each of those recipes the revision (its
3006 :term:`PR` value) is set accordingly. In this case, when 3336 :term:`PR` value) is set accordingly. In this case, when
@@ -3009,49 +3339,53 @@ system and gives an overview of their function and contents.
3009 updated version of the recipe. In this scenario, it can get 3339 updated version of the recipe. In this scenario, it can get
3010 complicated when recipes that are used in many places and provide 3340 complicated when recipes that are used in many places and provide
3011 common functionality are upgraded to a new revision. 3341 common functionality are upgraded to a new revision.
3012 3342
3013 A more efficient way of dealing with this situation is to set the 3343 A more efficient way of dealing with this situation is to set the
3014 ``INC_PR`` variable inside the ``include`` files that the recipes 3344 ``INC_PR`` variable inside the ``include`` files that the recipes
3015 share and then expand the ``INC_PR`` variable within the recipes to 3345 share and then expand the ``INC_PR`` variable within the recipes to
3016 help define the recipe revision. 3346 help define the recipe revision.
3017 3347
3018 The following provides an example that shows how to use the 3348 The following provides an example that shows how to use the
3019 ``INC_PR`` variable given a common ``include`` file that defines the 3349 ``INC_PR`` variable given a common ``include`` file that defines the
3020 variable. Once the variable is defined in the ``include`` file, you 3350 variable. Once the variable is defined in the ``include`` file, you
3021 can use the variable to set the ``PR`` values in each recipe. You 3351 can use the variable to set the ``PR`` values in each recipe. You
3022 will notice that when you set a recipe's ``PR`` you can provide more 3352 will notice that when you set a recipe's ``PR`` you can provide more
3023 granular revisioning by appending values to the ``INC_PR`` variable: 3353 granular revisioning by appending values to the ``INC_PR`` variable:
3024 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2" 3354 ::
3025 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1" 3355
3026 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0" 3356 recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
3027 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" The 3357 recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
3358 recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
3359 recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
3360
3361 The
3028 first line of the example establishes the baseline revision to be 3362 first line of the example establishes the baseline revision to be
3029 used for all recipes that use the ``include`` file. The remaining 3363 used for all recipes that use the ``include`` file. The remaining
3030 lines in the example are from individual recipes and show how the 3364 lines in the example are from individual recipes and show how the
3031 ``PR`` value is set. 3365 ``PR`` value is set.
3032 3366
3033 INCOMPATIBLE_LICENSE 3367 INCOMPATIBLE_LICENSE
3034 Specifies a space-separated list of license names (as they would 3368 Specifies a space-separated list of license names (as they would
3035 appear in :term:`LICENSE`) that should be excluded 3369 appear in :term:`LICENSE`) that should be excluded
3036 from the build. Recipes that provide no alternatives to listed 3370 from the build. Recipes that provide no alternatives to listed
3037 incompatible licenses are not built. Packages that are individually 3371 incompatible licenses are not built. Packages that are individually
3038 licensed with the specified incompatible licenses will be deleted. 3372 licensed with the specified incompatible licenses will be deleted.
3039 3373
3040 .. note:: 3374 .. note::
3041 3375
3042 This functionality is only regularly tested using the following 3376 This functionality is only regularly tested using the following
3043 setting: 3377 setting:
3044 :: 3378 ::
3045 3379
3046 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0" 3380 INCOMPATIBLE_LICENSE = "GPL-3.0 LGPL-3.0 AGPL-3.0"
3047 3381
3048 3382
3049 Although you can use other settings, you might be required to 3383 Although you can use other settings, you might be required to
3050 remove dependencies on or provide alternatives to components that 3384 remove dependencies on or provide alternatives to components that
3051 are required to produce a functional system image. 3385 are required to produce a functional system image.
3052 3386
3053 .. note:: 3387 .. note::
3054 3388
3055 It is possible to define a list of licenses that are allowed to be 3389 It is possible to define a list of licenses that are allowed to be
3056 used instead of the licenses that are excluded. To do this, define 3390 used instead of the licenses that are excluded. To do this, define
3057 a variable 3391 a variable
@@ -3060,10 +3394,10 @@ system and gives an overview of their function and contents.
3060 INCOMPATIBLE_LICENSE 3394 INCOMPATIBLE_LICENSE
3061 as: 3395 as:
3062 :: 3396 ::
3063 3397
3064 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}" 3398 INCOMPATIBLE_LICENSE = "${@' '.join(sorted(set(d.getVar('AVAILABLE_LICENSES').split()) - set(d.getVar('COMPATIBLE_LICENSES').split())))}"
3065 3399
3066 3400
3067 This will result in 3401 This will result in
3068 INCOMPATIBLE_LICENSE 3402 INCOMPATIBLE_LICENSE
3069 containing the names of all licences from 3403 containing the names of all licences from
@@ -3071,34 +3405,36 @@ system and gives an overview of their function and contents.
3071 except the ones specified in 3405 except the ones specified in
3072 COMPATIBLE_LICENSES 3406 COMPATIBLE_LICENSES
3073 , thus only allowing the latter licences to be used. 3407 , thus only allowing the latter licences to be used.
3074 3408
3075 INHERIT 3409 INHERIT
3076 Causes the named class or classes to be inherited globally. Anonymous 3410 Causes the named class or classes to be inherited globally. Anonymous
3077 functions in the class or classes are not executed for the base 3411 functions in the class or classes are not executed for the base
3078 configuration and in each individual recipe. The OpenEmbedded build 3412 configuration and in each individual recipe. The OpenEmbedded build
3079 system ignores changes to ``INHERIT`` in individual recipes. 3413 system ignores changes to ``INHERIT`` in individual recipes.
3080 3414
3081 For more information on ``INHERIT``, see the 3415 For more information on ``INHERIT``, see the
3082 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`" 3416 :ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:\`\`inherit\`\` configuration directive`"
3083 section in the Bitbake User Manual. 3417 section in the Bitbake User Manual.
3084 3418
3085 INHERIT_DISTRO 3419 INHERIT_DISTRO
3086 Lists classes that will be inherited at the distribution level. It is 3420 Lists classes that will be inherited at the distribution level. It is
3087 unlikely that you want to edit this variable. 3421 unlikely that you want to edit this variable.
3088 3422
3089 The default value of the variable is set as follows in the 3423 The default value of the variable is set as follows in the
3090 ``meta/conf/distro/defaultsetup.conf`` file: INHERIT_DISTRO ?= 3424 ``meta/conf/distro/defaultsetup.conf`` file:
3091 "debian devshell sstate license" 3425 ::
3092 3426
3427 INHERIT_DISTRO ?= "debian devshell sstate license"
3428
3093 INHIBIT_DEFAULT_DEPS 3429 INHIBIT_DEFAULT_DEPS
3094 Prevents the default dependencies, namely the C compiler and standard 3430 Prevents the default dependencies, namely the C compiler and standard
3095 C library (libc), from being added to :term:`DEPENDS`. 3431 C library (libc), from being added to :term:`DEPENDS`.
3096 This variable is usually used within recipes that do not require any 3432 This variable is usually used within recipes that do not require any
3097 compilation using the C compiler. 3433 compilation using the C compiler.
3098 3434
3099 Set the variable to "1" to prevent the default dependencies from 3435 Set the variable to "1" to prevent the default dependencies from
3100 being added. 3436 being added.
3101 3437
3102 INHIBIT_PACKAGE_DEBUG_SPLIT 3438 INHIBIT_PACKAGE_DEBUG_SPLIT
3103 Prevents the OpenEmbedded build system from splitting out debug 3439 Prevents the OpenEmbedded build system from splitting out debug
3104 information during packaging. By default, the build system splits out 3440 information during packaging. By default, the build system splits out
@@ -3107,37 +3443,40 @@ system and gives an overview of their function and contents.
3107 how debug information is split out, see the 3443 how debug information is split out, see the
3108 :term:`PACKAGE_DEBUG_SPLIT_STYLE` 3444 :term:`PACKAGE_DEBUG_SPLIT_STYLE`
3109 variable. 3445 variable.
3110 3446
3111 To prevent the build system from splitting out debug information 3447 To prevent the build system from splitting out debug information
3112 during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as 3448 during packaging, set the ``INHIBIT_PACKAGE_DEBUG_SPLIT`` variable as
3113 follows: INHIBIT_PACKAGE_DEBUG_SPLIT = "1" 3449 follows:
3114 3450 ::
3451
3452 INHIBIT_PACKAGE_DEBUG_SPLIT = "1"
3453
3115 INHIBIT_PACKAGE_STRIP 3454 INHIBIT_PACKAGE_STRIP
3116 If set to "1", causes the build to not strip binaries in resulting 3455 If set to "1", causes the build to not strip binaries in resulting
3117 packages and prevents the ``-dbg`` package from containing the source 3456 packages and prevents the ``-dbg`` package from containing the source
3118 files. 3457 files.
3119 3458
3120 By default, the OpenEmbedded build system strips binaries and puts 3459 By default, the OpenEmbedded build system strips binaries and puts
3121 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``. 3460 the debugging symbols into ``${``\ :term:`PN`\ ``}-dbg``.
3122 Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you 3461 Consequently, you should not set ``INHIBIT_PACKAGE_STRIP`` when you
3123 plan to debug in general. 3462 plan to debug in general.
3124 3463
3125 INHIBIT_SYSROOT_STRIP 3464 INHIBIT_SYSROOT_STRIP
3126 If set to "1", causes the build to not strip binaries in the 3465 If set to "1", causes the build to not strip binaries in the
3127 resulting sysroot. 3466 resulting sysroot.
3128 3467
3129 By default, the OpenEmbedded build system strips binaries in the 3468 By default, the OpenEmbedded build system strips binaries in the
3130 resulting sysroot. When you specifically set the 3469 resulting sysroot. When you specifically set the
3131 ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit 3470 ``INHIBIT_SYSROOT_STRIP`` variable to "1" in your recipe, you inhibit
3132 this stripping. 3471 this stripping.
3133 3472
3134 If you want to use this variable, include the 3473 If you want to use this variable, include the
3135 :ref:`staging <ref-classes-staging>` class. This class uses a 3474 :ref:`staging <ref-classes-staging>` class. This class uses a
3136 ``sys_strip()`` function to test for the variable and acts 3475 ``sys_strip()`` function to test for the variable and acts
3137 accordingly. 3476 accordingly.
3138 3477
3139 .. note:: 3478 .. note::
3140 3479
3141 Use of the 3480 Use of the
3142 INHIBIT_SYSROOT_STRIP 3481 INHIBIT_SYSROOT_STRIP
3143 variable occurs in rare and special circumstances. For example, 3482 variable occurs in rare and special circumstances. For example,
@@ -3145,20 +3484,20 @@ system and gives an overview of their function and contents.
3145 GCC toolchain. Furthermore, even if the toolchain's binaries are 3484 GCC toolchain. Furthermore, even if the toolchain's binaries are
3146 strippable, other files exist that are needed for the build that 3485 strippable, other files exist that are needed for the build that
3147 are not strippable. 3486 are not strippable.
3148 3487
3149 INITRAMFS_FSTYPES 3488 INITRAMFS_FSTYPES
3150 Defines the format for the output image of an initial RAM filesystem 3489 Defines the format for the output image of an initial RAM filesystem
3151 (initramfs), which is used during boot. Supported formats are the 3490 (initramfs), which is used during boot. Supported formats are the
3152 same as those supported by the 3491 same as those supported by the
3153 :term:`IMAGE_FSTYPES` variable. 3492 :term:`IMAGE_FSTYPES` variable.
3154 3493
3155 The default value of this variable, which is set in the 3494 The default value of this variable, which is set in the
3156 ``meta/conf/bitbake.conf`` configuration file in the 3495 ``meta/conf/bitbake.conf`` configuration file in the
3157 :term:`Source Directory`, is "cpio.gz". The Linux kernel's 3496 :term:`Source Directory`, is "cpio.gz". The Linux kernel's
3158 initramfs mechanism, as opposed to the initial RAM filesystem 3497 initramfs mechanism, as opposed to the initial RAM filesystem
3159 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects 3498 `initrd <https://en.wikipedia.org/wiki/Initrd>`__ mechanism, expects
3160 an optionally compressed cpio archive. 3499 an optionally compressed cpio archive.
3161 3500
3162 INITRAMFS_IMAGE 3501 INITRAMFS_IMAGE
3163 Specifies the :term:`PROVIDES` name of an image 3502 Specifies the :term:`PROVIDES` name of an image
3164 recipe that is used to build an initial RAM filesystem (initramfs) 3503 recipe that is used to build an initial RAM filesystem (initramfs)
@@ -3168,13 +3507,13 @@ system and gives an overview of their function and contents.
3168 initramfs image recipe you provide should set 3507 initramfs image recipe you provide should set
3169 :term:`IMAGE_FSTYPES` to 3508 :term:`IMAGE_FSTYPES` to
3170 :term:`INITRAMFS_FSTYPES`. 3509 :term:`INITRAMFS_FSTYPES`.
3171 3510
3172 An initramfs image provides a temporary root filesystem used for 3511 An initramfs image provides a temporary root filesystem used for
3173 early system initialization (e.g. loading of modules needed to locate 3512 early system initialization (e.g. loading of modules needed to locate
3174 and mount the "real" root filesystem). 3513 and mount the "real" root filesystem).
3175 3514
3176 .. note:: 3515 .. note::
3177 3516
3178 See the 3517 See the
3179 meta/recipes-core/images/core-image-minimal-initramfs.bb 3518 meta/recipes-core/images/core-image-minimal-initramfs.bb
3180 recipe in the 3519 recipe in the
@@ -3183,24 +3522,23 @@ system and gives an overview of their function and contents.
3183 the one built to provide the initramfs image, set 3522 the one built to provide the initramfs image, set
3184 INITRAMFS_IMAGE 3523 INITRAMFS_IMAGE
3185 to "core-image-minimal-initramfs". 3524 to "core-image-minimal-initramfs".
3186 3525
3187 You can also find more information by referencing the 3526 You can also find more information by referencing the
3188 ``meta-poky/conf/local.conf.sample.extended`` configuration file in 3527 ``meta-poky/conf/local.conf.sample.extended`` configuration file in
3189 the Source Directory, the :ref:`image <ref-classes-image>` class, 3528 the Source Directory, the :ref:`image <ref-classes-image>` class,
3190 and the :ref:`kernel <ref-classes-kernel>` class to see how to use 3529 and the :ref:`kernel <ref-classes-kernel>` class to see how to use
3191 the ``INITRAMFS_IMAGE`` variable. 3530 the ``INITRAMFS_IMAGE`` variable.
3192 3531
3193 If ``INITRAMFS_IMAGE`` is empty, which is the default, then no 3532 If ``INITRAMFS_IMAGE`` is empty, which is the default, then no
3194 initramfs image is built. 3533 initramfs image is built.
3195 3534
3196 For more information, you can also see the 3535 For more information, you can also see the
3197 :term:`INITRAMFS_IMAGE_BUNDLE` 3536 :term:`INITRAMFS_IMAGE_BUNDLE`
3198 variable, which allows the generated image to be bundled inside the 3537 variable, which allows the generated image to be bundled inside the
3199 kernel image. Additionally, for information on creating an initramfs 3538 kernel image. Additionally, for information on creating an initramfs
3200 image, see the "`Building an Initial RAM Filesystem (initramfs) 3539 image, see the ":ref:`building-an-initramfs-image`" section
3201 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
3202 in the Yocto Project Development Tasks Manual. 3540 in the Yocto Project Development Tasks Manual.
3203 3541
3204 INITRAMFS_IMAGE_BUNDLE 3542 INITRAMFS_IMAGE_BUNDLE
3205 Controls whether or not the image recipe specified by 3543 Controls whether or not the image recipe specified by
3206 :term:`INITRAMFS_IMAGE` is run through an 3544 :term:`INITRAMFS_IMAGE` is run through an
@@ -3211,152 +3549,181 @@ system and gives an overview of their function and contents.
3211 image. This makes use of the 3549 image. This makes use of the
3212 :term:`CONFIG_INITRAMFS_SOURCE` kernel 3550 :term:`CONFIG_INITRAMFS_SOURCE` kernel
3213 feature. 3551 feature.
3214 3552
3215 .. note:: 3553 .. note::
3216 3554
3217 Using an extra compilation pass to bundle the initramfs avoids a 3555 Using an extra compilation pass to bundle the initramfs avoids a
3218 circular dependency between the kernel recipe and the initramfs 3556 circular dependency between the kernel recipe and the initramfs
3219 recipe should the initramfs include kernel modules. Should that be 3557 recipe should the initramfs include kernel modules. Should that be
3220 the case, the initramfs recipe depends on the kernel for the 3558 the case, the initramfs recipe depends on the kernel for the
3221 kernel modules, and the kernel depends on the initramfs recipe 3559 kernel modules, and the kernel depends on the initramfs recipe
3222 since the initramfs is bundled inside the kernel image. 3560 since the initramfs is bundled inside the kernel image.
3223 3561
3224 The combined binary is deposited into the ``tmp/deploy`` directory, 3562 The combined binary is deposited into the ``tmp/deploy`` directory,
3225 which is part of the :term:`Build Directory`. 3563 which is part of the :term:`Build Directory`.
3226 3564
3227 Setting the variable to "1" in a configuration file causes the 3565 Setting the variable to "1" in a configuration file causes the
3228 OpenEmbedded build system to generate a kernel image with the 3566 OpenEmbedded build system to generate a kernel image with the
3229 initramfs specified in ``INITRAMFS_IMAGE`` bundled within: 3567 initramfs specified in ``INITRAMFS_IMAGE`` bundled within:
3230 INITRAMFS_IMAGE_BUNDLE = "1" By default, the 3568 ::
3569
3570 INITRAMFS_IMAGE_BUNDLE = "1"
3571
3572 By default, the
3231 :ref:`kernel <ref-classes-kernel>` class sets this variable to a 3573 :ref:`kernel <ref-classes-kernel>` class sets this variable to a
3232 null string as follows: INITRAMFS_IMAGE_BUNDLE ?= "" 3574 null string as follows:
3233 3575 ::
3576
3577 INITRAMFS_IMAGE_BUNDLE ?= ""
3578
3234 .. note:: 3579 .. note::
3235 3580
3236 You must set the 3581 You must set the
3237 INITRAMFS_IMAGE_BUNDLE 3582 INITRAMFS_IMAGE_BUNDLE
3238 variable in a configuration file. You cannot set the variable in a 3583 variable in a configuration file. You cannot set the variable in a
3239 recipe file. 3584 recipe file.
3240 3585
3241 See the 3586 See the
3242 :yocto_git:`local.conf.sample.extended </cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>` 3587 :yocto_git:`local.conf.sample.extended </cgit/cgit.cgi/poky/tree/meta-poky/conf/local.conf.sample.extended>`
3243 file for additional information. Also, for information on creating an 3588 file for additional information. Also, for information on creating an
3244 initramfs, see the "`Building an Initial RAM Filesystem (initramfs) 3589 initramfs, see the ":ref:`building-an-initramfs-image`" section
3245 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
3246 in the Yocto Project Development Tasks Manual. 3590 in the Yocto Project Development Tasks Manual.
3247 3591
3248 INITRAMFS_LINK_NAME 3592 INITRAMFS_LINK_NAME
3249 The link name of the initial RAM filesystem image. This variable is 3593 The link name of the initial RAM filesystem image. This variable is
3250 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 3594 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3251 follows: INITRAMFS_LINK_NAME ?= 3595 follows:
3252 "initramfs-${KERNEL_ARTIFACT_LINK_NAME}" The value of the 3596 ::
3597
3598 INITRAMFS_LINK_NAME ?= "initramfs-${KERNEL_ARTIFACT_LINK_NAME}"
3599
3600 The value of the
3253 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 3601 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3254 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?= 3602 file, has the following value:
3255 "${MACHINE}" 3603 ::
3256 3604
3605 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3606
3257 See the :term:`MACHINE` variable for additional 3607 See the :term:`MACHINE` variable for additional
3258 information. 3608 information.
3259 3609
3260 INITRAMFS_NAME 3610 INITRAMFS_NAME
3261 The base name of the initial RAM filesystem image. This variable is 3611 The base name of the initial RAM filesystem image. This variable is
3262 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 3612 set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3263 follows: INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}" The 3613 follows:
3264 value of the :term:`KERNEL_ARTIFACT_NAME` 3614 ::
3615
3616 INITRAMFS_NAME ?= "initramfs-${KERNEL_ARTIFACT_NAME}"
3617
3618 The value of the :term:`KERNEL_ARTIFACT_NAME`
3265 variable, which is set in the same file, has the following value: 3619 variable, which is set in the same file, has the following value:
3266 KERNEL_ARTIFACT_NAME ?= 3620 ::
3267 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3621
3268 3622 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3623
3269 INITRD 3624 INITRD
3270 Indicates list of filesystem images to concatenate and use as an 3625 Indicates list of filesystem images to concatenate and use as an
3271 initial RAM disk (``initrd``). 3626 initial RAM disk (``initrd``).
3272 3627
3273 The ``INITRD`` variable is an optional variable used with the 3628 The ``INITRD`` variable is an optional variable used with the
3274 :ref:`image-live <ref-classes-image-live>` class. 3629 :ref:`image-live <ref-classes-image-live>` class.
3275 3630
3276 INITRD_IMAGE 3631 INITRD_IMAGE
3277 When building a "live" bootable image (i.e. when 3632 When building a "live" bootable image (i.e. when
3278 :term:`IMAGE_FSTYPES` contains "live"), 3633 :term:`IMAGE_FSTYPES` contains "live"),
3279 ``INITRD_IMAGE`` specifies the image recipe that should be built to 3634 ``INITRD_IMAGE`` specifies the image recipe that should be built to
3280 provide the initial RAM disk image. The default value is 3635 provide the initial RAM disk image. The default value is
3281 "core-image-minimal-initramfs". 3636 "core-image-minimal-initramfs".
3282 3637
3283 See the :ref:`image-live <ref-classes-image-live>` class for more 3638 See the :ref:`image-live <ref-classes-image-live>` class for more
3284 information. 3639 information.
3285 3640
3286 INITSCRIPT_NAME 3641 INITSCRIPT_NAME
3287 The filename of the initialization script as installed to 3642 The filename of the initialization script as installed to
3288 ``${sysconfdir}/init.d``. 3643 ``${sysconfdir}/init.d``.
3289 3644
3290 This variable is used in recipes when using ``update-rc.d.bbclass``. 3645 This variable is used in recipes when using ``update-rc.d.bbclass``.
3291 The variable is mandatory. 3646 The variable is mandatory.
3292 3647
3293 INITSCRIPT_PACKAGES 3648 INITSCRIPT_PACKAGES
3294 A list of the packages that contain initscripts. If multiple packages 3649 A list of the packages that contain initscripts. If multiple packages
3295 are specified, you need to append the package name to the other 3650 are specified, you need to append the package name to the other
3296 ``INITSCRIPT_*`` as an override. 3651 ``INITSCRIPT_*`` as an override.
3297 3652
3298 This variable is used in recipes when using ``update-rc.d.bbclass``. 3653 This variable is used in recipes when using ``update-rc.d.bbclass``.
3299 The variable is optional and defaults to the :term:`PN` 3654 The variable is optional and defaults to the :term:`PN`
3300 variable. 3655 variable.
3301 3656
3302 INITSCRIPT_PARAMS 3657 INITSCRIPT_PARAMS
3303 Specifies the options to pass to ``update-rc.d``. Here is an example: 3658 Specifies the options to pass to ``update-rc.d``. Here is an example:
3304 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ." 3659 ::
3305 3660
3661 INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
3662
3306 In this example, the script has a runlevel of 99, starts the script 3663 In this example, the script has a runlevel of 99, starts the script
3307 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6. 3664 in initlevels 2 and 5, and stops the script in levels 0, 1 and 6.
3308 3665
3309 The variable's default value is "defaults", which is set in the 3666 The variable's default value is "defaults", which is set in the
3310 :ref:`update-rc.d <ref-classes-update-rc.d>` class. 3667 :ref:`update-rc.d <ref-classes-update-rc.d>` class.
3311 3668
3312 The value in ``INITSCRIPT_PARAMS`` is passed through to the 3669 The value in ``INITSCRIPT_PARAMS`` is passed through to the
3313 ``update-rc.d`` command. For more information on valid parameters, 3670 ``update-rc.d`` command. For more information on valid parameters,
3314 please see the ``update-rc.d`` manual page at 3671 please see the ``update-rc.d`` manual page at
3315 http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d. 3672 http://www.tin.org/bin/man.cgi?section=8&topic=update-rc.d.
3316 3673
3317 INSANE_SKIP 3674 INSANE_SKIP
3318 Specifies the QA checks to skip for a specific package within a 3675 Specifies the QA checks to skip for a specific package within a
3319 recipe. For example, to skip the check for symbolic link ``.so`` 3676 recipe. For example, to skip the check for symbolic link ``.so``
3320 files in the main package of a recipe, add the following to the 3677 files in the main package of a recipe, add the following to the
3321 recipe. The package name override must be used, which in this example 3678 recipe. The package name override must be used, which in this example
3322 is ``${PN}``: INSANE_SKIP_${PN} += "dev-so" 3679 is ``${PN}``:
3323 3680 ::
3681
3682 INSANE_SKIP_${PN} += "dev-so"
3683
3324 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a 3684 See the ":ref:`insane.bbclass <ref-classes-insane>`" section for a
3325 list of the valid QA checks you can specify using this variable. 3685 list of the valid QA checks you can specify using this variable.
3326 3686
3327 INSTALL_TIMEZONE_FILE 3687 INSTALL_TIMEZONE_FILE
3328 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file. 3688 By default, the ``tzdata`` recipe packages an ``/etc/timezone`` file.
3329 Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the 3689 Set the ``INSTALL_TIMEZONE_FILE`` variable to "0" at the
3330 configuration level to disable this behavior. 3690 configuration level to disable this behavior.
3331 3691
3332 IPK_FEED_URIS 3692 IPK_FEED_URIS
3333 When the IPK backend is in use and package management is enabled on 3693 When the IPK backend is in use and package management is enabled on
3334 the target, you can use this variable to set up ``opkg`` in the 3694 the target, you can use this variable to set up ``opkg`` in the
3335 target image to point to package feeds on a nominated server. Once 3695 target image to point to package feeds on a nominated server. Once
3336 the feed is established, you can perform installations or upgrades 3696 the feed is established, you can perform installations or upgrades
3337 using the package manager at runtime. 3697 using the package manager at runtime.
3338 3698
3339 KARCH 3699 KARCH
3340 Defines the kernel architecture used when assembling the 3700 Defines the kernel architecture used when assembling the
3341 configuration. Architectures supported for this release are: powerpc 3701 configuration. Architectures supported for this release are:
3342 i386 x86_64 arm qemu mips 3702
3343 3703 - powerpc
3344 You define the ``KARCH`` variable in the `BSP 3704 - i386
3345 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__. 3705 - x86_64
3346 3706 - arm
3707 - qemu
3708 - mips
3709
3710 You define the ``KARCH`` variable in the :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`.
3711
3347 KBRANCH 3712 KBRANCH
3348 A regular expression used by the build process to explicitly identify 3713 A regular expression used by the build process to explicitly identify
3349 the kernel branch that is validated, patched, and configured during a 3714 the kernel branch that is validated, patched, and configured during a
3350 build. You must set this variable to ensure the exact kernel branch 3715 build. You must set this variable to ensure the exact kernel branch
3351 you want is being used by the build process. 3716 you want is being used by the build process.
3352 3717
3353 Values for this variable are set in the kernel's recipe file and the 3718 Values for this variable are set in the kernel's recipe file and the
3354 kernel's append file. For example, if you are using the 3719 kernel's append file. For example, if you are using the
3355 ``linux-yocto_4.12`` kernel, the kernel recipe file is the 3720 ``linux-yocto_4.12`` kernel, the kernel recipe file is the
3356 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH`` 3721 ``meta/recipes-kernel/linux/linux-yocto_4.12.bb`` file. ``KBRANCH``
3357 is set as follows in that kernel recipe file: KBRANCH ?= 3722 is set as follows in that kernel recipe file:
3358 "standard/base" 3723 ::
3359 3724
3725 KBRANCH ?= "standard/base"
3726
3360 This variable is also used from the kernel's append file to identify 3727 This variable is also used from the kernel's append file to identify
3361 the kernel branch specific to a particular machine or target 3728 the kernel branch specific to a particular machine or target
3362 hardware. Continuing with the previous kernel example, the kernel's 3729 hardware. Continuing with the previous kernel example, the kernel's
@@ -3366,17 +3733,22 @@ system and gives an overview of their function and contents.
3366 machines (``meta-yocto-bsp``) is named 3733 machines (``meta-yocto-bsp``) is named
3367 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``. 3734 ``meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.12.bbappend``.
3368 Here are the related statements from that append file: 3735 Here are the related statements from that append file:
3369 KBRANCH_genericx86 = "standard/base" KBRANCH_genericx86-64 = 3736 ::
3370 "standard/base" KBRANCH_edgerouter = "standard/edgerouter" 3737
3371 KBRANCH_beaglebone = "standard/beaglebone" The ``KBRANCH`` statements 3738 KBRANCH_genericx86 = "standard/base"
3739 KBRANCH_genericx86-64 = "standard/base"
3740 KBRANCH_edgerouter = "standard/edgerouter"
3741 KBRANCH_beaglebone = "standard/beaglebone"
3742
3743 The ``KBRANCH`` statements
3372 identify the kernel branch to use when building for each supported 3744 identify the kernel branch to use when building for each supported
3373 BSP. 3745 BSP.
3374 3746
3375 KBUILD_DEFCONFIG 3747 KBUILD_DEFCONFIG
3376 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>` 3748 When used with the :ref:`kernel-yocto <ref-classes-kernel-yocto>`
3377 class, specifies an "in-tree" kernel configuration file for use 3749 class, specifies an "in-tree" kernel configuration file for use
3378 during a kernel build. 3750 during a kernel build.
3379 3751
3380 Typically, when using a ``defconfig`` to configure a kernel during a 3752 Typically, when using a ``defconfig`` to configure a kernel during a
3381 build, you place the file in your layer in the same manner as you 3753 build, you place the file in your layer in the same manner as you
3382 would place patch files and configuration fragment files (i.e. 3754 would place patch files and configuration fragment files (i.e.
@@ -3385,46 +3757,53 @@ system and gives an overview of their function and contents.
3385 ``KBUILD_DEFCONFIG`` variable and append the 3757 ``KBUILD_DEFCONFIG`` variable and append the
3386 :term:`KMACHINE` variable to point to the 3758 :term:`KMACHINE` variable to point to the
3387 ``defconfig`` file. 3759 ``defconfig`` file.
3388 3760
3389 To use the variable, set it in the append file for your kernel recipe 3761 To use the variable, set it in the append file for your kernel recipe
3390 using the following form: KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file 3762 using the following form:
3763 ::
3764
3765 KBUILD_DEFCONFIG_KMACHINE ?= defconfig_file
3766
3391 Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses 3767 Here is an example from a "raspberrypi2" ``KMACHINE`` build that uses
3392 a ``defconfig`` file named "bcm2709_defconfig": 3768 a ``defconfig`` file named "bcm2709_defconfig":
3393 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig" As an 3769 ::
3394 alternative, you can use the following within your append file: 3770
3395 KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file For more 3771 KBUILD_DEFCONFIG_raspberrypi2 = "bcm2709_defconfig"
3772
3773 As an alternative, you can use the following within your append file:
3774 ::
3775
3776 KBUILD_DEFCONFIG_pn-linux-yocto ?= defconfig_file
3777
3778 For more
3396 information on how to use the ``KBUILD_DEFCONFIG`` variable, see the 3779 information on how to use the ``KBUILD_DEFCONFIG`` variable, see the
3397 "`Using an "In-Tree" ``defconfig`` 3780 ":ref:`kernel-dev/kernel-dev-common:using an "in-tree" \`\`defconfig\`\` file`"
3398 File <&YOCTO_DOCS_KERNEL_DEV_URL;#using-an-in-tree-defconfig-file>`__"
3399 section in the Yocto Project Linux Kernel Development Manual. 3781 section in the Yocto Project Linux Kernel Development Manual.
3400 3782
3401 KERNEL_ALT_IMAGETYPE 3783 KERNEL_ALT_IMAGETYPE
3402 Specifies an alternate kernel image type for creation in addition to 3784 Specifies an alternate kernel image type for creation in addition to
3403 the kernel image type specified using the 3785 the kernel image type specified using the
3404 :term:`KERNEL_IMAGETYPE` variable. 3786 :term:`KERNEL_IMAGETYPE` variable.
3405 3787
3406 KERNEL_ARTIFACT_NAME 3788 KERNEL_ARTIFACT_NAME
3407 Specifies the name of all of the build artifacts. You can change the 3789 Specifies the name of all of the build artifacts. You can change the
3408 name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME`` 3790 name of the artifacts by changing the ``KERNEL_ARTIFACT_NAME``
3409 variable. 3791 variable.
3410 3792
3411 The value of ``KERNEL_ARTIFACT_NAME``, which is set in the 3793 The value of ``KERNEL_ARTIFACT_NAME``, which is set in the
3412 ``meta/classes/kernel-artifact-names.bbclass`` file, has the 3794 ``meta/classes/kernel-artifact-names.bbclass`` file, has the
3413 following default value: KERNEL_ARTIFACT_NAME ?= 3795 following default value:
3414 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3796 ::
3415 3797
3416 See the :term:`PKGE`, :term:`PKGV`, 3798 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3417 :term:`PKGR`, and :term:`MACHINE` 3799
3800 See the :term:`PKGE`, :term:`PKGV`, :term:`PKGR`, and :term:`MACHINE`
3418 variables for additional information. 3801 variables for additional information.
3419 3802
3420 .. note:: 3803 .. note::
3421 3804
3422 The 3805 The IMAGE_VERSION_SUFFIX variable is set to DATETIME.
3423 IMAGE_VERSION_SUFFIX 3806
3424 variable is set to
3425 DATETIME
3426 .
3427
3428 KERNEL_CLASSES 3807 KERNEL_CLASSES
3429 A list of classes defining kernel image types that the 3808 A list of classes defining kernel image types that the
3430 :ref:`kernel <ref-classes-kernel>` class should inherit. You 3809 :ref:`kernel <ref-classes-kernel>` class should inherit. You
@@ -3433,46 +3812,56 @@ system and gives an overview of their function and contents.
3433 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register 3812 resides in ``meta/classes/kernel-fitimage.bbclass``. You can register
3434 custom kernel image types with the ``kernel`` class using this 3813 custom kernel image types with the ``kernel`` class using this
3435 variable. 3814 variable.
3436 3815
3437 KERNEL_DEVICETREE 3816 KERNEL_DEVICETREE
3438 Specifies the name of the generated Linux kernel device tree (i.e. 3817 Specifies the name of the generated Linux kernel device tree (i.e.
3439 the ``.dtb``) file. 3818 the ``.dtb``) file.
3440 3819
3441 .. note:: 3820 .. note::
3442 3821
3443 Legacy support exists for specifying the full path to the device 3822 Legacy support exists for specifying the full path to the device
3444 tree. However, providing just the 3823 tree. However, providing just the .dtb file is preferred.
3445 .dtb 3824
3446 file is preferred.
3447
3448 In order to use this variable, the 3825 In order to use this variable, the
3449 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must 3826 :ref:`kernel-devicetree <ref-classes-kernel-devicetree>` class must
3450 be inherited. 3827 be inherited.
3451 3828
3452 KERNEL_DTB_LINK_NAME 3829 KERNEL_DTB_LINK_NAME
3453 The link name of the kernel device tree binary (DTB). This variable 3830 The link name of the kernel device tree binary (DTB). This variable
3454 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 3831 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3455 follows: KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The 3832 follows:
3833 ::
3834
3835 KERNEL_DTB_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3836
3837 The
3456 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in 3838 value of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in
3457 the same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?= 3839 the same file, has the following value:
3458 "${MACHINE}" 3840 ::
3459 3841
3842 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3843
3460 See the :term:`MACHINE` variable for additional 3844 See the :term:`MACHINE` variable for additional
3461 information. 3845 information.
3462 3846
3463 KERNEL_DTB_NAME 3847 KERNEL_DTB_NAME
3464 The base name of the kernel device tree binary (DTB). This variable 3848 The base name of the kernel device tree binary (DTB). This variable
3465 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as 3849 is set in the ``meta/classes/kernel-artifact-names.bbclass`` file as
3466 follows: KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of 3850 follows:
3467 the :term:`KERNEL_ARTIFACT_NAME` 3851 ::
3852
3853 KERNEL_DTB_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3854
3855 The value of the :term:`KERNEL_ARTIFACT_NAME`
3468 variable, which is set in the same file, has the following value: 3856 variable, which is set in the same file, has the following value:
3469 KERNEL_ARTIFACT_NAME ?= 3857 ::
3470 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3858
3471 3859 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3860
3472 KERNEL_EXTRA_ARGS 3861 KERNEL_EXTRA_ARGS
3473 Specifies additional ``make`` command-line arguments the OpenEmbedded 3862 Specifies additional ``make`` command-line arguments the OpenEmbedded
3474 build system passes on when compiling the kernel. 3863 build system passes on when compiling the kernel.
3475 3864
3476 KERNEL_FEATURES 3865 KERNEL_FEATURES
3477 Includes additional kernel metadata. In the OpenEmbedded build 3866 Includes additional kernel metadata. In the OpenEmbedded build
3478 system, the default Board Support Packages (BSPs) 3867 system, the default Board Support Packages (BSPs)
@@ -3481,158 +3870,184 @@ system and gives an overview of their function and contents.
3481 variables. You can use the ``KERNEL_FEATURES`` variable from within 3870 variables. You can use the ``KERNEL_FEATURES`` variable from within
3482 the kernel recipe or kernel append file to further add metadata for 3871 the kernel recipe or kernel append file to further add metadata for
3483 all BSPs or specific BSPs. 3872 all BSPs or specific BSPs.
3484 3873
3485 The metadata you add through this variable includes config fragments 3874 The metadata you add through this variable includes config fragments
3486 and features descriptions, which usually includes patches as well as 3875 and features descriptions, which usually includes patches as well as
3487 config fragments. You typically override the ``KERNEL_FEATURES`` 3876 config fragments. You typically override the ``KERNEL_FEATURES``
3488 variable for a specific machine. In this way, you can provide 3877 variable for a specific machine. In this way, you can provide
3489 validated, but optional, sets of kernel configurations and features. 3878 validated, but optional, sets of kernel configurations and features.
3490 3879
3491 For example, the following example from the ``linux-yocto-rt_4.12`` 3880 For example, the following example from the ``linux-yocto-rt_4.12``
3492 kernel recipe adds "netfilter" and "taskstats" features to all BSPs 3881 kernel recipe adds "netfilter" and "taskstats" features to all BSPs
3493 as well as "virtio" configurations to all QEMU machines. The last two 3882 as well as "virtio" configurations to all QEMU machines. The last two
3494 statements add specific configurations to targeted machine types: 3883 statements add specific configurations to targeted machine types:
3495 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc 3884 ::
3496 features/taskstats/taskstats.scc" KERNEL_FEATURES_append = " 3885
3497 ${KERNEL_EXTRA_FEATURES}" KERNEL_FEATURES_append_qemuall = " 3886 KERNEL_EXTRA_FEATURES ?= "features/netfilter/netfilter.scc features/taskstats/taskstats.scc"
3498 cfg/virtio.scc" KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc 3887 KERNEL_FEATURES_append = "${KERNEL_EXTRA_FEATURES}"
3499 cfg/paravirt_kvm.scc" KERNEL_FEATURES_append_qemux86-64 = " 3888 KERNEL_FEATURES_append_qemuall = "cfg/virtio.scc"
3500 cfg/sound.scc" 3889 KERNEL_FEATURES_append_qemux86 = " cfg/sound.scc cfg/paravirt_kvm.scc"
3501 3890 KERNEL_FEATURES_append_qemux86-64 = "cfg/sound.scc"
3891
3502 KERNEL_FIT_LINK_NAME 3892 KERNEL_FIT_LINK_NAME
3503 The link name of the kernel flattened image tree (FIT) image. This 3893 The link name of the kernel flattened image tree (FIT) image. This
3504 variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` 3894 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
3505 file as follows: KERNEL_FIT_LINK_NAME ?= 3895 file as follows:
3506 "${KERNEL_ARTIFACT_LINK_NAME}" The value of the 3896 ::
3897
3898 KERNEL_FIT_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3899
3900 The value of the
3507 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 3901 ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3508 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?= 3902 file, has the following value:
3509 "${MACHINE}" 3903 ::
3510 3904
3905 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3906
3511 See the :term:`MACHINE` variable for additional 3907 See the :term:`MACHINE` variable for additional
3512 information. 3908 information.
3513 3909
3514 KERNEL_FIT_NAME 3910 KERNEL_FIT_NAME
3515 The base name of the kernel flattened image tree (FIT) image. This 3911 The base name of the kernel flattened image tree (FIT) image. This
3516 variable is set in the ``meta/classes/kernel-artifact-names.bbclass`` 3912 variable is set in the ``meta/classes/kernel-artifact-names.bbclass``
3517 file as follows: KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}" The 3913 file as follows:
3518 value of the :term:`KERNEL_ARTIFACT_NAME` 3914 ::
3915
3916 KERNEL_FIT_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3917
3918 The value of the :term:`KERNEL_ARTIFACT_NAME`
3519 variable, which is set in the same file, has the following value: 3919 variable, which is set in the same file, has the following value:
3520 KERNEL_ARTIFACT_NAME ?= 3920 ::
3521 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3921
3522 3922 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3923
3523 KERNEL_IMAGE_LINK_NAME 3924 KERNEL_IMAGE_LINK_NAME
3524 The link name for the kernel image. This variable is set in the 3925 The link name for the kernel image. This variable is set in the
3525 ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 3926 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
3526 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value of 3927 ::
3928
3929 KERNEL_IMAGE_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
3930
3931 The value of
3527 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same 3932 the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the same
3528 file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?= 3933 file, has the following value:
3529 "${MACHINE}" 3934 ::
3530 3935
3936 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
3937
3531 See the :term:`MACHINE` variable for additional 3938 See the :term:`MACHINE` variable for additional
3532 information. 3939 information.
3533 3940
3534 KERNEL_IMAGE_MAXSIZE 3941 KERNEL_IMAGE_MAXSIZE
3535 Specifies the maximum size of the kernel image file in kilobytes. If 3942 Specifies the maximum size of the kernel image file in kilobytes. If
3536 ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is 3943 ``KERNEL_IMAGE_MAXSIZE`` is set, the size of the kernel image file is
3537 checked against the set value during the 3944 checked against the set value during the
3538 :ref:`ref-tasks-sizecheck` task. The task fails if 3945 :ref:`ref-tasks-sizecheck` task. The task fails if
3539 the kernel image file is larger than the setting. 3946 the kernel image file is larger than the setting.
3540 3947
3541 ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a 3948 ``KERNEL_IMAGE_MAXSIZE`` is useful for target devices that have a
3542 limited amount of space in which the kernel image must be stored. 3949 limited amount of space in which the kernel image must be stored.
3543 3950
3544 By default, this variable is not set, which means the size of the 3951 By default, this variable is not set, which means the size of the
3545 kernel image is not checked. 3952 kernel image is not checked.
3546 3953
3547 KERNEL_IMAGE_NAME 3954 KERNEL_IMAGE_NAME
3548 The base name of the kernel image. This variable is set in the 3955 The base name of the kernel image. This variable is set in the
3549 ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 3956 ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
3550 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the 3957 ::
3958
3959 KERNEL_IMAGE_NAME ?= "${KERNEL_ARTIFACT_NAME}"
3960
3961 The value of the
3551 :term:`KERNEL_ARTIFACT_NAME` variable, 3962 :term:`KERNEL_ARTIFACT_NAME` variable,
3552 which is set in the same file, has the following value: 3963 which is set in the same file, has the following value:
3553 KERNEL_ARTIFACT_NAME ?= 3964 ::
3554 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 3965
3555 3966 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
3967
3556 KERNEL_IMAGETYPE 3968 KERNEL_IMAGETYPE
3557 The type of kernel to build for a device, usually set by the machine 3969 The type of kernel to build for a device, usually set by the machine
3558 configuration files and defaults to "zImage". This variable is used 3970 configuration files and defaults to "zImage". This variable is used
3559 when building the kernel and is passed to ``make`` as the target to 3971 when building the kernel and is passed to ``make`` as the target to
3560 build. 3972 build.
3561 3973
3562 If you want to build an alternate kernel image type, use the 3974 If you want to build an alternate kernel image type, use the
3563 :term:`KERNEL_ALT_IMAGETYPE` variable. 3975 :term:`KERNEL_ALT_IMAGETYPE` variable.
3564 3976
3565 KERNEL_MODULE_AUTOLOAD 3977 KERNEL_MODULE_AUTOLOAD
3566 Lists kernel modules that need to be auto-loaded during boot. 3978 Lists kernel modules that need to be auto-loaded during boot.
3567 3979
3568 .. note:: 3980 .. note::
3569 3981
3570 This variable replaces the deprecated 3982 This variable replaces the deprecated
3571 module_autoload 3983 module_autoload
3572 variable. 3984 variable.
3573 3985
3574 You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it 3986 You can use the ``KERNEL_MODULE_AUTOLOAD`` variable anywhere that it
3575 can be recognized by the kernel recipe or by an out-of-tree kernel 3987 can be recognized by the kernel recipe or by an out-of-tree kernel
3576 module recipe (e.g. a machine configuration file, a distribution 3988 module recipe (e.g. a machine configuration file, a distribution
3577 configuration file, an append file for the recipe, or the recipe 3989 configuration file, an append file for the recipe, or the recipe
3578 itself). 3990 itself).
3579 3991
3580 Specify it as follows: KERNEL_MODULE_AUTOLOAD += "module_name1 3992 Specify it as follows:
3581 module_name2 module_name3" 3993 ::
3582 3994
3995 KERNEL_MODULE_AUTOLOAD += "module_name1 module_name2 module_name3"
3996
3583 Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build 3997 Including ``KERNEL_MODULE_AUTOLOAD`` causes the OpenEmbedded build
3584 system to populate the ``/etc/modules-load.d/modname.conf`` file with 3998 system to populate the ``/etc/modules-load.d/modname.conf`` file with
3585 the list of modules to be auto-loaded on boot. The modules appear 3999 the list of modules to be auto-loaded on boot. The modules appear
3586 one-per-line in the file. Here is an example of the most common use 4000 one-per-line in the file. Here is an example of the most common use
3587 case: KERNEL_MODULE_AUTOLOAD += "module_name" 4001 case:
3588 4002 ::
4003
4004 KERNEL_MODULE_AUTOLOAD += "module_name"
4005
3589 For information on how to populate the ``modname.conf`` file with 4006 For information on how to populate the ``modname.conf`` file with
3590 ``modprobe.d`` syntax lines, see the 4007 ``modprobe.d`` syntax lines, see the :term:`KERNEL_MODULE_PROBECONF` variable.
3591 :term:`KERNEL_MODULE_PROBECONF` 4008
3592 variable.
3593
3594 KERNEL_MODULE_PROBECONF 4009 KERNEL_MODULE_PROBECONF
3595 Provides a list of modules for which the OpenEmbedded build system 4010 Provides a list of modules for which the OpenEmbedded build system
3596 expects to find ``module_conf_``\ modname values that specify 4011 expects to find ``module_conf_``\ modname values that specify
3597 configuration for each of the modules. For information on how to 4012 configuration for each of the modules. For information on how to
3598 provide those module configurations, see the 4013 provide those module configurations, see the
3599 :term:`module_conf_* <module_conf>` variable. 4014 :term:`module_conf_* <module_conf>` variable.
3600 4015
3601 KERNEL_PATH 4016 KERNEL_PATH
3602 The location of the kernel sources. This variable is set to the value 4017 The location of the kernel sources. This variable is set to the value
3603 of the :term:`STAGING_KERNEL_DIR` within 4018 of the :term:`STAGING_KERNEL_DIR` within
3604 the :ref:`module <ref-classes-module>` class. For information on 4019 the :ref:`module <ref-classes-module>` class. For information on
3605 how this variable is used, see the "`Incorporating Out-of-Tree 4020 how this variable is used, see the
3606 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__" 4021 ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`"
3607 section in the Yocto Project Linux Kernel Development Manual. 4022 section in the Yocto Project Linux Kernel Development Manual.
3608 4023
3609 To help maximize compatibility with out-of-tree drivers used to build 4024 To help maximize compatibility with out-of-tree drivers used to build
3610 modules, the OpenEmbedded build system also recognizes and uses the 4025 modules, the OpenEmbedded build system also recognizes and uses the
3611 :term:`KERNEL_SRC` variable, which is identical to 4026 :term:`KERNEL_SRC` variable, which is identical to
3612 the ``KERNEL_PATH`` variable. Both variables are common variables 4027 the ``KERNEL_PATH`` variable. Both variables are common variables
3613 used by external Makefiles to point to the kernel source directory. 4028 used by external Makefiles to point to the kernel source directory.
3614 4029
3615 KERNEL_SRC 4030 KERNEL_SRC
3616 The location of the kernel sources. This variable is set to the value 4031 The location of the kernel sources. This variable is set to the value
3617 of the :term:`STAGING_KERNEL_DIR` within 4032 of the :term:`STAGING_KERNEL_DIR` within
3618 the :ref:`module <ref-classes-module>` class. For information on 4033 the :ref:`module <ref-classes-module>` class. For information on
3619 how this variable is used, see the "`Incorporating Out-of-Tree 4034 how this variable is used, see the
3620 Modules <&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules>`__" 4035 ":ref:`kernel-dev/kernel-dev-common:incorporating out-of-tree modules`"
3621 section in the Yocto Project Linux Kernel Development Manual. 4036 section in the Yocto Project Linux Kernel Development Manual.
3622 4037
3623 To help maximize compatibility with out-of-tree drivers used to build 4038 To help maximize compatibility with out-of-tree drivers used to build
3624 modules, the OpenEmbedded build system also recognizes and uses the 4039 modules, the OpenEmbedded build system also recognizes and uses the
3625 :term:`KERNEL_PATH` variable, which is identical 4040 :term:`KERNEL_PATH` variable, which is identical
3626 to the ``KERNEL_SRC`` variable. Both variables are common variables 4041 to the ``KERNEL_SRC`` variable. Both variables are common variables
3627 used by external Makefiles to point to the kernel source directory. 4042 used by external Makefiles to point to the kernel source directory.
3628 4043
3629 KERNEL_VERSION 4044 KERNEL_VERSION
3630 Specifies the version of the kernel as extracted from ``version.h`` 4045 Specifies the version of the kernel as extracted from ``version.h``
3631 or ``utsrelease.h`` within the kernel sources. Effects of setting 4046 or ``utsrelease.h`` within the kernel sources. Effects of setting
3632 this variable do not take affect until the kernel has been 4047 this variable do not take affect until the kernel has been
3633 configured. Consequently, attempting to refer to this variable in 4048 configured. Consequently, attempting to refer to this variable in
3634 contexts prior to configuration will not work. 4049 contexts prior to configuration will not work.
3635 4050
3636 KERNELDEPMODDEPEND 4051 KERNELDEPMODDEPEND
3637 Specifies whether the data referenced through 4052 Specifies whether the data referenced through
3638 :term:`PKGDATA_DIR` is needed or not. The 4053 :term:`PKGDATA_DIR` is needed or not. The
@@ -3641,14 +4056,16 @@ system and gives an overview of their function and contents.
3641 use the data, set the ``KERNELDEPMODDEPEND`` variable in your 4056 use the data, set the ``KERNELDEPMODDEPEND`` variable in your
3642 ``initramfs`` recipe. Setting the variable there when the data is not 4057 ``initramfs`` recipe. Setting the variable there when the data is not
3643 needed avoids a potential dependency loop. 4058 needed avoids a potential dependency loop.
3644 4059
3645 KFEATURE_DESCRIPTION 4060 KFEATURE_DESCRIPTION
3646 Provides a short description of a configuration fragment. You use 4061 Provides a short description of a configuration fragment. You use
3647 this variable in the ``.scc`` file that describes a configuration 4062 this variable in the ``.scc`` file that describes a configuration
3648 fragment file. Here is the variable used in a file named ``smp.scc`` 4063 fragment file. Here is the variable used in a file named ``smp.scc``
3649 to describe SMP being enabled: define KFEATURE_DESCRIPTION "Enable 4064 to describe SMP being enabled:
3650 SMP" 4065 ::
3651 4066
4067 define KFEATURE_DESCRIPTION "Enable SMP"
4068
3652 KMACHINE 4069 KMACHINE
3653 The machine as known by the kernel. Sometimes the machine name used 4070 The machine as known by the kernel. Sometimes the machine name used
3654 by the kernel does not match the machine name used by the 4071 by the kernel does not match the machine name used by the
@@ -3658,77 +4075,86 @@ system and gives an overview of their function and contents.
3658 understands that machine as ``intel-core2-32``. For cases like these, 4075 understands that machine as ``intel-core2-32``. For cases like these,
3659 the ``KMACHINE`` variable maps the kernel machine name to the 4076 the ``KMACHINE`` variable maps the kernel machine name to the
3660 OpenEmbedded build system machine name. 4077 OpenEmbedded build system machine name.
3661 4078
3662 These mappings between different names occur in the Yocto Linux 4079 These mappings between different names occur in the Yocto Linux
3663 Kernel's ``meta`` branch. As an example take a look in the 4080 Kernel's ``meta`` branch. As an example take a look in the
3664 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file: 4081 ``common/recipes-kernel/linux/linux-yocto_3.19.bbappend`` file:
3665 LINUX_VERSION_core2-32-intel-common = "3.19.0" 4082 ::
3666 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}" 4083
3667 SRCREV_meta_core2-32-intel-common = 4084 LINUX_VERSION_core2-32-intel-common = "3.19.0"
3668 "8897ef68b30e7426bc1d39895e71fb155d694974" 4085 COMPATIBLE_MACHINE_core2-32-intel-common = "${MACHINE}"
3669 SRCREV_machine_core2-32-intel-common = 4086 SRCREV_meta_core2-32-intel-common = "8897ef68b30e7426bc1d39895e71fb155d694974"
3670 "43b9eced9ba8a57add36af07736344dcc383f711" 4087 SRCREV_machine_core2-32-intel-common = "43b9eced9ba8a57add36af07736344dcc383f711"
3671 KMACHINE_core2-32-intel-common = "intel-core2-32" 4088 KMACHINE_core2-32-intel-common = "intel-core2-32"
3672 KBRANCH_core2-32-intel-common = "standard/base" 4089 KBRANCH_core2-32-intel-common = "standard/base"
3673 KERNEL_FEATURES_append_core2-32-intel-common = 4090 KERNEL_FEATURES_append_core2-32-intel-common = "${KERNEL_FEATURES_INTEL_COMMON}"
3674 "${KERNEL_FEATURES_INTEL_COMMON}" The ``KMACHINE`` statement says 4091
4092 The ``KMACHINE`` statement says
3675 that the kernel understands the machine name as "intel-core2-32". 4093 that the kernel understands the machine name as "intel-core2-32".
3676 However, the OpenEmbedded build system understands the machine as 4094 However, the OpenEmbedded build system understands the machine as
3677 "core2-32-intel-common". 4095 "core2-32-intel-common".
3678 4096
3679 KTYPE 4097 KTYPE
3680 Defines the kernel type to be used in assembling the configuration. 4098 Defines the kernel type to be used in assembling the configuration.
3681 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4099 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
3682 kernel types. See the "`Kernel 4100 kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`"
3683 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the 4101 section in the
3684 Yocto Project Linux Kernel Development Manual for more information on 4102 Yocto Project Linux Kernel Development Manual for more information on
3685 kernel types. 4103 kernel types.
3686 4104
3687 You define the ``KTYPE`` variable in the `BSP 4105 You define the ``KTYPE`` variable in the
3688 Descriptions <&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions>`__. The 4106 :ref:`kernel-dev/kernel-dev-advanced:bsp descriptions`. The
3689 value you use must match the value used for the 4107 value you use must match the value used for the
3690 :term:`LINUX_KERNEL_TYPE` value used by the 4108 :term:`LINUX_KERNEL_TYPE` value used by the
3691 kernel recipe. 4109 kernel recipe.
3692 4110
3693 LABELS 4111 LABELS
3694 Provides a list of targets for automatic configuration. 4112 Provides a list of targets for automatic configuration.
3695 4113
3696 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more 4114 See the :ref:`grub-efi <ref-classes-grub-efi>` class for more
3697 information on how this variable is used. 4115 information on how this variable is used.
3698 4116
3699 LAYERDEPENDS 4117 LAYERDEPENDS
3700 Lists the layers, separated by spaces, on which this recipe depends. 4118 Lists the layers, separated by spaces, on which this recipe depends.
3701 Optionally, you can specify a specific layer version for a dependency 4119 Optionally, you can specify a specific layer version for a dependency
3702 by adding it to the end of the layer name. Here is an example: 4120 by adding it to the end of the layer name. Here is an example:
3703 LAYERDEPENDS_mylayer = "anotherlayer (=3)" In this previous example, 4121 ::
4122
4123 LAYERDEPENDS_mylayer = "anotherlayer (=3)"
4124
4125 In this previous example,
3704 version 3 of "anotherlayer" is compared against 4126 version 3 of "anotherlayer" is compared against
3705 :term:`LAYERVERSION`\ ``_anotherlayer``. 4127 :term:`LAYERVERSION`\ ``_anotherlayer``.
3706 4128
3707 An error is produced if any dependency is missing or the version 4129 An error is produced if any dependency is missing or the version
3708 numbers (if specified) do not match exactly. This variable is used in 4130 numbers (if specified) do not match exactly. This variable is used in
3709 the ``conf/layer.conf`` file and must be suffixed with the name of 4131 the ``conf/layer.conf`` file and must be suffixed with the name of
3710 the specific layer (e.g. ``LAYERDEPENDS_mylayer``). 4132 the specific layer (e.g. ``LAYERDEPENDS_mylayer``).
3711 4133
3712 LAYERDIR 4134 LAYERDIR
3713 When used inside the ``layer.conf`` configuration file, this variable 4135 When used inside the ``layer.conf`` configuration file, this variable
3714 provides the path of the current layer. This variable is not 4136 provides the path of the current layer. This variable is not
3715 available outside of ``layer.conf`` and references are expanded 4137 available outside of ``layer.conf`` and references are expanded
3716 immediately when parsing of the file completes. 4138 immediately when parsing of the file completes.
3717 4139
3718 LAYERRECOMMENDS 4140 LAYERRECOMMENDS
3719 Lists the layers, separated by spaces, recommended for use with this 4141 Lists the layers, separated by spaces, recommended for use with this
3720 layer. 4142 layer.
3721 4143
3722 Optionally, you can specify a specific layer version for a 4144 Optionally, you can specify a specific layer version for a
3723 recommendation by adding the version to the end of the layer name. 4145 recommendation by adding the version to the end of the layer name.
3724 Here is an example: LAYERRECOMMENDS_mylayer = "anotherlayer (=3)" In 4146 Here is an example:
3725 this previous example, version 3 of "anotherlayer" is compared 4147 ::
4148
4149 LAYERRECOMMENDS_mylayer = "anotherlayer (=3)"
4150
4151 In this previous example, version 3 of "anotherlayer" is compared
3726 against ``LAYERVERSION_anotherlayer``. 4152 against ``LAYERVERSION_anotherlayer``.
3727 4153
3728 This variable is used in the ``conf/layer.conf`` file and must be 4154 This variable is used in the ``conf/layer.conf`` file and must be
3729 suffixed with the name of the specific layer (e.g. 4155 suffixed with the name of the specific layer (e.g.
3730 ``LAYERRECOMMENDS_mylayer``). 4156 ``LAYERRECOMMENDS_mylayer``).
3731 4157
3732 LAYERSERIES_COMPAT 4158 LAYERSERIES_COMPAT
3733 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which 4159 Lists the versions of the :term:`OpenEmbedded-Core (OE-Core)` for which
3734 a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable 4160 a layer is compatible. Using the ``LAYERSERIES_COMPAT`` variable
@@ -3736,27 +4162,28 @@ system and gives an overview of their function and contents.
3736 layer and OE-Core can be expected to work. The variable gives the 4162 layer and OE-Core can be expected to work. The variable gives the
3737 system a way to detect when a layer has not been tested with new 4163 system a way to detect when a layer has not been tested with new
3738 releases of OE-Core (e.g. the layer is not maintained). 4164 releases of OE-Core (e.g. the layer is not maintained).
3739 4165
3740 To specify the OE-Core versions for which a layer is compatible, use 4166 To specify the OE-Core versions for which a layer is compatible, use
3741 this variable in your layer's ``conf/layer.conf`` configuration file. 4167 this variable in your layer's ``conf/layer.conf`` configuration file.
3742 For the list, use the Yocto Project 4168 For the list, use the Yocto Project
3743 :yocto_wiki:`Release Name </wiki/Releases>` (e.g. 4169 :yocto_wiki:`Release Name </wiki/Releases>` (e.g.
3744 DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the 4170 DISTRO_NAME_NO_CAP). To specify multiple OE-Core versions for the
3745 layer, use a space-separated list: LAYERSERIES_COMPAT_layer_root_name 4171 layer, use a space-separated list:
3746 = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE" 4172 ::
3747 4173
4174 LAYERSERIES_COMPAT_layer_root_name = "DISTRO_NAME_NO_CAP DISTRO_NAME_NO_CAP_MINUS_ONE"
4175
3748 .. note:: 4176 .. note::
3749 4177
3750 Setting 4178 Setting
3751 LAYERSERIES_COMPAT 4179 LAYERSERIES_COMPAT
3752 is required by the Yocto Project Compatible version 2 standard. 4180 is required by the Yocto Project Compatible version 2 standard.
3753 The OpenEmbedded build system produces a warning if the variable 4181 The OpenEmbedded build system produces a warning if the variable
3754 is not set for any given layer. 4182 is not set for any given layer.
3755 4183
3756 See the "`Creating Your Own 4184 See the ":ref:`dev-manual/dev-manual-common-tasks:creating your own layer`"
3757 Layer <&YOCTO_DOCS_DEV_URL;#creating-your-own-layer>`__" section in 4185 section in the Yocto Project Development Tasks Manual.
3758 the Yocto Project Development Tasks Manual. 4186
3759
3760 LAYERVERSION 4187 LAYERVERSION
3761 Optionally specifies the version of a layer as a single number. You 4188 Optionally specifies the version of a layer as a single number. You
3762 can use this within :term:`LAYERDEPENDS` for 4189 can use this within :term:`LAYERDEPENDS` for
@@ -3764,90 +4191,98 @@ system and gives an overview of their function and contents.
3764 This variable is used in the ``conf/layer.conf`` file and must be 4191 This variable is used in the ``conf/layer.conf`` file and must be
3765 suffixed with the name of the specific layer (e.g. 4192 suffixed with the name of the specific layer (e.g.
3766 ``LAYERVERSION_mylayer``). 4193 ``LAYERVERSION_mylayer``).
3767 4194
3768 LD 4195 LD
3769 The minimal command and arguments used to run the linker. 4196 The minimal command and arguments used to run the linker.
3770 4197
3771 LDFLAGS 4198 LDFLAGS
3772 Specifies the flags to pass to the linker. This variable is exported 4199 Specifies the flags to pass to the linker. This variable is exported
3773 to an environment variable and thus made visible to the software 4200 to an environment variable and thus made visible to the software
3774 being built during the compilation step. 4201 being built during the compilation step.
3775 4202
3776 Default initialization for ``LDFLAGS`` varies depending on what is 4203 Default initialization for ``LDFLAGS`` varies depending on what is
3777 being built: 4204 being built:
3778 4205
3779 - :term:`TARGET_LDFLAGS` when building for the 4206 - :term:`TARGET_LDFLAGS` when building for the
3780 target 4207 target
3781 4208
3782 - :term:`BUILD_LDFLAGS` when building for the 4209 - :term:`BUILD_LDFLAGS` when building for the
3783 build host (i.e. ``-native``) 4210 build host (i.e. ``-native``)
3784 4211
3785 - :term:`BUILDSDK_LDFLAGS` when building for 4212 - :term:`BUILDSDK_LDFLAGS` when building for
3786 an SDK (i.e. ``nativesdk-``) 4213 an SDK (i.e. ``nativesdk-``)
3787 4214
3788 LEAD_SONAME 4215 LEAD_SONAME
3789 Specifies the lead (or primary) compiled library file (i.e. ``.so``) 4216 Specifies the lead (or primary) compiled library file (i.e. ``.so``)
3790 that the :ref:`debian <ref-classes-debian>` class applies its 4217 that the :ref:`debian <ref-classes-debian>` class applies its
3791 naming policy to given a recipe that packages multiple libraries. 4218 naming policy to given a recipe that packages multiple libraries.
3792 4219
3793 This variable works in conjunction with the ``debian`` class. 4220 This variable works in conjunction with the ``debian`` class.
3794 4221
3795 LIC_FILES_CHKSUM 4222 LIC_FILES_CHKSUM
3796 Checksums of the license text in the recipe source code. 4223 Checksums of the license text in the recipe source code.
3797 4224
3798 This variable tracks changes in license text of the source code 4225 This variable tracks changes in license text of the source code
3799 files. If the license text is changed, it will trigger a build 4226 files. If the license text is changed, it will trigger a build
3800 failure, which gives the developer an opportunity to review any 4227 failure, which gives the developer an opportunity to review any
3801 license change. 4228 license change.
3802 4229
3803 This variable must be defined for all recipes (unless 4230 This variable must be defined for all recipes (unless
3804 :term:`LICENSE` is set to "CLOSED"). 4231 :term:`LICENSE` is set to "CLOSED").
3805 4232
3806 For more information, see the "`Tracking License 4233 For more information, see the ":ref:`usingpoky-configuring-lic_files_chksum`"
3807 Changes <&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-LIC_FILES_CHKSUM>`__"
3808 section in the Yocto Project Development Tasks Manual. 4234 section in the Yocto Project Development Tasks Manual.
3809 4235
3810 LICENSE 4236 LICENSE
3811 The list of source licenses for the recipe. Follow these rules: 4237 The list of source licenses for the recipe. Follow these rules:
3812 4238
3813 - Do not use spaces within individual license names. 4239 - Do not use spaces within individual license names.
3814 4240
3815 - Separate license names using \| (pipe) when there is a choice 4241 - Separate license names using \| (pipe) when there is a choice
3816 between licenses. 4242 between licenses.
3817 4243
3818 - Separate license names using & (ampersand) when multiple licenses 4244 - Separate license names using & (ampersand) when multiple licenses
3819 exist that cover different parts of the source. 4245 exist that cover different parts of the source.
3820 4246
3821 - You can use spaces between license names. 4247 - You can use spaces between license names.
3822 4248
3823 - For standard licenses, use the names of the files in 4249 - For standard licenses, use the names of the files in
3824 ``meta/files/common-licenses/`` or the 4250 ``meta/files/common-licenses/`` or the
3825 :term:`SPDXLICENSEMAP` flag names defined in 4251 :term:`SPDXLICENSEMAP` flag names defined in
3826 ``meta/conf/licenses.conf``. 4252 ``meta/conf/licenses.conf``.
3827 4253
3828 Here are some examples: LICENSE = "LGPLv2.1 \| GPLv3" LICENSE = 4254 Here are some examples:
3829 "MPL-1 & LGPLv2.1" LICENSE = "GPLv2+" The first example is from the 4255 ::
4256
4257 LICENSE = "LGPLv2.1 | GPLv3"
4258 LICENSE = "MPL-1 & LGPLv2.1"
4259 LICENSE = "GPLv2+"
4260
4261 The first example is from the
3830 recipes for Qt, which the user may choose to distribute under either 4262 recipes for Qt, which the user may choose to distribute under either
3831 the LGPL version 2.1 or GPL version 3. The second example is from 4263 the LGPL version 2.1 or GPL version 3. The second example is from
3832 Cairo where two licenses cover different parts of the source code. 4264 Cairo where two licenses cover different parts of the source code.
3833 The final example is from ``sysstat``, which presents a single 4265 The final example is from ``sysstat``, which presents a single
3834 license. 4266 license.
3835 4267
3836 You can also specify licenses on a per-package basis to handle 4268 You can also specify licenses on a per-package basis to handle
3837 situations where components of the output have different licenses. 4269 situations where components of the output have different licenses.
3838 For example, a piece of software whose code is licensed under GPLv2 4270 For example, a piece of software whose code is licensed under GPLv2
3839 but has accompanying documentation licensed under the GNU Free 4271 but has accompanying documentation licensed under the GNU Free
3840 Documentation License 1.2 could be specified as follows: LICENSE = 4272 Documentation License 1.2 could be specified as follows:
3841 "GFDL-1.2 & GPLv2" LICENSE_${PN} = "GPLv2" LICENSE_${PN}-doc = 4273 ::
3842 "GFDL-1.2" 4274
3843 4275 LICENSE = "GFDL-1.2 & GPLv2"
4276 LICENSE_${PN} = "GPLv2"
4277 LICENSE_${PN}-doc = "GFDL-1.2"
4278
3844 LICENSE_CREATE_PACKAGE 4279 LICENSE_CREATE_PACKAGE
3845 Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded 4280 Setting ``LICENSE_CREATE_PACKAGE`` to "1" causes the OpenEmbedded
3846 build system to create an extra package (i.e. 4281 build system to create an extra package (i.e.
3847 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add 4282 ``${``\ :term:`PN`\ ``}-lic``) for each recipe and to add
3848 those packages to the 4283 those packages to the
3849 :term:`RRECOMMENDS`\ ``_${PN}``. 4284 :term:`RRECOMMENDS`\ ``_${PN}``.
3850 4285
3851 The ``${PN}-lic`` package installs a directory in 4286 The ``${PN}-lic`` package installs a directory in
3852 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base 4287 ``/usr/share/licenses`` named ``${PN}``, which is the recipe's base
3853 name, and installs files in that directory that contain license and 4288 name, and installs files in that directory that contain license and
@@ -3857,124 +4292,149 @@ system and gives an overview of their function and contents.
3857 and copies of files marked in 4292 and copies of files marked in
3858 :term:`LIC_FILES_CHKSUM` as containing 4293 :term:`LIC_FILES_CHKSUM` as containing
3859 license text). 4294 license text).
3860 4295
3861 For related information on providing license text, see the 4296 For related information on providing license text, see the
3862 :term:`COPY_LIC_DIRS` variable, the 4297 :term:`COPY_LIC_DIRS` variable, the
3863 :term:`COPY_LIC_MANIFEST` variable, and the 4298 :term:`COPY_LIC_MANIFEST` variable, and the
3864 "`Providing License 4299 ":ref:`dev-manual/dev-manual-common-tasks:providing license text`"
3865 Text <&YOCTO_DOCS_DEV_URL;#providing-license-text>`__" section in the 4300 section in the Yocto Project Development Tasks Manual.
3866 Yocto Project Development Tasks Manual. 4301
3867
3868 LICENSE_FLAGS 4302 LICENSE_FLAGS
3869 Specifies additional flags for a recipe you must whitelist through 4303 Specifies additional flags for a recipe you must whitelist through
3870 :term:`LICENSE_FLAGS_WHITELIST` in 4304 :term:`LICENSE_FLAGS_WHITELIST` in
3871 order to allow the recipe to be built. When providing multiple flags, 4305 order to allow the recipe to be built. When providing multiple flags,
3872 separate them with spaces. 4306 separate them with spaces.
3873 4307
3874 This value is independent of :term:`LICENSE` and is 4308 This value is independent of :term:`LICENSE` and is
3875 typically used to mark recipes that might require additional licenses 4309 typically used to mark recipes that might require additional licenses
3876 in order to be used in a commercial product. For more information, 4310 in order to be used in a commercial product. For more information,
3877 see the "`Enabling Commercially Licensed 4311 see the
3878 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__" 4312 ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`"
3879 section in the Yocto Project Development Tasks Manual. 4313 section in the Yocto Project Development Tasks Manual.
3880 4314
3881 LICENSE_FLAGS_WHITELIST 4315 LICENSE_FLAGS_WHITELIST
3882 Lists license flags that when specified in 4316 Lists license flags that when specified in
3883 :term:`LICENSE_FLAGS` within a recipe should not 4317 :term:`LICENSE_FLAGS` within a recipe should not
3884 prevent that recipe from being built. This practice is otherwise 4318 prevent that recipe from being built. This practice is otherwise
3885 known as "whitelisting" license flags. For more information, see the 4319 known as "whitelisting" license flags. For more information, see the
3886 "`Enabling Commercially Licensed 4320 ":ref:`dev-manual/dev-manual-common-tasks:enabling commercially licensed recipes`"
3887 Recipes <&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes>`__"
3888 section in the Yocto Project Development Tasks Manual. 4321 section in the Yocto Project Development Tasks Manual.
3889 4322
3890 LICENSE_PATH 4323 LICENSE_PATH
3891 Path to additional licenses used during the build. By default, the 4324 Path to additional licenses used during the build. By default, the
3892 OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the 4325 OpenEmbedded build system uses ``COMMON_LICENSE_DIR`` to define the
3893 directory that holds common license text used during the build. The 4326 directory that holds common license text used during the build. The
3894 ``LICENSE_PATH`` variable allows you to extend that location to other 4327 ``LICENSE_PATH`` variable allows you to extend that location to other
3895 areas that have additional licenses: LICENSE_PATH += 4328 areas that have additional licenses:
3896 "path-to-additional-common-licenses" 4329 ::
3897 4330
4331 LICENSE_PATH += "path-to-additional-common-licenses"
4332
3898 LINUX_KERNEL_TYPE 4333 LINUX_KERNEL_TYPE
3899 Defines the kernel type to be used in assembling the configuration. 4334 Defines the kernel type to be used in assembling the configuration.
3900 The linux-yocto recipes define "standard", "tiny", and "preempt-rt" 4335 The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
3901 kernel types. See the "`Kernel 4336 kernel types. See the ":ref:`kernel-dev/kernel-dev-advanced:kernel types`"
3902 Types <&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types>`__" section in the 4337 section in the
3903 Yocto Project Linux Kernel Development Manual for more information on 4338 Yocto Project Linux Kernel Development Manual for more information on
3904 kernel types. 4339 kernel types.
3905 4340
3906 If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to 4341 If you do not specify a ``LINUX_KERNEL_TYPE``, it defaults to
3907 "standard". Together with :term:`KMACHINE`, the 4342 "standard". Together with :term:`KMACHINE`, the
3908 ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by 4343 ``LINUX_KERNEL_TYPE`` variable defines the search arguments used by
3909 the kernel tools to find the appropriate description within the 4344 the kernel tools to find the appropriate description within the
3910 kernel :term:`Metadata` with which to build out the sources 4345 kernel :term:`Metadata` with which to build out the sources
3911 and configuration. 4346 and configuration.
3912 4347
3913 LINUX_VERSION 4348 LINUX_VERSION
3914 The Linux version from ``kernel.org`` on which the Linux kernel image 4349 The Linux version from ``kernel.org`` on which the Linux kernel image
3915 being built using the OpenEmbedded build system is based. You define 4350 being built using the OpenEmbedded build system is based. You define
3916 this variable in the kernel recipe. For example, the 4351 this variable in the kernel recipe. For example, the
3917 ``linux-yocto-3.4.bb`` kernel recipe found in 4352 ``linux-yocto-3.4.bb`` kernel recipe found in
3918 ``meta/recipes-kernel/linux`` defines the variables as follows: 4353 ``meta/recipes-kernel/linux`` defines the variables as follows:
3919 LINUX_VERSION ?= "3.4.24" 4354 ::
3920 4355
4356 LINUX_VERSION ?= "3.4.24"
4357
3921 The ``LINUX_VERSION`` variable is used to define :term:`PV` 4358 The ``LINUX_VERSION`` variable is used to define :term:`PV`
3922 for the recipe: PV = "${LINUX_VERSION}+git${SRCPV}" 4359 for the recipe:
3923 4360 ::
4361
4362 PV = "${LINUX_VERSION}+git${SRCPV}"
4363
3924 LINUX_VERSION_EXTENSION 4364 LINUX_VERSION_EXTENSION
3925 A string extension compiled into the version string of the Linux 4365 A string extension compiled into the version string of the Linux
3926 kernel built with the OpenEmbedded build system. You define this 4366 kernel built with the OpenEmbedded build system. You define this
3927 variable in the kernel recipe. For example, the linux-yocto kernel 4367 variable in the kernel recipe. For example, the linux-yocto kernel
3928 recipes all define the variable as follows: LINUX_VERSION_EXTENSION 4368 recipes all define the variable as follows:
3929 ?= "-yocto-${:term:`LINUX_KERNEL_TYPE`}" 4369 ::
3930 4370
4371 LINUX_VERSION_EXTENSION ?= "-yocto-${LINUX_KERNEL_TYPE}"
4372
3931 Defining this variable essentially sets the Linux kernel 4373 Defining this variable essentially sets the Linux kernel
3932 configuration item ``CONFIG_LOCALVERSION``, which is visible through 4374 configuration item ``CONFIG_LOCALVERSION``, which is visible through
3933 the ``uname`` command. Here is an example that shows the extension 4375 the ``uname`` command. Here is an example that shows the extension
3934 assuming it was set as previously shown: $ uname -r 3.7.0-rc8-custom 4376 assuming it was set as previously shown:
3935 4377 ::
4378
4379 $ uname -r
4380 3.7.0-rc8-custom
4381
3936 LOG_DIR 4382 LOG_DIR
3937 Specifies the directory to which the OpenEmbedded build system writes 4383 Specifies the directory to which the OpenEmbedded build system writes
3938 overall log files. The default directory is ``${TMPDIR}/log``. 4384 overall log files. The default directory is ``${TMPDIR}/log``.
3939 4385
3940 For the directory containing logs specific to each task, see the 4386 For the directory containing logs specific to each task, see the
3941 :term:`T` variable. 4387 :term:`T` variable.
3942 4388
3943 MACHINE 4389 MACHINE
3944 Specifies the target device for which the image is built. You define 4390 Specifies the target device for which the image is built. You define
3945 ``MACHINE`` in the ``local.conf`` file found in the 4391 ``MACHINE`` in the ``local.conf`` file found in the
3946 :term:`Build Directory`. By default, ``MACHINE`` is set to 4392 :term:`Build Directory`. By default, ``MACHINE`` is set to
3947 "qemux86", which is an x86-based architecture machine to be emulated 4393 "qemux86", which is an x86-based architecture machine to be emulated
3948 using QEMU: MACHINE ?= "qemux86" 4394 using QEMU:
3949 4395 ::
4396
4397 MACHINE ?= "qemux86"
4398
3950 The variable corresponds to a machine configuration file of the same 4399 The variable corresponds to a machine configuration file of the same
3951 name, through which machine-specific configurations are set. Thus, 4400 name, through which machine-specific configurations are set. Thus,
3952 when ``MACHINE`` is set to "qemux86" there exists the corresponding 4401 when ``MACHINE`` is set to "qemux86" there exists the corresponding
3953 ``qemux86.conf`` machine configuration file, which can be found in 4402 ``qemux86.conf`` machine configuration file, which can be found in
3954 the :term:`Source Directory` in 4403 the :term:`Source Directory` in
3955 ``meta/conf/machine``. 4404 ``meta/conf/machine``.
3956 4405
3957 The list of machines supported by the Yocto Project as shipped 4406 The list of machines supported by the Yocto Project as shipped
3958 include the following: MACHINE ?= "qemuarm" MACHINE ?= "qemuarm64" 4407 include the following:
3959 MACHINE ?= "qemumips" MACHINE ?= "qemumips64" MACHINE ?= "qemuppc" 4408 ::
3960 MACHINE ?= "qemux86" MACHINE ?= "qemux86-64" MACHINE ?= "genericx86" 4409
3961 MACHINE ?= "genericx86-64" MACHINE ?= "beaglebone" MACHINE ?= 4410 MACHINE ?= "qemuarm"
3962 "edgerouter" The last five are Yocto Project reference hardware 4411 MACHINE ?= "qemuarm64"
4412 MACHINE ?= "qemumips"
4413 MACHINE ?= "qemumips64"
4414 MACHINE ?= "qemuppc"
4415 MACHINE ?= "qemux86"
4416 MACHINE ?= "qemux86-64"
4417 MACHINE ?= "genericx86"
4418 MACHINE ?= "genericx86-64"
4419 MACHINE ?= "beaglebone"
4420 MACHINE ?= "edgerouter"
4421
4422 The last five are Yocto Project reference hardware
3963 boards, which are provided in the ``meta-yocto-bsp`` layer. 4423 boards, which are provided in the ``meta-yocto-bsp`` layer.
3964 4424
3965 .. note:: 4425 .. note::
3966 4426
3967 Adding additional Board Support Package (BSP) layers to your 4427 Adding additional Board Support Package (BSP) layers to your
3968 configuration adds new possible settings for 4428 configuration adds new possible settings for
3969 MACHINE 4429 MACHINE
3970 . 4430 .
3971 4431
3972 MACHINE_ARCH 4432 MACHINE_ARCH
3973 Specifies the name of the machine-specific architecture. This 4433 Specifies the name of the machine-specific architecture. This
3974 variable is set automatically from :term:`MACHINE` or 4434 variable is set automatically from :term:`MACHINE` or
3975 :term:`TUNE_PKGARCH`. You should not hand-edit 4435 :term:`TUNE_PKGARCH`. You should not hand-edit
3976 the ``MACHINE_ARCH`` variable. 4436 the ``MACHINE_ARCH`` variable.
3977 4437
3978 MACHINE_ESSENTIAL_EXTRA_RDEPENDS 4438 MACHINE_ESSENTIAL_EXTRA_RDEPENDS
3979 A list of required machine-specific packages to install as part of 4439 A list of required machine-specific packages to install as part of
3980 the image being built. The build process depends on these packages 4440 the image being built. The build process depends on these packages
@@ -3983,19 +4443,21 @@ system and gives an overview of their function and contents.
3983 The impact of this variable affects images based on 4443 The impact of this variable affects images based on
3984 ``packagegroup-core-boot``, including the ``core-image-minimal`` 4444 ``packagegroup-core-boot``, including the ``core-image-minimal``
3985 image. 4445 image.
3986 4446
3987 This variable is similar to the 4447 This variable is similar to the
3988 ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception 4448 ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` variable with the exception
3989 that the image being built has a build dependency on the variable's 4449 that the image being built has a build dependency on the variable's
3990 list of packages. In other words, the image will not build if a file 4450 list of packages. In other words, the image will not build if a file
3991 in this list is not found. 4451 in this list is not found.
3992 4452
3993 As an example, suppose the machine for which you are building 4453 As an example, suppose the machine for which you are building
3994 requires ``example-init`` to be run during boot to initialize the 4454 requires ``example-init`` to be run during boot to initialize the
3995 hardware. In this case, you would use the following in the machine's 4455 hardware. In this case, you would use the following in the machine's
3996 ``.conf`` configuration file: MACHINE_ESSENTIAL_EXTRA_RDEPENDS += 4456 ``.conf`` configuration file:
3997 "example-init" 4457 ::
3998 4458
4459 MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
4460
3999 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS 4461 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS
4000 A list of recommended machine-specific packages to install as part of 4462 A list of recommended machine-specific packages to install as part of
4001 the image being built. The build process does not depend on these 4463 the image being built. The build process does not depend on these
@@ -4004,7 +4466,7 @@ system and gives an overview of their function and contents.
4004 the machine to boot. The impact of this variable affects images based 4466 the machine to boot. The impact of this variable affects images based
4005 on ``packagegroup-core-boot``, including the ``core-image-minimal`` 4467 on ``packagegroup-core-boot``, including the ``core-image-minimal``
4006 image. 4468 image.
4007 4469
4008 This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` 4470 This variable is similar to the ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS``
4009 variable with the exception that the image being built does not have 4471 variable with the exception that the image being built does not have
4010 a build dependency on the variable's list of packages. In other 4472 a build dependency on the variable's list of packages. In other
@@ -4013,7 +4475,7 @@ system and gives an overview of their function and contents.
4013 modules, whose functionality may be selected to be built into the 4475 modules, whose functionality may be selected to be built into the
4014 kernel rather than as a module, in which case a package will not be 4476 kernel rather than as a module, in which case a package will not be
4015 produced. 4477 produced.
4016 4478
4017 Consider an example where you have a custom kernel where a specific 4479 Consider an example where you have a custom kernel where a specific
4018 touchscreen driver is required for the machine to be usable. However, 4480 touchscreen driver is required for the machine to be usable. However,
4019 the driver can be built as a module or into the kernel depending on 4481 the driver can be built as a module or into the kernel depending on
@@ -4024,10 +4486,12 @@ system and gives an overview of their function and contents.
4024 not fail due to the missing package. To accomplish this, assuming the 4486 not fail due to the missing package. To accomplish this, assuming the
4025 package for the module was called ``kernel-module-ab123``, you would 4487 package for the module was called ``kernel-module-ab123``, you would
4026 use the following in the machine's ``.conf`` configuration file: 4488 use the following in the machine's ``.conf`` configuration file:
4027 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123" 4489 ::
4028 4490
4491 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
4492
4029 .. note:: 4493 .. note::
4030 4494
4031 In this example, the 4495 In this example, the
4032 kernel-module-ab123 4496 kernel-module-ab123
4033 recipe needs to explicitly set its 4497 recipe needs to explicitly set its
@@ -4035,25 +4499,25 @@ system and gives an overview of their function and contents.
4035 variable to ensure that BitBake does not use the kernel recipe's 4499 variable to ensure that BitBake does not use the kernel recipe's
4036 PACKAGES_DYNAMIC 4500 PACKAGES_DYNAMIC
4037 variable to satisfy the dependency. 4501 variable to satisfy the dependency.
4038 4502
4039 Some examples of these machine essentials are flash, screen, 4503 Some examples of these machine essentials are flash, screen,
4040 keyboard, mouse, or touchscreen drivers (depending on the machine). 4504 keyboard, mouse, or touchscreen drivers (depending on the machine).
4041 4505
4042 MACHINE_EXTRA_RDEPENDS 4506 MACHINE_EXTRA_RDEPENDS
4043 A list of machine-specific packages to install as part of the image 4507 A list of machine-specific packages to install as part of the image
4044 being built that are not essential for the machine to boot. However, 4508 being built that are not essential for the machine to boot. However,
4045 the build process for more fully-featured images depends on the 4509 the build process for more fully-featured images depends on the
4046 packages being present. 4510 packages being present.
4047 4511
4048 This variable affects all images based on ``packagegroup-base``, 4512 This variable affects all images based on ``packagegroup-base``,
4049 which does not include the ``core-image-minimal`` or 4513 which does not include the ``core-image-minimal`` or
4050 ``core-image-full-cmdline`` images. 4514 ``core-image-full-cmdline`` images.
4051 4515
4052 The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable 4516 The variable is similar to the ``MACHINE_EXTRA_RRECOMMENDS`` variable
4053 with the exception that the image being built has a build dependency 4517 with the exception that the image being built has a build dependency
4054 on the variable's list of packages. In other words, the image will 4518 on the variable's list of packages. In other words, the image will
4055 not build if a file in this list is not found. 4519 not build if a file in this list is not found.
4056 4520
4057 An example is a machine that has WiFi capability but is not essential 4521 An example is a machine that has WiFi capability but is not essential
4058 for the machine to boot the image. However, if you are building a 4522 for the machine to boot the image. However, if you are building a
4059 more fully-featured image, you want to enable the WiFi. The package 4523 more fully-featured image, you want to enable the WiFi. The package
@@ -4062,22 +4526,24 @@ system and gives an overview of their function and contents.
4062 finding the package. In this case, assuming the package for the 4526 finding the package. In this case, assuming the package for the
4063 firmware was called ``wifidriver-firmware``, you would use the 4527 firmware was called ``wifidriver-firmware``, you would use the
4064 following in the ``.conf`` file for the machine: 4528 following in the ``.conf`` file for the machine:
4065 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware" 4529 ::
4066 4530
4531 MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
4532
4067 MACHINE_EXTRA_RRECOMMENDS 4533 MACHINE_EXTRA_RRECOMMENDS
4068 A list of machine-specific packages to install as part of the image 4534 A list of machine-specific packages to install as part of the image
4069 being built that are not essential for booting the machine. The image 4535 being built that are not essential for booting the machine. The image
4070 being built has no build dependency on this list of packages. 4536 being built has no build dependency on this list of packages.
4071 4537
4072 This variable affects only images based on ``packagegroup-base``, 4538 This variable affects only images based on ``packagegroup-base``,
4073 which does not include the ``core-image-minimal`` or 4539 which does not include the ``core-image-minimal`` or
4074 ``core-image-full-cmdline`` images. 4540 ``core-image-full-cmdline`` images.
4075 4541
4076 This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable 4542 This variable is similar to the ``MACHINE_EXTRA_RDEPENDS`` variable
4077 with the exception that the image being built does not have a build 4543 with the exception that the image being built does not have a build
4078 dependency on the variable's list of packages. In other words, the 4544 dependency on the variable's list of packages. In other words, the
4079 image will build if a file in this list is not found. 4545 image will build if a file in this list is not found.
4080 4546
4081 An example is a machine that has WiFi capability but is not essential 4547 An example is a machine that has WiFi capability but is not essential
4082 For the machine to boot the image. However, if you are building a 4548 For the machine to boot the image. However, if you are building a
4083 more fully-featured image, you want to enable WiFi. In this case, the 4549 more fully-featured image, you want to enable WiFi. In this case, the
@@ -4087,8 +4553,10 @@ system and gives an overview of their function and contents.
4087 not being found. To accomplish this, assuming the package for the 4553 not being found. To accomplish this, assuming the package for the
4088 module was called ``kernel-module-examplewifi``, you would use the 4554 module was called ``kernel-module-examplewifi``, you would use the
4089 following in the ``.conf`` file for the machine: 4555 following in the ``.conf`` file for the machine:
4090 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi" 4556 ::
4091 4557
4558 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
4559
4092 MACHINE_FEATURES 4560 MACHINE_FEATURES
4093 Specifies the list of hardware features the 4561 Specifies the list of hardware features the
4094 :term:`MACHINE` is capable of supporting. For related 4562 :term:`MACHINE` is capable of supporting. For related
@@ -4096,48 +4564,59 @@ system and gives an overview of their function and contents.
4096 :term:`DISTRO_FEATURES`, 4564 :term:`DISTRO_FEATURES`,
4097 :term:`COMBINED_FEATURES`, and 4565 :term:`COMBINED_FEATURES`, and
4098 :term:`IMAGE_FEATURES` variables. 4566 :term:`IMAGE_FEATURES` variables.
4099 4567
4100 For a list of hardware features supported by the Yocto Project as 4568 For a list of hardware features supported by the Yocto Project as
4101 shipped, see the "`Machine Features <#ref-features-machine>`__" 4569 shipped, see the "`Machine Features <#ref-features-machine>`__"
4102 section. 4570 section.
4103 4571
4104 MACHINE_FEATURES_BACKFILL 4572 MACHINE_FEATURES_BACKFILL
4105 Features to be added to ``MACHINE_FEATURES`` if not also present in 4573 Features to be added to ``MACHINE_FEATURES`` if not also present in
4106 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``. 4574 ``MACHINE_FEATURES_BACKFILL_CONSIDERED``.
4107 4575
4108 This variable is set in the ``meta/conf/bitbake.conf`` file. It is 4576 This variable is set in the ``meta/conf/bitbake.conf`` file. It is
4109 not intended to be user-configurable. It is best to just reference 4577 not intended to be user-configurable. It is best to just reference
4110 the variable to see which machine features are being backfilled for 4578 the variable to see which machine features are being backfilled for
4111 all machine configurations. See the "`Feature 4579 all machine configurations. See the "`Feature
4112 Backfilling <#ref-features-backfill>`__" section for more 4580 Backfilling <#ref-features-backfill>`__" section for more
4113 information. 4581 information.
4114 4582
4115 MACHINE_FEATURES_BACKFILL_CONSIDERED 4583 MACHINE_FEATURES_BACKFILL_CONSIDERED
4116 Features from ``MACHINE_FEATURES_BACKFILL`` that should not be 4584 Features from ``MACHINE_FEATURES_BACKFILL`` that should not be
4117 backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See 4585 backfilled (i.e. added to ``MACHINE_FEATURES``) during the build. See
4118 the "`Feature Backfilling <#ref-features-backfill>`__" section for 4586 the "`Feature Backfilling <#ref-features-backfill>`__" section for
4119 more information. 4587 more information.
4120 4588
4121 MACHINEOVERRIDES 4589 MACHINEOVERRIDES
4122 A colon-separated list of overrides that apply to the current 4590 A colon-separated list of overrides that apply to the current
4123 machine. By default, this list includes the value of 4591 machine. By default, this list includes the value of
4124 :term:`MACHINE`. 4592 :term:`MACHINE`.
4125 4593
4126 You can extend ``MACHINEOVERRIDES`` to add extra overrides that 4594 You can extend ``MACHINEOVERRIDES`` to add extra overrides that
4127 should apply to a machine. For example, all machines emulated in QEMU 4595 should apply to a machine. For example, all machines emulated in QEMU
4128 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named 4596 (e.g. ``qemuarm``, ``qemux86``, and so forth) include a file named
4129 ``meta/conf/machine/include/qemu.inc`` that prepends the following 4597 ``meta/conf/machine/include/qemu.inc`` that prepends the following
4130 override to ``MACHINEOVERRIDES``: MACHINEOVERRIDES =. "qemuall:" This 4598 override to ``MACHINEOVERRIDES``:
4599 ::
4600
4601 MACHINEOVERRIDES =. "qemuall:"
4602
4603 This
4131 override allows variables to be overriden for all machines emulated 4604 override allows variables to be overriden for all machines emulated
4132 in QEMU, like in the following example from the ``connman-conf`` 4605 in QEMU, like in the following example from the ``connman-conf``
4133 recipe: SRC_URI_append_qemuall = "file://wired.config \\ 4606 recipe:
4134 file://wired-setup \\ " The underlying mechanism behind 4607 ::
4608
4609 SRC_URI_append_qemuall = "file://wired.config \
4610 file://wired-setup \
4611 "
4612
4613 The underlying mechanism behind
4135 ``MACHINEOVERRIDES`` is simply that it is included in the default 4614 ``MACHINEOVERRIDES`` is simply that it is included in the default
4136 value of :term:`OVERRIDES`. 4615 value of :term:`OVERRIDES`.
4137 4616
4138 MAINTAINER 4617 MAINTAINER
4139 The email address of the distribution maintainer. 4618 The email address of the distribution maintainer.
4140 4619
4141 MIRRORS 4620 MIRRORS
4142 Specifies additional paths from which the OpenEmbedded build system 4621 Specifies additional paths from which the OpenEmbedded build system
4143 gets source code. When the build system searches for source code, it 4622 gets source code. When the build system searches for source code, it
@@ -4145,20 +4624,20 @@ system and gives an overview of their function and contents.
4145 build system tries locations defined by 4624 build system tries locations defined by
4146 :term:`PREMIRRORS`, the upstream source, and then 4625 :term:`PREMIRRORS`, the upstream source, and then
4147 locations specified by ``MIRRORS`` in that order. 4626 locations specified by ``MIRRORS`` in that order.
4148 4627
4149 Assuming your distribution (:term:`DISTRO`) is "poky", 4628 Assuming your distribution (:term:`DISTRO`) is "poky",
4150 the default value for ``MIRRORS`` is defined in the 4629 the default value for ``MIRRORS`` is defined in the
4151 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. 4630 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
4152 4631
4153 MLPREFIX 4632 MLPREFIX
4154 Specifies a prefix has been added to :term:`PN` to create a 4633 Specifies a prefix has been added to :term:`PN` to create a
4155 special version of a recipe or package (i.e. a Multilib version). The 4634 special version of a recipe or package (i.e. a Multilib version). The
4156 variable is used in places where the prefix needs to be added to or 4635 variable is used in places where the prefix needs to be added to or
4157 removed from a the name (e.g. the :term:`BPN` variable). 4636 removed from a the name (e.g. the :term:`BPN` variable).
4158 ``MLPREFIX`` gets set when a prefix has been added to ``PN``. 4637 ``MLPREFIX`` gets set when a prefix has been added to ``PN``.
4159 4638
4160 .. note:: 4639 .. note::
4161 4640
4162 The "ML" in 4641 The "ML" in
4163 MLPREFIX 4642 MLPREFIX
4164 stands for "MultiLib". This representation is historical and comes 4643 stands for "MultiLib". This representation is historical and comes
@@ -4169,7 +4648,7 @@ system and gives an overview of their function and contents.
4169 was turned into a prefix, it made sense to set 4648 was turned into a prefix, it made sense to set
4170 MLPREFIX 4649 MLPREFIX
4171 for it as well. 4650 for it as well.
4172 4651
4173 To help understand when ``MLPREFIX`` might be needed, consider when 4652 To help understand when ``MLPREFIX`` might be needed, consider when
4174 :term:`BBCLASSEXTEND` is used to provide a 4653 :term:`BBCLASSEXTEND` is used to provide a
4175 ``nativesdk`` version of a recipe in addition to the target version. 4654 ``nativesdk`` version of a recipe in addition to the target version.
@@ -4177,25 +4656,37 @@ system and gives an overview of their function and contents.
4177 recipes by using :term:`DEPENDS`, then a dependency on 4656 recipes by using :term:`DEPENDS`, then a dependency on
4178 "foo" will automatically get rewritten to a dependency on 4657 "foo" will automatically get rewritten to a dependency on
4179 "nativesdk-foo". However, dependencies like the following will not 4658 "nativesdk-foo". However, dependencies like the following will not
4180 get rewritten automatically: do_foo[depends] += "recipe:do_foo" If 4659 get rewritten automatically:
4181 you want such a dependency to also get transformed, you can do the 4660 ::
4182 following: do_foo[depends] += "${MLPREFIX}recipe:do_foo" 4661
4183 4662 do_foo[depends] += "recipe:do_foo"
4663
4664 If you want such a dependency to also get transformed, you can do the
4665 following:
4666 ::
4667
4668 do_foo[depends] += "${MLPREFIX}recipe:do_foo"
4669
4184 module_autoload 4670 module_autoload
4185 This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD`` 4671 This variable has been replaced by the ``KERNEL_MODULE_AUTOLOAD``
4186 variable. You should replace all occurrences of ``module_autoload`` 4672 variable. You should replace all occurrences of ``module_autoload``
4187 with additions to ``KERNEL_MODULE_AUTOLOAD``, for example: 4673 with additions to ``KERNEL_MODULE_AUTOLOAD``, for example:
4188 module_autoload_rfcomm = "rfcomm" 4674 ::
4189 4675
4190 should now be replaced with: KERNEL_MODULE_AUTOLOAD += "rfcomm" See 4676 module_autoload_rfcomm = "rfcomm"
4191 the :term:`KERNEL_MODULE_AUTOLOAD` 4677
4192 variable for more information. 4678 should now be replaced with:
4193 4679 ::
4680
4681 KERNEL_MODULE_AUTOLOAD += "rfcomm"
4682
4683 See the :term:`KERNEL_MODULE_AUTOLOAD` variable for more information.
4684
4194 module_conf 4685 module_conf
4195 Specifies ```modprobe.d`http://linux.die.net/man/5/modprobe.d 4686 Specifies `modprobe.d <http://linux.die.net/man/5/modprobe.d>`_
4196 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf`` 4687 syntax lines for inclusion in the ``/etc/modprobe.d/modname.conf``
4197 file. 4688 file.
4198 4689
4199 You can use this variable anywhere that it can be recognized by the 4690 You can use this variable anywhere that it can be recognized by the
4200 kernel recipe or out-of-tree kernel module recipe (e.g. a machine 4691 kernel recipe or out-of-tree kernel module recipe (e.g. a machine
4201 configuration file, a distribution configuration file, an append file 4692 configuration file, a distribution configuration file, an append file
@@ -4203,64 +4694,80 @@ system and gives an overview of their function and contents.
4203 must also be sure to list the module name in the 4694 must also be sure to list the module name in the
4204 :term:`KERNEL_MODULE_AUTOLOAD` 4695 :term:`KERNEL_MODULE_AUTOLOAD`
4205 variable. 4696 variable.
4206 4697
4207 Here is the general syntax: module_conf_module_name = 4698 Here is the general syntax:
4208 "modprobe.d-syntax" You must use the kernel module name override. 4699 ::
4209 4700
4701 module_conf_module_name = "modprobe.d-syntax"
4702
4703 You must use the kernel module name override.
4704
4210 Run ``man modprobe.d`` in the shell to find out more information on 4705 Run ``man modprobe.d`` in the shell to find out more information on
4211 the exact syntax you want to provide with ``module_conf``. 4706 the exact syntax you want to provide with ``module_conf``.
4212 4707
4213 Including ``module_conf`` causes the OpenEmbedded build system to 4708 Including ``module_conf`` causes the OpenEmbedded build system to
4214 populate the ``/etc/modprobe.d/modname.conf`` file with 4709 populate the ``/etc/modprobe.d/modname.conf`` file with
4215 ``modprobe.d`` syntax lines. Here is an example that adds the options 4710 ``modprobe.d`` syntax lines. Here is an example that adds the options
4216 ``arg1`` and ``arg2`` to a module named ``mymodule``: 4711 ``arg1`` and ``arg2`` to a module named ``mymodule``:
4217 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2" 4712 ::
4218 4713
4714 module_conf_mymodule = "options mymodule arg1=val1 arg2=val2"
4715
4219 For information on how to specify kernel modules to auto-load on 4716 For information on how to specify kernel modules to auto-load on
4220 boot, see the 4717 boot, see the :term:`KERNEL_MODULE_AUTOLOAD` variable.
4221 :term:`KERNEL_MODULE_AUTOLOAD` 4718
4222 variable.
4223
4224 MODULE_TARBALL_DEPLOY 4719 MODULE_TARBALL_DEPLOY
4225 Controls creation of the ``modules-*.tgz`` file. Set this variable to 4720 Controls creation of the ``modules-*.tgz`` file. Set this variable to
4226 "0" to disable creation of this file, which contains all of the 4721 "0" to disable creation of this file, which contains all of the
4227 kernel modules resulting from a kernel build. 4722 kernel modules resulting from a kernel build.
4228 4723
4229 MODULE_TARBALL_LINK_NAME 4724 MODULE_TARBALL_LINK_NAME
4230 The link name of the kernel module tarball. This variable is set in 4725 The link name of the kernel module tarball. This variable is set in
4231 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 4726 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4232 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}" The value 4727 ::
4728
4729 MODULE_TARBALL_LINK_NAME ?= "${KERNEL_ARTIFACT_LINK_NAME}"
4730
4731 The value
4233 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the 4732 of the ``KERNEL_ARTIFACT_LINK_NAME`` variable, which is set in the
4234 same file, has the following value: KERNEL_ARTIFACT_LINK_NAME ?= 4733 same file, has the following value:
4235 "${MACHINE}" 4734 ::
4236 4735
4237 See the :term:`MACHINE` variable for additional 4736 KERNEL_ARTIFACT_LINK_NAME ?= "${MACHINE}"
4238 information. 4737
4239 4738 See the :term:`MACHINE` variable for additional information.
4739
4240 MODULE_TARBALL_NAME 4740 MODULE_TARBALL_NAME
4241 The base name of the kernel module tarball. This variable is set in 4741 The base name of the kernel module tarball. This variable is set in
4242 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows: 4742 the ``meta/classes/kernel-artifact-names.bbclass`` file as follows:
4243 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}" The value of the 4743 ::
4244 :term:`KERNEL_ARTIFACT_NAME` variable, 4744
4745 MODULE_TARBALL_NAME ?= "${KERNEL_ARTIFACT_NAME}"
4746
4747 The value of the :term:`KERNEL_ARTIFACT_NAME` variable,
4245 which is set in the same file, has the following value: 4748 which is set in the same file, has the following value:
4246 KERNEL_ARTIFACT_NAME ?= 4749 ::
4247 "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}" 4750
4248 4751 KERNEL_ARTIFACT_NAME ?= "${PKGE}-${PKGV}-${PKGR}-${MACHINE}${IMAGE_VERSION_SUFFIX}"
4752
4249 MULTIMACH_TARGET_SYS 4753 MULTIMACH_TARGET_SYS
4250 Uniquely identifies the type of the target system for which packages 4754 Uniquely identifies the type of the target system for which packages
4251 are being built. This variable allows output for different types of 4755 are being built. This variable allows output for different types of
4252 target systems to be put into different subdirectories of the same 4756 target systems to be put into different subdirectories of the same
4253 output directory. 4757 output directory.
4254 4758
4255 The default value of this variable is: 4759 The default value of this variable is:
4256 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS} Some classes (e.g. 4760 ::
4761
4762 ${PACKAGE_ARCH}${TARGET_VENDOR}-${TARGET_OS}
4763
4764 Some classes (e.g.
4257 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the 4765 :ref:`cross-canadian <ref-classes-cross-canadian>`) modify the
4258 ``MULTIMACH_TARGET_SYS`` value. 4766 ``MULTIMACH_TARGET_SYS`` value.
4259 4767
4260 See the :term:`STAMP` variable for an example. See the 4768 See the :term:`STAMP` variable for an example. See the
4261 :term:`STAGING_DIR_TARGET` variable for 4769 :term:`STAGING_DIR_TARGET` variable for more information.
4262 more information. 4770
4263
4264 NATIVELSBSTRING 4771 NATIVELSBSTRING
4265 A string identifying the host distribution. Strings consist of the 4772 A string identifying the host distribution. Strings consist of the
4266 host distributor ID followed by the release, as reported by the 4773 host distributor ID followed by the release, as reported by the
@@ -4268,17 +4775,17 @@ system and gives an overview of their function and contents.
4268 example, when running a build on Ubuntu 12.10, the value is 4775 example, when running a build on Ubuntu 12.10, the value is
4269 "Ubuntu-12.10". If this information is unable to be determined, the 4776 "Ubuntu-12.10". If this information is unable to be determined, the
4270 value resolves to "Unknown". 4777 value resolves to "Unknown".
4271 4778
4272 This variable is used by default to isolate native shared state 4779 This variable is used by default to isolate native shared state
4273 packages for different distributions (e.g. to avoid problems with 4780 packages for different distributions (e.g. to avoid problems with
4274 ``glibc`` version incompatibilities). Additionally, the variable is 4781 ``glibc`` version incompatibilities). Additionally, the variable is
4275 checked against 4782 checked against
4276 :term:`SANITY_TESTED_DISTROS` if that 4783 :term:`SANITY_TESTED_DISTROS` if that
4277 variable is set. 4784 variable is set.
4278 4785
4279 NM 4786 NM
4280 The minimal command and arguments to run ``nm``. 4787 The minimal command and arguments to run ``nm``.
4281 4788
4282 NO_GENERIC_LICENSE 4789 NO_GENERIC_LICENSE
4283 Avoids QA errors when you use a non-common, non-CLOSED license in a 4790 Avoids QA errors when you use a non-common, non-CLOSED license in a
4284 recipe. Packages exist, such as the linux-firmware package, with many 4791 recipe. Packages exist, such as the linux-firmware package, with many
@@ -4287,60 +4794,71 @@ system and gives an overview of their function and contents.
4287 which are only applicable to a specific package. 4794 which are only applicable to a specific package.
4288 ``NO_GENERIC_LICENSE`` is used to allow copying a license that does 4795 ``NO_GENERIC_LICENSE`` is used to allow copying a license that does
4289 not exist in common licenses. 4796 not exist in common licenses.
4290 4797
4291 The following example shows how to add ``NO_GENERIC_LICENSE`` to a 4798 The following example shows how to add ``NO_GENERIC_LICENSE`` to a
4292 recipe: NO_GENERIC_LICENSE[license_name] = 4799 recipe:
4293 "license_file_in_fetched_source" The following is an example that 4800 ::
4801
4802 NO_GENERIC_LICENSE[license_name] = "license_file_in_fetched_source"
4803
4804 The following is an example that
4294 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched 4805 uses the ``LICENSE.Abilis.txt`` file as the license from the fetched
4295 source: NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt" 4806 source:
4296 4807 ::
4808
4809 NO_GENERIC_LICENSE[Firmware-Abilis] = "LICENSE.Abilis.txt"
4810
4297 NO_RECOMMENDATIONS 4811 NO_RECOMMENDATIONS
4298 Prevents installation of all "recommended-only" packages. 4812 Prevents installation of all "recommended-only" packages.
4299 Recommended-only packages are packages installed only through the 4813 Recommended-only packages are packages installed only through the
4300 :term:`RRECOMMENDS` variable). Setting the 4814 :term:`RRECOMMENDS` variable). Setting the
4301 ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: 4815 ``NO_RECOMMENDATIONS`` variable to "1" turns this feature on: ::
4302 NO_RECOMMENDATIONS = "1" 4816
4303 4817 NO_RECOMMENDATIONS = "1"
4818
4304 You can set this variable globally in your ``local.conf`` file or you 4819 You can set this variable globally in your ``local.conf`` file or you
4305 can attach it to a specific image recipe by using the recipe name 4820 can attach it to a specific image recipe by using the recipe name
4306 override: NO_RECOMMENDATIONS_pn-target_image = "1" 4821 override: ::
4307 4822
4823 NO_RECOMMENDATIONS_pn-target_image = "1"
4824
4308 It is important to realize that if you choose to not install packages 4825 It is important to realize that if you choose to not install packages
4309 using this variable and some other packages are dependent on them 4826 using this variable and some other packages are dependent on them
4310 (i.e. listed in a recipe's :term:`RDEPENDS` 4827 (i.e. listed in a recipe's :term:`RDEPENDS`
4311 variable), the OpenEmbedded build system ignores your request and 4828 variable), the OpenEmbedded build system ignores your request and
4312 will install the packages to avoid dependency errors. 4829 will install the packages to avoid dependency errors.
4313 4830
4314 .. note:: 4831 .. note::
4315 4832
4316 Some recommended packages might be required for certain system 4833 Some recommended packages might be required for certain system
4317 functionality, such as kernel modules. It is up to you to add 4834 functionality, such as kernel modules. It is up to you to add
4318 packages with the 4835 packages with the IMAGE_INSTALL variable.
4319 IMAGE_INSTALL 4836
4320 variable.
4321
4322 Support for this variable exists only when using the IPK and RPM 4837 Support for this variable exists only when using the IPK and RPM
4323 packaging backend. Support does not exist for DEB. 4838 packaging backend. Support does not exist for DEB.
4324 4839
4325 See the :term:`BAD_RECOMMENDATIONS` and 4840 See the :term:`BAD_RECOMMENDATIONS` and
4326 the :term:`PACKAGE_EXCLUDE` variables for 4841 the :term:`PACKAGE_EXCLUDE` variables for
4327 related information. 4842 related information.
4328 4843
4329 NOAUTOPACKAGEDEBUG 4844 NOAUTOPACKAGEDEBUG
4330 Disables auto package from splitting ``.debug`` files. If a recipe 4845 Disables auto package from splitting ``.debug`` files. If a recipe
4331 requires ``FILES_${PN}-dbg`` to be set manually, the 4846 requires ``FILES_${PN}-dbg`` to be set manually, the
4332 ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the 4847 ``NOAUTOPACKAGEDEBUG`` can be defined allowing you to define the
4333 content of the debug package. For example: NOAUTOPACKAGEDEBUG = "1" 4848 content of the debug package. For example:
4334 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*" FILES_${PN}-dbg 4849 ::
4335 = "/usr/src/debug/" FILES_${QT_BASE_NAME}-demos-doc = 4850
4336 "${docdir}/${QT_DIR_NAME}/qch/qt.qch" 4851 NOAUTOPACKAGEDEBUG = "1"
4337 4852 FILES_${PN}-dev = "${includedir}/${QT_DIR_NAME}/Qt/*"
4853 FILES_${PN}-dbg = "/usr/src/debug/"
4854 FILES_${QT_BASE_NAME}-demos-doc = "${docdir}/${QT_DIR_NAME}/qch/qt.qch"
4855
4338 OBJCOPY 4856 OBJCOPY
4339 The minimal command and arguments to run ``objcopy``. 4857 The minimal command and arguments to run ``objcopy``.
4340 4858
4341 OBJDUMP 4859 OBJDUMP
4342 The minimal command and arguments to run ``objdump``. 4860 The minimal command and arguments to run ``objdump``.
4343 4861
4344 OE_BINCONFIG_EXTRA_MANGLE 4862 OE_BINCONFIG_EXTRA_MANGLE
4345 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class, 4863 When inheriting the :ref:`binconfig <ref-classes-binconfig>` class,
4346 this variable specifies additional arguments passed to the "sed" 4864 this variable specifies additional arguments passed to the "sed"
@@ -4349,60 +4867,66 @@ system and gives an overview of their function and contents.
4349 results in all paths in these scripts being changed to point into the 4867 results in all paths in these scripts being changed to point into the
4350 ``sysroots/`` directory so that all builds that use the script will 4868 ``sysroots/`` directory so that all builds that use the script will
4351 use the correct directories for the cross compiling layout. 4869 use the correct directories for the cross compiling layout.
4352 4870
4353 See the ``meta/classes/binconfig.bbclass`` in the 4871 See the ``meta/classes/binconfig.bbclass`` in the
4354 :term:`Source Directory` for details on how this class 4872 :term:`Source Directory` for details on how this class
4355 applies these additional sed command arguments. For general 4873 applies these additional sed command arguments. For general
4356 information on the ``binconfig`` class, see the 4874 information on the ``binconfig`` class, see the
4357 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section. 4875 ":ref:`binconfig.bbclass <ref-classes-binconfig>`" section.
4358 4876
4359 OE_IMPORTS 4877 OE_IMPORTS
4360 An internal variable used to tell the OpenEmbedded build system what 4878 An internal variable used to tell the OpenEmbedded build system what
4361 Python modules to import for every Python function run by the system. 4879 Python modules to import for every Python function run by the system.
4362 4880
4363 .. note:: 4881 .. note::
4364 4882
4365 Do not set this variable. It is for internal use only. 4883 Do not set this variable. It is for internal use only.
4366 4884
4367 OE_INIT_ENV_SCRIPT 4885 OE_INIT_ENV_SCRIPT
4368 The name of the build environment setup script for the purposes of 4886 The name of the build environment setup script for the purposes of
4369 setting up the environment within the extensible SDK. The default 4887 setting up the environment within the extensible SDK. The default
4370 value is "oe-init-build-env". 4888 value is "oe-init-build-env".
4371 4889
4372 If you use a custom script to set up your build environment, set the 4890 If you use a custom script to set up your build environment, set the
4373 ``OE_INIT_ENV_SCRIPT`` variable to its name. 4891 ``OE_INIT_ENV_SCRIPT`` variable to its name.
4374 4892
4375 OE_TERMINAL 4893 OE_TERMINAL
4376 Controls how the OpenEmbedded build system spawns interactive 4894 Controls how the OpenEmbedded build system spawns interactive
4377 terminals on the host development system (e.g. using the BitBake 4895 terminals on the host development system (e.g. using the BitBake
4378 command with the ``-c devshell`` command-line option). For more 4896 command with the ``-c devshell`` command-line option). For more
4379 information, see the "`Using a Development 4897 information, see the ":ref:`platdev-appdev-devshell`" section in
4380 Shell <&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell>`__" section in
4381 the Yocto Project Development Tasks Manual. 4898 the Yocto Project Development Tasks Manual.
4382 4899
4383 You can use the following values for the ``OE_TERMINAL`` variable: 4900 You can use the following values for the ``OE_TERMINAL`` variable:
4384 auto gnome xfce rxvt screen konsole none 4901
4385 4902 - auto
4903 - gnome
4904 - xfce
4905 - rxvt
4906 - screen
4907 - konsole
4908 - none
4909
4386 OEROOT 4910 OEROOT
4387 The directory from which the top-level build environment setup script 4911 The directory from which the top-level build environment setup script
4388 is sourced. The Yocto Project provides a top-level build environment 4912 is sourced. The Yocto Project provides a top-level build environment
4389 setup script: ````` <#structure-core-script>`__. When you run this 4913 setup script: ````` <#structure-core-script>`__. When you run this
4390 script, the ``OEROOT`` variable resolves to the directory that 4914 script, the ``OEROOT`` variable resolves to the directory that
4391 contains the script. 4915 contains the script.
4392 4916
4393 For additional information on how this variable is used, see the 4917 For additional information on how this variable is used, see the
4394 initialization script. 4918 initialization script.
4395 4919
4396 OLDEST_KERNEL 4920 OLDEST_KERNEL
4397 Declares the oldest version of the Linux kernel that the produced 4921 Declares the oldest version of the Linux kernel that the produced
4398 binaries must support. This variable is passed into the build of the 4922 binaries must support. This variable is passed into the build of the
4399 Embedded GNU C Library (``glibc``). 4923 Embedded GNU C Library (``glibc``).
4400 4924
4401 The default for this variable comes from the 4925 The default for this variable comes from the
4402 ``meta/conf/bitbake.conf`` configuration file. You can override this 4926 ``meta/conf/bitbake.conf`` configuration file. You can override this
4403 default by setting the variable in a custom distribution 4927 default by setting the variable in a custom distribution
4404 configuration file. 4928 configuration file.
4405 4929
4406 OVERRIDES 4930 OVERRIDES
4407 A colon-separated list of overrides that currently apply. Overrides 4931 A colon-separated list of overrides that currently apply. Overrides
4408 are a BitBake mechanism that allows variables to be selectively 4932 are a BitBake mechanism that allows variables to be selectively
@@ -4410,26 +4934,33 @@ system and gives an overview of their function and contents.
4410 ``OVERRIDES`` represents the "state" during building, which includes 4934 ``OVERRIDES`` represents the "state" during building, which includes
4411 the current recipe being built, the machine for which it is being 4935 the current recipe being built, the machine for which it is being
4412 built, and so forth. 4936 built, and so forth.
4413 4937
4414 As an example, if the string "an-override" appears as an element in 4938 As an example, if the string "an-override" appears as an element in
4415 the colon-separated list in ``OVERRIDES``, then the following 4939 the colon-separated list in ``OVERRIDES``, then the following
4416 assignment will override ``FOO`` with the value "overridden" at the 4940 assignment will override ``FOO`` with the value "overridden" at the
4417 end of parsing: FOO_an-override = "overridden" See the 4941 end of parsing:
4942 ::
4943
4944 FOO_an-override = "overridden"
4945
4946 See the
4418 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`" 4947 ":ref:`bitbake:bitbake-user-manual/bitbake-user-manual-metadata:conditional syntax (overrides)`"
4419 section in the BitBake User Manual for more information on the 4948 section in the BitBake User Manual for more information on the
4420 overrides mechanism. 4949 overrides mechanism.
4421 4950
4422 The default value of ``OVERRIDES`` includes the values of the 4951 The default value of ``OVERRIDES`` includes the values of the
4423 :term:`CLASSOVERRIDE`, 4952 :term:`CLASSOVERRIDE`,
4424 :term:`MACHINEOVERRIDES`, and 4953 :term:`MACHINEOVERRIDES`, and
4425 :term:`DISTROOVERRIDES` variables. Another 4954 :term:`DISTROOVERRIDES` variables. Another
4426 important override included by default is ``pn-${PN}``. This override 4955 important override included by default is ``pn-${PN}``. This override
4427 allows variables to be set for a single recipe within configuration 4956 allows variables to be set for a single recipe within configuration
4428 (``.conf``) files. Here is an example: FOO_pn-myrecipe = 4957 (``.conf``) files. Here is an example:
4429 "myrecipe-specific value" 4958 ::
4430 4959
4960 FOO_pn-myrecipe = "myrecipe-specific value"
4961
4431 .. note:: 4962 .. note::
4432 4963
4433 An easy way to see what overrides apply is to search for 4964 An easy way to see what overrides apply is to search for
4434 OVERRIDES 4965 OVERRIDES
4435 in the output of the 4966 in the output of the
@@ -4438,128 +4969,134 @@ system and gives an overview of their function and contents.
4438 Viewing Variable Values 4969 Viewing Variable Values
4439 " section in the Yocto Project Development Tasks Manual for more 4970 " section in the Yocto Project Development Tasks Manual for more
4440 information. 4971 information.
4441 4972
4442 P 4973 P
4443 The recipe name and version. ``P`` is comprised of the following: 4974 The recipe name and version. ``P`` is comprised of the following:
4444 ${PN}-${PV} 4975 ::
4445 4976
4977 ${PN}-${PV}
4978
4446 PACKAGE_ADD_METADATA 4979 PACKAGE_ADD_METADATA
4447 This variable defines additional metdata to add to packages. 4980 This variable defines additional metdata to add to packages.
4448 4981
4449 You may find you need to inject additional metadata into packages. 4982 You may find you need to inject additional metadata into packages.
4450 This variable allows you to do that by setting the injected data as 4983 This variable allows you to do that by setting the injected data as
4451 the value. Multiple fields can be added by splitting the content with 4984 the value. Multiple fields can be added by splitting the content with
4452 the literal separator "\n". 4985 the literal separator "\n".
4453 4986
4454 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable 4987 The suffixes '_IPK', '_DEB', or '_RPM' can be applied to the variable
4455 to do package type specific settings. It can also be made package 4988 to do package type specific settings. It can also be made package
4456 specific by using the package name as a suffix. 4989 specific by using the package name as a suffix.
4457 4990
4458 You can find out more about applying this variable in the "`Adding 4991 You can find out more about applying this variable in the
4459 custom metadata to 4992 ":ref:`dev-manual/dev-manual-common-tasks:adding custom metadata to packages`"
4460 packages <&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages>`__"
4461 section in the Yocto Project Development Tasks Manual. 4993 section in the Yocto Project Development Tasks Manual.
4462 4994
4463 PACKAGE_ARCH 4995 PACKAGE_ARCH
4464 The architecture of the resulting package or packages. 4996 The architecture of the resulting package or packages.
4465 4997
4466 By default, the value of this variable is set to 4998 By default, the value of this variable is set to
4467 :term:`TUNE_PKGARCH` when building for the 4999 :term:`TUNE_PKGARCH` when building for the
4468 target, :term:`BUILD_ARCH` when building for the 5000 target, :term:`BUILD_ARCH` when building for the
4469 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the 5001 build host, and "${SDK_ARCH}-${SDKPKGSUFFIX}" when building for the
4470 SDK. 5002 SDK.
4471 5003
4472 .. note:: 5004 .. note::
4473 5005
4474 See 5006 See
4475 SDK_ARCH 5007 SDK_ARCH
4476 for more information. 5008 for more information.
4477 5009
4478 However, if your recipe's output packages are built specific to the 5010 However, if your recipe's output packages are built specific to the
4479 target machine rather than generally for the architecture of the 5011 target machine rather than generally for the architecture of the
4480 machine, you should set ``PACKAGE_ARCH`` to the value of 5012 machine, you should set ``PACKAGE_ARCH`` to the value of
4481 :term:`MACHINE_ARCH` in the recipe as follows: 5013 :term:`MACHINE_ARCH` in the recipe as follows:
4482 PACKAGE_ARCH = "${MACHINE_ARCH}" 5014 ::
4483 5015
5016 PACKAGE_ARCH = "${MACHINE_ARCH}"
5017
4484 PACKAGE_ARCHS 5018 PACKAGE_ARCHS
4485 Specifies a list of architectures compatible with the target machine. 5019 Specifies a list of architectures compatible with the target machine.
4486 This variable is set automatically and should not normally be 5020 This variable is set automatically and should not normally be
4487 hand-edited. Entries are separated using spaces and listed in order 5021 hand-edited. Entries are separated using spaces and listed in order
4488 of priority. The default value for ``PACKAGE_ARCHS`` is "all any 5022 of priority. The default value for ``PACKAGE_ARCHS`` is "all any
4489 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}". 5023 noarch ${PACKAGE_EXTRA_ARCHS} ${MACHINE_ARCH}".
4490 5024
4491 PACKAGE_BEFORE_PN 5025 PACKAGE_BEFORE_PN
4492 Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so 5026 Enables easily adding packages to ``PACKAGES`` before ``${PN}`` so
4493 that those added packages can pick up files that would normally be 5027 that those added packages can pick up files that would normally be
4494 included in the default package. 5028 included in the default package.
4495 5029
4496 PACKAGE_CLASSES 5030 PACKAGE_CLASSES
4497 This variable, which is set in the ``local.conf`` configuration file 5031 This variable, which is set in the ``local.conf`` configuration file
4498 found in the ``conf`` folder of the 5032 found in the ``conf`` folder of the
4499 :term:`Build Directory`, specifies the package manager the 5033 :term:`Build Directory`, specifies the package manager the
4500 OpenEmbedded build system uses when packaging data. 5034 OpenEmbedded build system uses when packaging data.
4501 5035
4502 You can provide one or more of the following arguments for the 5036 You can provide one or more of the following arguments for the
4503 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk 5037 variable: PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk
4504 package_tar" 5038 package_tar"
4505 5039
4506 .. note:: 5040 .. note::
4507 5041
4508 While it is a legal option, the 5042 While it is a legal option, the
4509 package_tar 5043 package_tar
4510 class has limited functionality due to no support for package 5044 class has limited functionality due to no support for package
4511 dependencies by that backend. Therefore, it is recommended that 5045 dependencies by that backend. Therefore, it is recommended that
4512 you do not use it. 5046 you do not use it.
4513 5047
4514 The build system uses only the first argument in the list as the 5048 The build system uses only the first argument in the list as the
4515 package manager when creating your image or SDK. However, packages 5049 package manager when creating your image or SDK. However, packages
4516 will be created using any additional packaging classes you specify. 5050 will be created using any additional packaging classes you specify.
4517 For example, if you use the following in your ``local.conf`` file: 5051 For example, if you use the following in your ``local.conf`` file:
4518 PACKAGE_CLASSES ?= "package_ipk" The OpenEmbedded build system uses 5052 ::
5053
5054 PACKAGE_CLASSES ?= "package_ipk"
5055
5056 The OpenEmbedded build system uses
4519 the IPK package manager to create your image or SDK. 5057 the IPK package manager to create your image or SDK.
4520 5058
4521 For information on packaging and build performance effects as a 5059 For information on packaging and build performance effects as a
4522 result of the package manager in use, see the 5060 result of the package manager in use, see the
4523 ":ref:`package.bbclass <ref-classes-package>`" section. 5061 ":ref:`package.bbclass <ref-classes-package>`" section.
4524 5062
4525 PACKAGE_DEBUG_SPLIT_STYLE 5063 PACKAGE_DEBUG_SPLIT_STYLE
4526 Determines how to split up the binary and debug information when 5064 Determines how to split up the binary and debug information when
4527 creating ``*-dbg`` packages to be used with the GNU Project Debugger 5065 creating ``*-dbg`` packages to be used with the GNU Project Debugger
4528 (GDB). 5066 (GDB).
4529 5067
4530 With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control 5068 With the ``PACKAGE_DEBUG_SPLIT_STYLE`` variable, you can control
4531 where debug information, which can include or exclude source files, 5069 where debug information, which can include or exclude source files,
4532 is stored: 5070 is stored:
4533 5071
4534 - ".debug": Debug symbol files are placed next to the binary in a 5072 - ".debug": Debug symbol files are placed next to the binary in a
4535 ``.debug`` directory on the target. For example, if a binary is 5073 ``.debug`` directory on the target. For example, if a binary is
4536 installed into ``/bin``, the corresponding debug symbol files are 5074 installed into ``/bin``, the corresponding debug symbol files are
4537 installed in ``/bin/.debug``. Source files are placed in 5075 installed in ``/bin/.debug``. Source files are placed in
4538 ``/usr/src/debug``. 5076 ``/usr/src/debug``.
4539 5077
4540 - "debug-file-directory": Debug symbol files are placed under 5078 - "debug-file-directory": Debug symbol files are placed under
4541 ``/usr/lib/debug`` on the target, and separated by the path from 5079 ``/usr/lib/debug`` on the target, and separated by the path from
4542 where the binary is installed. For example, if a binary is 5080 where the binary is installed. For example, if a binary is
4543 installed in ``/bin``, the corresponding debug symbols are 5081 installed in ``/bin``, the corresponding debug symbols are
4544 installed in ``/usr/lib/debug/bin``. Source files are placed in 5082 installed in ``/usr/lib/debug/bin``. Source files are placed in
4545 ``/usr/src/debug``. 5083 ``/usr/src/debug``.
4546 5084
4547 - "debug-without-src": The same behavior as ".debug" previously 5085 - "debug-without-src": The same behavior as ".debug" previously
4548 described with the exception that no source files are installed. 5086 described with the exception that no source files are installed.
4549 5087
4550 - "debug-with-srcpkg": The same behavior as ".debug" previously 5088 - "debug-with-srcpkg": The same behavior as ".debug" previously
4551 described with the exception that all source files are placed in a 5089 described with the exception that all source files are placed in a
4552 separate ``*-src`` pkg. This is the default behavior. 5090 separate ``*-src`` pkg. This is the default behavior.
4553 5091
4554 You can find out more about debugging using GDB by reading the 5092 You can find out more about debugging using GDB by reading the
4555 "`Debugging With the GNU Project Debugger (GDB) 5093 ":ref:`platdev-gdb-remotedebug`" section
4556 Remotely <&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug>`__" section
4557 in the Yocto Project Development Tasks Manual. 5094 in the Yocto Project Development Tasks Manual.
4558 5095
4559 PACKAGE_EXCLUDE_COMPLEMENTARY 5096 PACKAGE_EXCLUDE_COMPLEMENTARY
4560 Prevents specific packages from being installed when you are 5097 Prevents specific packages from being installed when you are
4561 installing complementary packages. 5098 installing complementary packages.
4562 5099
4563 You might find that you want to prevent installing certain packages 5100 You might find that you want to prevent installing certain packages
4564 when you are installing complementary packages. For example, if you 5101 when you are installing complementary packages. For example, if you
4565 are using :term:`IMAGE_FEATURES` to install 5102 are using :term:`IMAGE_FEATURES` to install
@@ -4567,16 +5104,21 @@ system and gives an overview of their function and contents.
4567 particular multilib. If you find yourself in this situation, you can 5104 particular multilib. If you find yourself in this situation, you can
4568 use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular 5105 use the ``PACKAGE_EXCLUDE_COMPLEMENTARY`` variable to specify regular
4569 expressions to match the packages you want to exclude. 5106 expressions to match the packages you want to exclude.
4570 5107
4571 PACKAGE_EXCLUDE 5108 PACKAGE_EXCLUDE
4572 Lists packages that should not be installed into an image. For 5109 Lists packages that should not be installed into an image. For
4573 example: PACKAGE_EXCLUDE = "package_name package_name package_name 5110 example:
4574 ..." 5111 ::
4575 5112
5113 PACKAGE_EXCLUDE = "package_name package_name package_name ..."
5114
4576 You can set this variable globally in your ``local.conf`` file or you 5115 You can set this variable globally in your ``local.conf`` file or you
4577 can attach it to a specific image recipe by using the recipe name 5116 can attach it to a specific image recipe by using the recipe name
4578 override: PACKAGE_EXCLUDE_pn-target_image = "package_name" 5117 override:
4579 5118 ::
5119
5120 PACKAGE_EXCLUDE_pn-target_image = "package_name"
5121
4580 If you choose to not install a package using this variable and some 5122 If you choose to not install a package using this variable and some
4581 other package is dependent on it (i.e. listed in a recipe's 5123 other package is dependent on it (i.e. listed in a recipe's
4582 :term:`RDEPENDS` variable), the OpenEmbedded build 5124 :term:`RDEPENDS` variable), the OpenEmbedded build
@@ -4584,19 +5126,19 @@ system and gives an overview of their function and contents.
4584 halts the process with a fatal error, you can use the variable with 5126 halts the process with a fatal error, you can use the variable with
4585 an iterative development process to remove specific components from a 5127 an iterative development process to remove specific components from a
4586 system. 5128 system.
4587 5129
4588 Support for this variable exists only when using the IPK and RPM 5130 Support for this variable exists only when using the IPK and RPM
4589 packaging backend. Support does not exist for DEB. 5131 packaging backend. Support does not exist for DEB.
4590 5132
4591 See the :term:`NO_RECOMMENDATIONS` and the 5133 See the :term:`NO_RECOMMENDATIONS` and the
4592 :term:`BAD_RECOMMENDATIONS` variables for 5134 :term:`BAD_RECOMMENDATIONS` variables for
4593 related information. 5135 related information.
4594 5136
4595 PACKAGE_EXTRA_ARCHS 5137 PACKAGE_EXTRA_ARCHS
4596 Specifies the list of architectures compatible with the device CPU. 5138 Specifies the list of architectures compatible with the device CPU.
4597 This variable is useful when you build for several different devices 5139 This variable is useful when you build for several different devices
4598 that use miscellaneous processors such as XScale and ARM926-EJS. 5140 that use miscellaneous processors such as XScale and ARM926-EJS.
4599 5141
4600 PACKAGE_FEED_ARCHS 5142 PACKAGE_FEED_ARCHS
4601 Optionally specifies the package architectures used as part of the 5143 Optionally specifies the package architectures used as part of the
4602 package feed URIs during the build. When used, the 5144 package feed URIs during the build. When used, the
@@ -4605,9 +5147,9 @@ system and gives an overview of their function and contents.
4605 :term:`PACKAGE_FEED_URIS` and 5147 :term:`PACKAGE_FEED_URIS` and
4606 :term:`PACKAGE_FEED_BASE_PATHS` 5148 :term:`PACKAGE_FEED_BASE_PATHS`
4607 variables. 5149 variables.
4608 5150
4609 .. note:: 5151 .. note::
4610 5152
4611 You can use the 5153 You can use the
4612 PACKAGE_FEEDS_ARCHS 5154 PACKAGE_FEEDS_ARCHS
4613 variable to whitelist specific package architectures. If you do 5155 variable to whitelist specific package architectures. If you do
@@ -4615,73 +5157,91 @@ system and gives an overview of their function and contents.
4615 case, you can omit this variable. Omitting the variable results in 5157 case, you can omit this variable. Omitting the variable results in
4616 all available architectures for the current machine being included 5158 all available architectures for the current machine being included
4617 into remote package feeds. 5159 into remote package feeds.
4618 5160
4619 Consider the following example where the ``PACKAGE_FEED_URIS``, 5161 Consider the following example where the ``PACKAGE_FEED_URIS``,
4620 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 5162 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4621 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 5163 defined in your ``local.conf`` file:
4622 "https://example.com/packagerepos/release \\ 5164 ::
4623 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 5165
4624 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 5166 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
4625 settings, the resulting package feeds are as follows: 5167 https://example.com/packagerepos/updates"
4626 https://example.com/packagerepos/release/rpm/all 5168 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
4627 https://example.com/packagerepos/release/rpm/core2-64 5169 PACKAGE_FEED_ARCHS = "all core2-64"
4628 https://example.com/packagerepos/release/rpm-dev/all 5170
4629 https://example.com/packagerepos/release/rpm-dev/core2-64 5171 Given these settings, the resulting package feeds are as follows:
4630 https://example.com/packagerepos/updates/rpm/all 5172 ::
4631 https://example.com/packagerepos/updates/rpm/core2-64 5173
4632 https://example.com/packagerepos/updates/rpm-dev/all 5174 https://example.com/packagerepos/release/rpm/all
4633 https://example.com/packagerepos/updates/rpm-dev/core2-64 5175 https://example.com/packagerepos/release/rpm/core2-64
4634 5176 https://example.com/packagerepos/release/rpm-dev/all
5177 https://example.com/packagerepos/release/rpm-dev/core2-64
5178 https://example.com/packagerepos/updates/rpm/all
5179 https://example.com/packagerepos/updates/rpm/core2-64
5180 https://example.com/packagerepos/updates/rpm-dev/all
5181 https://example.com/packagerepos/updates/rpm-dev/core2-64
5182
4635 PACKAGE_FEED_BASE_PATHS 5183 PACKAGE_FEED_BASE_PATHS
4636 Specifies the base path used when constructing package feed URIs. The 5184 Specifies the base path used when constructing package feed URIs. The
4637 ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a 5185 ``PACKAGE_FEED_BASE_PATHS`` variable makes up the middle portion of a
4638 package feed URI used by the OpenEmbedded build system. The base path 5186 package feed URI used by the OpenEmbedded build system. The base path
4639 lies between the :term:`PACKAGE_FEED_URIS` 5187 lies between the :term:`PACKAGE_FEED_URIS`
4640 and :term:`PACKAGE_FEED_ARCHS` variables. 5188 and :term:`PACKAGE_FEED_ARCHS` variables.
4641 5189
4642 Consider the following example where the ``PACKAGE_FEED_URIS``, 5190 Consider the following example where the ``PACKAGE_FEED_URIS``,
4643 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 5191 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4644 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 5192 defined in your ``local.conf`` file:
4645 "https://example.com/packagerepos/release \\ 5193 ::
4646 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 5194
4647 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 5195 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
4648 settings, the resulting package feeds are as follows: 5196 https://example.com/packagerepos/updates"
4649 https://example.com/packagerepos/release/rpm/all 5197 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
4650 https://example.com/packagerepos/release/rpm/core2-64 5198 PACKAGE_FEED_ARCHS = "all core2-64"
4651 https://example.com/packagerepos/release/rpm-dev/all 5199
4652 https://example.com/packagerepos/release/rpm-dev/core2-64 5200 Given these settings, the resulting package feeds are as follows:
4653 https://example.com/packagerepos/updates/rpm/all 5201 ::
4654 https://example.com/packagerepos/updates/rpm/core2-64 5202
4655 https://example.com/packagerepos/updates/rpm-dev/all 5203 https://example.com/packagerepos/release/rpm/all
4656 https://example.com/packagerepos/updates/rpm-dev/core2-64 5204 https://example.com/packagerepos/release/rpm/core2-64
4657 5205 https://example.com/packagerepos/release/rpm-dev/all
5206 https://example.com/packagerepos/release/rpm-dev/core2-64
5207 https://example.com/packagerepos/updates/rpm/all
5208 https://example.com/packagerepos/updates/rpm/core2-64
5209 https://example.com/packagerepos/updates/rpm-dev/all
5210 https://example.com/packagerepos/updates/rpm-dev/core2-64
5211
4658 PACKAGE_FEED_URIS 5212 PACKAGE_FEED_URIS
4659 Specifies the front portion of the package feed URI used by the 5213 Specifies the front portion of the package feed URI used by the
4660 OpenEmbedded build system. Each final package feed URI is comprised 5214 OpenEmbedded build system. Each final package feed URI is comprised
4661 of ``PACKAGE_FEED_URIS``, 5215 of ``PACKAGE_FEED_URIS``,
4662 :term:`PACKAGE_FEED_BASE_PATHS`, and 5216 :term:`PACKAGE_FEED_BASE_PATHS`, and
4663 :term:`PACKAGE_FEED_ARCHS` variables. 5217 :term:`PACKAGE_FEED_ARCHS` variables.
4664 5218
4665 Consider the following example where the ``PACKAGE_FEED_URIS``, 5219 Consider the following example where the ``PACKAGE_FEED_URIS``,
4666 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are 5220 ``PACKAGE_FEED_BASE_PATHS``, and ``PACKAGE_FEED_ARCHS`` variables are
4667 defined in your ``local.conf`` file: PACKAGE_FEED_URIS = 5221 defined in your ``local.conf`` file:
4668 "https://example.com/packagerepos/release \\ 5222 ::
4669 https://example.com/packagerepos/updates" PACKAGE_FEED_BASE_PATHS = 5223
4670 "rpm rpm-dev" PACKAGE_FEED_ARCHS = "all core2-64" Given these 5224 PACKAGE_FEED_URIS = "https://example.com/packagerepos/release \
4671 settings, the resulting package feeds are as follows: 5225 https://example.com/packagerepos/updates"
4672 https://example.com/packagerepos/release/rpm/all 5226 PACKAGE_FEED_BASE_PATHS = "rpm rpm-dev"
4673 https://example.com/packagerepos/release/rpm/core2-64 5227 PACKAGE_FEED_ARCHS = "all core2-64"
4674 https://example.com/packagerepos/release/rpm-dev/all 5228
4675 https://example.com/packagerepos/release/rpm-dev/core2-64 5229 Given these settings, the resulting package feeds are as follows:
4676 https://example.com/packagerepos/updates/rpm/all 5230 ::
4677 https://example.com/packagerepos/updates/rpm/core2-64 5231
4678 https://example.com/packagerepos/updates/rpm-dev/all 5232 https://example.com/packagerepos/release/rpm/all
4679 https://example.com/packagerepos/updates/rpm-dev/core2-64 5233 https://example.com/packagerepos/release/rpm/core2-64
4680 5234 https://example.com/packagerepos/release/rpm-dev/all
5235 https://example.com/packagerepos/release/rpm-dev/core2-64
5236 https://example.com/packagerepos/updates/rpm/all
5237 https://example.com/packagerepos/updates/rpm/core2-64
5238 https://example.com/packagerepos/updates/rpm-dev/all
5239 https://example.com/packagerepos/updates/rpm-dev/core2-64
5240
4681 PACKAGE_INSTALL 5241 PACKAGE_INSTALL
4682 The final list of packages passed to the package manager for 5242 The final list of packages passed to the package manager for
4683 installation into the image. 5243 installation into the image.
4684 5244
4685 Because the package manager controls actual installation of all 5245 Because the package manager controls actual installation of all
4686 packages, the list of packages passed using ``PACKAGE_INSTALL`` is 5246 packages, the list of packages passed using ``PACKAGE_INSTALL`` is
4687 not the final list of packages that are actually installed. This 5247 not the final list of packages that are actually installed. This
@@ -4693,21 +5253,20 @@ system and gives an overview of their function and contents.
4693 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__ 5253 ```core-image-minimal-initramfs`` <#images-core-image-minimal-initramfs>`__
4694 image. When working with an initial RAM filesystem (initramfs) image, 5254 image. When working with an initial RAM filesystem (initramfs) image,
4695 use the ``PACKAGE_INSTALL`` variable. For information on creating an 5255 use the ``PACKAGE_INSTALL`` variable. For information on creating an
4696 initramfs, see the "`Building an Initial RAM Filesystem (initramfs) 5256 initramfs, see the ":ref:`building-an-initramfs-image`" section
4697 Image <&YOCTO_DOCS_DEV_URL;#building-an-initramfs-image>`__" section
4698 in the Yocto Project Development Tasks Manual. 5257 in the Yocto Project Development Tasks Manual.
4699 5258
4700 PACKAGE_INSTALL_ATTEMPTONLY 5259 PACKAGE_INSTALL_ATTEMPTONLY
4701 Specifies a list of packages the OpenEmbedded build system attempts 5260 Specifies a list of packages the OpenEmbedded build system attempts
4702 to install when creating an image. If a listed package fails to 5261 to install when creating an image. If a listed package fails to
4703 install, the build system does not generate an error. This variable 5262 install, the build system does not generate an error. This variable
4704 is generally not user-defined. 5263 is generally not user-defined.
4705 5264
4706 PACKAGE_PREPROCESS_FUNCS 5265 PACKAGE_PREPROCESS_FUNCS
4707 Specifies a list of functions run to pre-process the 5266 Specifies a list of functions run to pre-process the
4708 :term:`PKGD` directory prior to splitting the files out 5267 :term:`PKGD` directory prior to splitting the files out
4709 to individual packages. 5268 to individual packages.
4710 5269
4711 PACKAGE_WRITE_DEPS 5270 PACKAGE_WRITE_DEPS
4712 Specifies a list of dependencies for post-installation and 5271 Specifies a list of dependencies for post-installation and
4713 pre-installation scripts on native/cross tools. If your 5272 pre-installation scripts on native/cross tools. If your
@@ -4715,93 +5274,114 @@ system and gives an overview of their function and contents.
4715 creation time rather than on the target but depends on a native tool 5274 creation time rather than on the target but depends on a native tool
4716 in order to execute, you need to list the tools in 5275 in order to execute, you need to list the tools in
4717 ``PACKAGE_WRITE_DEPS``. 5276 ``PACKAGE_WRITE_DEPS``.
4718 5277
4719 For information on running post-installation scripts, see the 5278 For information on running post-installation scripts, see the
4720 "`Post-Installation 5279 ":ref:`dev-manual/dev-manual-common-tasks:post-installation scripts`"
4721 Scripts <&YOCTO_DOCS_DEV_URL;#new-recipe-post-installation-scripts>`__"
4722 section in the Yocto Project Development Tasks Manual. 5280 section in the Yocto Project Development Tasks Manual.
4723 5281
4724 PACKAGECONFIG 5282 PACKAGECONFIG
4725 This variable provides a means of enabling or disabling features of a 5283 This variable provides a means of enabling or disabling features of a
4726 recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in 5284 recipe on a per-recipe basis. ``PACKAGECONFIG`` blocks are defined in
4727 recipes when you specify features and then arguments that define 5285 recipes when you specify features and then arguments that define
4728 feature behaviors. Here is the basic block structure (broken over 5286 feature behaviors. Here is the basic block structure (broken over
4729 multiple lines for readability): PACKAGECONFIG ??= "f1 f2 f3 ..." 5287 multiple lines for readability):
4730 PACKAGECONFIG[f1] = "\\ --with-f1, \\ --without-f1, \\ 5288 ::
4731 build-deps-for-f1, \\ runtime-deps-for-f1, \\ 5289
4732 runtime-recommends-for-f1, \\ packageconfig-conflicts-for-f1 \\ " 5290 PACKAGECONFIG ??= "f1 f2 f3 ..."
4733 PACKAGECONFIG[f2] = "\\ ... and so on and so on ... 5291 PACKAGECONFIG[f1] = "\
4734 5292 --with-f1, \
5293 --without-f1, \
5294 build-deps-for-f1, \
5295 runtime-deps-for-f1, \
5296 runtime-recommends-for-f1, \
5297 packageconfig-conflicts-for-f1"
5298 PACKAGECONFIG[f2] = "\
5299 ... and so on and so on ...
5300
4735 The ``PACKAGECONFIG`` variable itself specifies a space-separated 5301 The ``PACKAGECONFIG`` variable itself specifies a space-separated
4736 list of the features to enable. Following the features, you can 5302 list of the features to enable. Following the features, you can
4737 determine the behavior of each feature by providing up to six 5303 determine the behavior of each feature by providing up to six
4738 order-dependent arguments, which are separated by commas. You can 5304 order-dependent arguments, which are separated by commas. You can
4739 omit any argument you like but must retain the separating commas. The 5305 omit any argument you like but must retain the separating commas. The
4740 order is important and specifies the following: 5306 order is important and specifies the following:
4741 5307
4742 1. Extra arguments that should be added to the configure script 5308 1. Extra arguments that should be added to the configure script
4743 argument list (:term:`EXTRA_OECONF` or 5309 argument list (:term:`EXTRA_OECONF` or
4744 :term:`PACKAGECONFIG_CONFARGS`) if 5310 :term:`PACKAGECONFIG_CONFARGS`) if
4745 the feature is enabled. 5311 the feature is enabled.
4746 5312
4747 2. Extra arguments that should be added to ``EXTRA_OECONF`` or 5313 2. Extra arguments that should be added to ``EXTRA_OECONF`` or
4748 ``PACKAGECONFIG_CONFARGS`` if the feature is disabled. 5314 ``PACKAGECONFIG_CONFARGS`` if the feature is disabled.
4749 5315
4750 3. Additional build dependencies (:term:`DEPENDS`) 5316 3. Additional build dependencies (:term:`DEPENDS`)
4751 that should be added if the feature is enabled. 5317 that should be added if the feature is enabled.
4752 5318
4753 4. Additional runtime dependencies (:term:`RDEPENDS`) 5319 4. Additional runtime dependencies (:term:`RDEPENDS`)
4754 that should be added if the feature is enabled. 5320 that should be added if the feature is enabled.
4755 5321
4756 5. Additional runtime recommendations 5322 5. Additional runtime recommendations
4757 (:term:`RRECOMMENDS`) that should be added if 5323 (:term:`RRECOMMENDS`) that should be added if
4758 the feature is enabled. 5324 the feature is enabled.
4759 5325
4760 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG`` 5326 6. Any conflicting (that is, mutually exclusive) ``PACKAGECONFIG``
4761 settings for this feature. 5327 settings for this feature.
4762 5328
4763 Consider the following ``PACKAGECONFIG`` block taken from the 5329 Consider the following ``PACKAGECONFIG`` block taken from the
4764 ``librsvg`` recipe. In this example the feature is ``gtk``, which has 5330 ``librsvg`` recipe. In this example the feature is ``gtk``, which has
4765 three arguments that determine the feature's behavior. 5331 three arguments that determine the feature's behavior.
4766 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3" The 5332 ::
5333
5334 PACKAGECONFIG[gtk] = "--with-gtk3,--without-gtk3,gtk+3"
5335
5336 The
4767 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is 5337 ``--with-gtk3`` and ``gtk+3`` arguments apply only if the feature is
4768 enabled. In this case, ``--with-gtk3`` is added to the configure 5338 enabled. In this case, ``--with-gtk3`` is added to the configure
4769 script argument list and ``gtk+3`` is added to ``DEPENDS``. On the 5339 script argument list and ``gtk+3`` is added to ``DEPENDS``. On the
4770 other hand, if the feature is disabled say through a ``.bbappend`` 5340 other hand, if the feature is disabled say through a ``.bbappend``
4771 file in another layer, then the second argument ``--without-gtk3`` is 5341 file in another layer, then the second argument ``--without-gtk3`` is
4772 added to the configure script instead. 5342 added to the configure script instead.
4773 5343
4774 The basic ``PACKAGECONFIG`` structure previously described holds true 5344 The basic ``PACKAGECONFIG`` structure previously described holds true
4775 regardless of whether you are creating a block or changing a block. 5345 regardless of whether you are creating a block or changing a block.
4776 When creating a block, use the structure inside your recipe. 5346 When creating a block, use the structure inside your recipe.
4777 5347
4778 If you want to change an existing ``PACKAGECONFIG`` block, you can do 5348 If you want to change an existing ``PACKAGECONFIG`` block, you can do
4779 so one of two ways: 5349 so one of two ways:
4780 5350
4781 - *Append file:* Create an append file named 5351 - *Append file:* Create an append file named
4782 recipename\ ``.bbappend`` in your layer and override the value of 5352 recipename\ ``.bbappend`` in your layer and override the value of
4783 ``PACKAGECONFIG``. You can either completely override the 5353 ``PACKAGECONFIG``. You can either completely override the
4784 variable: PACKAGECONFIG = "f4 f5" Or, you can just append the 5354 variable:
4785 variable: PACKAGECONFIG_append = " f4" 5355 ::
4786 5356
5357 PACKAGECONFIG = "f4 f5"
5358
5359 Or, you can just append the variable:
5360 ::
5361
5362 PACKAGECONFIG_append = " f4"
5363
4787 - *Configuration file:* This method is identical to changing the 5364 - *Configuration file:* This method is identical to changing the
4788 block through an append file except you edit your ``local.conf`` 5365 block through an append file except you edit your ``local.conf``
4789 or ``mydistro.conf`` file. As with append files previously 5366 or ``mydistro.conf`` file. As with append files previously
4790 described, you can either completely override the variable: 5367 described, you can either completely override the variable:
4791 PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the 5368 PACKAGECONFIG_pn-recipename = "f4 f5" Or, you can just amend the
4792 variable: PACKAGECONFIG_append_pn-recipename = " f4" 5369 variable:
4793 5370 ::
5371
5372 PACKAGECONFIG_append_pn-recipename = " f4"
5373
4794 PACKAGECONFIG_CONFARGS 5374 PACKAGECONFIG_CONFARGS
4795 A space-separated list of configuration options generated from the 5375 A space-separated list of configuration options generated from the
4796 :term:`PACKAGECONFIG` setting. 5376 :term:`PACKAGECONFIG` setting.
4797 5377
4798 Classes such as :ref:`autotools <ref-classes-autotools>` and 5378 Classes such as :ref:`autotools <ref-classes-autotools>` and
4799 :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to 5379 :ref:`cmake <ref-classes-cmake>` use ``PACKAGECONFIG_CONFARGS`` to
4800 pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``, 5380 pass ``PACKAGECONFIG`` options to ``configure`` and ``cmake``,
4801 respectively. If you are using ``PACKAGECONFIG`` but not a class that 5381 respectively. If you are using ``PACKAGECONFIG`` but not a class that
4802 handles the ``do_configure`` task, then you need to use 5382 handles the ``do_configure`` task, then you need to use
4803 ``PACKAGECONFIG_CONFARGS`` appropriately. 5383 ``PACKAGECONFIG_CONFARGS`` appropriately.
4804 5384
4805 PACKAGEGROUP_DISABLE_COMPLEMENTARY 5385 PACKAGEGROUP_DISABLE_COMPLEMENTARY
4806 For recipes inheriting the 5386 For recipes inheriting the
4807 :ref:`packagegroup <ref-classes-packagegroup>` class, setting 5387 :ref:`packagegroup <ref-classes-packagegroup>` class, setting
@@ -4809,25 +5389,27 @@ system and gives an overview of their function and contents.
4809 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth) 5389 normal complementary packages (i.e. ``-dev``, ``-dbg``, and so forth)
4810 should not be automatically created by the ``packagegroup`` recipe, 5390 should not be automatically created by the ``packagegroup`` recipe,
4811 which is the default behavior. 5391 which is the default behavior.
4812 5392
4813 PACKAGES 5393 PACKAGES
4814 The list of packages the recipe creates. The default value is the 5394 The list of packages the recipe creates. The default value is the
4815 following: ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale 5395 following:
4816 ${PACKAGE_BEFORE_PN} ${PN} 5396 ::
4817 5397
5398 ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
5399
4818 During packaging, the :ref:`ref-tasks-package` task 5400 During packaging, the :ref:`ref-tasks-package` task
4819 goes through ``PACKAGES`` and uses the :term:`FILES` 5401 goes through ``PACKAGES`` and uses the :term:`FILES`
4820 variable corresponding to each package to assign files to the 5402 variable corresponding to each package to assign files to the
4821 package. If a file matches the ``FILES`` variable for more than one 5403 package. If a file matches the ``FILES`` variable for more than one
4822 package in ``PACKAGES``, it will be assigned to the earliest 5404 package in ``PACKAGES``, it will be assigned to the earliest
4823 (leftmost) package. 5405 (leftmost) package.
4824 5406
4825 Packages in the variable's list that are empty (i.e. where none of 5407 Packages in the variable's list that are empty (i.e. where none of
4826 the patterns in ``FILES_``\ pkg match any files installed by the 5408 the patterns in ``FILES_``\ pkg match any files installed by the
4827 :ref:`ref-tasks-install` task) are not generated, 5409 :ref:`ref-tasks-install` task) are not generated,
4828 unless generation is forced through the 5410 unless generation is forced through the
4829 :term:`ALLOW_EMPTY` variable. 5411 :term:`ALLOW_EMPTY` variable.
4830 5412
4831 PACKAGES_DYNAMIC 5413 PACKAGES_DYNAMIC
4832 A promise that your recipe satisfies runtime dependencies for 5414 A promise that your recipe satisfies runtime dependencies for
4833 optional modules that are found in other recipes. 5415 optional modules that are found in other recipes.
@@ -4840,17 +5422,17 @@ system and gives an overview of their function and contents.
4840 to include that package in an image, you will get a dependency 5422 to include that package in an image, you will get a dependency
4841 failure from the packaging system during the 5423 failure from the packaging system during the
4842 :ref:`ref-tasks-rootfs` task. 5424 :ref:`ref-tasks-rootfs` task.
4843 5425
4844 Typically, if there is a chance that such a situation can occur and 5426 Typically, if there is a chance that such a situation can occur and
4845 the package that is not created is valid without the dependency being 5427 the package that is not created is valid without the dependency being
4846 satisfied, then you should use :term:`RRECOMMENDS` 5428 satisfied, then you should use :term:`RRECOMMENDS`
4847 (a soft runtime dependency) instead of ``RDEPENDS``. 5429 (a soft runtime dependency) instead of ``RDEPENDS``.
4848 5430
4849 For an example of how to use the ``PACKAGES_DYNAMIC`` variable when 5431 For an example of how to use the ``PACKAGES_DYNAMIC`` variable when
4850 you are splitting packages, see the "`Handling Optional Module 5432 you are splitting packages, see the
4851 Packaging <&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging>`__" 5433 ":ref:`dev-manual/dev-manual-common-tasks:handling optional module packaging`"
4852 section in the Yocto Project Development Tasks Manual. 5434 section in the Yocto Project Development Tasks Manual.
4853 5435
4854 PACKAGESPLITFUNCS 5436 PACKAGESPLITFUNCS
4855 Specifies a list of functions run to perform additional splitting of 5437 Specifies a list of functions run to perform additional splitting of
4856 files into individual packages. Recipes can either prepend to this 5438 files into individual packages. Recipes can either prepend to this
@@ -4860,16 +5442,16 @@ system and gives an overview of their function and contents.
4860 :term:`FILES`, :term:`RDEPENDS` and 5442 :term:`FILES`, :term:`RDEPENDS` and
4861 other packaging variables appropriately in order to perform the 5443 other packaging variables appropriately in order to perform the
4862 desired splitting. 5444 desired splitting.
4863 5445
4864 PARALLEL_MAKE 5446 PARALLEL_MAKE
4865 Extra options passed to the ``make`` command during the 5447 Extra options passed to the ``make`` command during the
4866 :ref:`ref-tasks-compile` task in order to specify 5448 :ref:`ref-tasks-compile` task in order to specify
4867 parallel compilation on the local build host. This variable is 5449 parallel compilation on the local build host. This variable is
4868 usually in the form "-j x", where x represents the maximum number of 5450 usually in the form "-j x", where x represents the maximum number of
4869 parallel threads ``make`` can run. 5451 parallel threads ``make`` can run.
4870 5452
4871 .. note:: 5453 .. note::
4872 5454
4873 In order for 5455 In order for
4874 PARALLEL_MAKE 5456 PARALLEL_MAKE
4875 to be effective, 5457 to be effective,
@@ -4881,12 +5463,12 @@ system and gives an overview of their function and contents.
4881 . An easy way to ensure this is to use the 5463 . An easy way to ensure this is to use the
4882 oe_runmake 5464 oe_runmake
4883 function. 5465 function.
4884 5466
4885 By default, the OpenEmbedded build system automatically sets this 5467 By default, the OpenEmbedded build system automatically sets this
4886 variable to be equal to the number of cores the build system uses. 5468 variable to be equal to the number of cores the build system uses.
4887 5469
4888 .. note:: 5470 .. note::
4889 5471
4890 If the software being built experiences dependency issues during 5472 If the software being built experiences dependency issues during
4891 the 5473 the
4892 do_compile 5474 do_compile
@@ -4896,50 +5478,49 @@ system and gives an overview of their function and contents.
4896 addressing race conditions, see the " 5478 addressing race conditions, see the "
4897 Debugging Parallel Make Races 5479 Debugging Parallel Make Races
4898 " section in the Yocto Project Development Tasks Manual. 5480 " section in the Yocto Project Development Tasks Manual.
4899 5481
4900 For single socket systems (i.e. one CPU), you should not have to 5482 For single socket systems (i.e. one CPU), you should not have to
4901 override this variable to gain optimal parallelism during builds. 5483 override this variable to gain optimal parallelism during builds.
4902 However, if you have very large systems that employ multiple physical 5484 However, if you have very large systems that employ multiple physical
4903 CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is 5485 CPUs, you might want to make sure the ``PARALLEL_MAKE`` variable is
4904 not set higher than "-j 20". 5486 not set higher than "-j 20".
4905 5487
4906 For more information on speeding up builds, see the "`Speeding Up a 5488 For more information on speeding up builds, see the
4907 Build <&YOCTO_DOCS_DEV_URL;#speeding-up-a-build>`__" section in the 5489 ":ref:`dev-manual/dev-manual-common-tasks:speeding up a build`"
4908 Yocto Project Development Tasks Manual. 5490 section in the Yocto Project Development Tasks Manual.
4909 5491
4910 PARALLEL_MAKEINST 5492 PARALLEL_MAKEINST
4911 Extra options passed to the ``make install`` command during the 5493 Extra options passed to the ``make install`` command during the
4912 :ref:`ref-tasks-install` task in order to specify 5494 :ref:`ref-tasks-install` task in order to specify
4913 parallel installation. This variable defaults to the value of 5495 parallel installation. This variable defaults to the value of
4914 :term:`PARALLEL_MAKE`. 5496 :term:`PARALLEL_MAKE`.
4915 5497
4916 .. note:: 5498 .. note::
4917 5499
4918 In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must 5500 In order for ``PARALLEL_MAKEINST`` to be effective, ``make`` must
4919 be called with 5501 be called with
4920 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy 5502 ``${``\ :term:`EXTRA_OEMAKE`\ ``}``. An easy
4921 way to ensure this is to use the ``oe_runmake`` function. 5503 way to ensure this is to use the ``oe_runmake`` function.
4922 5504
4923 If the software being built experiences dependency issues during 5505 If the software being built experiences dependency issues during
4924 the ``do_install`` task that result in race conditions, you can 5506 the ``do_install`` task that result in race conditions, you can
4925 clear the ``PARALLEL_MAKEINST`` variable within the recipe as a 5507 clear the ``PARALLEL_MAKEINST`` variable within the recipe as a
4926 workaround. For information on addressing race conditions, see the 5508 workaround. For information on addressing race conditions, see the
4927 "`Debugging Parallel Make 5509 ":ref:`dev-manual/dev-manual-common-tasks:debugging parallel make races`"
4928 Races <&YOCTO_DOCS_DEV_URL;#debugging-parallel-make-races>`__"
4929 section in the Yocto Project Development Tasks Manual. 5510 section in the Yocto Project Development Tasks Manual.
4930 5511
4931 PATCHRESOLVE 5512 PATCHRESOLVE
4932 Determines the action to take when a patch fails. You can set this 5513 Determines the action to take when a patch fails. You can set this
4933 variable to one of two values: "noop" and "user". 5514 variable to one of two values: "noop" and "user".
4934 5515
4935 The default value of "noop" causes the build to simply fail when the 5516 The default value of "noop" causes the build to simply fail when the
4936 OpenEmbedded build system cannot successfully apply a patch. Setting 5517 OpenEmbedded build system cannot successfully apply a patch. Setting
4937 the value to "user" causes the build system to launch a shell and 5518 the value to "user" causes the build system to launch a shell and
4938 places you in the right location so that you can manually resolve the 5519 places you in the right location so that you can manually resolve the
4939 conflicts. 5520 conflicts.
4940 5521
4941 Set this variable in your ``local.conf`` file. 5522 Set this variable in your ``local.conf`` file.
4942 5523
4943 PATCHTOOL 5524 PATCHTOOL
4944 Specifies the utility used to apply patches for a recipe during the 5525 Specifies the utility used to apply patches for a recipe during the
4945 :ref:`ref-tasks-patch` task. You can specify one of 5526 :ref:`ref-tasks-patch` task. You can specify one of
@@ -4947,24 +5528,28 @@ system and gives an overview of their function and contents.
4947 is "quilt" except for the quilt-native recipe itself. Because the 5528 is "quilt" except for the quilt-native recipe itself. Because the
4948 quilt tool is not available at the time quilt-native is being 5529 quilt tool is not available at the time quilt-native is being
4949 patched, it uses "patch". 5530 patched, it uses "patch".
4950 5531
4951 If you wish to use an alternative patching tool, set the variable in 5532 If you wish to use an alternative patching tool, set the variable in
4952 the recipe using one of the following: PATCHTOOL = "patch" PATCHTOOL 5533 the recipe using one of the following:
4953 = "quilt" PATCHTOOL = "git" 5534 ::
4954 5535
5536 PATCHTOOL = "patch"
5537 PATCHTOOL = "quilt"
5538 PATCHTOOL = "git"
5539
4955 PE 5540 PE
4956 The epoch of the recipe. By default, this variable is unset. The 5541 The epoch of the recipe. By default, this variable is unset. The
4957 variable is used to make upgrades possible when the versioning scheme 5542 variable is used to make upgrades possible when the versioning scheme
4958 changes in some backwards incompatible way. 5543 changes in some backwards incompatible way.
4959 5544
4960 ``PE`` is the default value of the :term:`PKGE` variable. 5545 ``PE`` is the default value of the :term:`PKGE` variable.
4961 5546
4962 PF 5547 PF
4963 Specifies the recipe or package name and includes all version and 5548 Specifies the recipe or package name and includes all version and
4964 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and 5549 revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
4965 ``bash-4.2-r1/``). This variable is comprised of the following: 5550 ``bash-4.2-r1/``). This variable is comprised of the following:
4966 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`} 5551 ${:term:`PN`}-${:term:`EXTENDPE`}${:term:`PV`}-${:term:`PR`}
4967 5552
4968 PIXBUF_PACKAGES 5553 PIXBUF_PACKAGES
4969 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>` 5554 When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
4970 class, this variable identifies packages that contain the pixbuf 5555 class, this variable identifies packages that contain the pixbuf
@@ -4972,139 +5557,158 @@ system and gives an overview of their function and contents.
4972 class assumes that the loaders are in the recipe's main package (i.e. 5557 class assumes that the loaders are in the recipe's main package (i.e.
4973 ``${``\ :term:`PN`\ ``}``). Use this variable if the 5558 ``${``\ :term:`PN`\ ``}``). Use this variable if the
4974 loaders you need are in a package other than that main package. 5559 loaders you need are in a package other than that main package.
4975 5560
4976 PKG 5561 PKG
4977 The name of the resulting package created by the OpenEmbedded build 5562 The name of the resulting package created by the OpenEmbedded build
4978 system. 5563 system.
4979 5564
4980 .. note:: 5565 .. note::
4981 5566
4982 When using the 5567 When using the
4983 PKG 5568 PKG
4984 variable, you must use a package name override. 5569 variable, you must use a package name override.
4985 5570
4986 For example, when the :ref:`debian <ref-classes-debian>` class 5571 For example, when the :ref:`debian <ref-classes-debian>` class
4987 renames the output package, it does so by setting 5572 renames the output package, it does so by setting
4988 ``PKG_packagename``. 5573 ``PKG_packagename``.
4989 5574
4990 PKG_CONFIG_PATH 5575 PKG_CONFIG_PATH
4991 The path to ``pkg-config`` files for the current build context. 5576 The path to ``pkg-config`` files for the current build context.
4992 ``pkg-config`` reads this variable from the environment. 5577 ``pkg-config`` reads this variable from the environment.
4993 5578
4994 PKGD 5579 PKGD
4995 Points to the destination directory for files to be packaged before 5580 Points to the destination directory for files to be packaged before
4996 they are split into individual packages. This directory defaults to 5581 they are split into individual packages. This directory defaults to
4997 the following: ${WORKDIR}/package 5582 the following:
4998 5583 ::
5584
5585 ${WORKDIR}/package
5586
4999 Do not change this default. 5587 Do not change this default.
5000 5588
5001 PKGDATA_DIR 5589 PKGDATA_DIR
5002 Points to a shared, global-state directory that holds data generated 5590 Points to a shared, global-state directory that holds data generated
5003 during the packaging process. During the packaging process, the 5591 during the packaging process. During the packaging process, the
5004 :ref:`ref-tasks-packagedata` task packages data 5592 :ref:`ref-tasks-packagedata` task packages data
5005 for each recipe and installs it into this temporary, shared area. 5593 for each recipe and installs it into this temporary, shared area.
5006 This directory defaults to the following, which you should not 5594 This directory defaults to the following, which you should not
5007 change: ${STAGING_DIR_HOST}/pkgdata For examples of how this data is 5595 change:
5008 used, see the "`Automatically Added Runtime 5596 ::
5009 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 5597
5598 ${STAGING_DIR_HOST}/pkgdata
5599
5600 For examples of how this data is used, see the
5601 ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
5010 section in the Yocto Project Overview and Concepts Manual and the 5602 section in the Yocto Project Overview and Concepts Manual and the
5011 "`Viewing Package Information with 5603 ":ref:`dev-manual/dev-manual-common-tasks:viewing package information with \`\`oe-pkgdata-util\`\``"
5012 ``oe-pkgdata-util`` <&YOCTO_DOCS_DEV_URL;#viewing-package-information-with-oe-pkgdata-util>`__"
5013 section in the Yocto Project Development Tasks Manual. For more 5604 section in the Yocto Project Development Tasks Manual. For more
5014 information on the shared, global-state directory, see 5605 information on the shared, global-state directory, see
5015 :term:`STAGING_DIR_HOST`. 5606 :term:`STAGING_DIR_HOST`.
5016 5607
5017 PKGDEST 5608 PKGDEST
5018 Points to the parent directory for files to be packaged after they 5609 Points to the parent directory for files to be packaged after they
5019 have been split into individual packages. This directory defaults to 5610 have been split into individual packages. This directory defaults to
5020 the following: ${WORKDIR}/packages-split 5611 the following:
5021 5612 ::
5613
5614 ${WORKDIR}/packages-split
5615
5022 Under this directory, the build system creates directories for each 5616 Under this directory, the build system creates directories for each
5023 package specified in :term:`PACKAGES`. Do not change 5617 package specified in :term:`PACKAGES`. Do not change
5024 this default. 5618 this default.
5025 5619
5026 PKGDESTWORK 5620 PKGDESTWORK
5027 Points to a temporary work area where the 5621 Points to a temporary work area where the
5028 :ref:`ref-tasks-package` task saves package metadata. 5622 :ref:`ref-tasks-package` task saves package metadata.
5029 The ``PKGDESTWORK`` location defaults to the following: 5623 The ``PKGDESTWORK`` location defaults to the following:
5030 ${WORKDIR}/pkgdata Do not change this default. 5624 ::
5031 5625
5626 ${WORKDIR}/pkgdata
5627
5628 Do not change this default.
5629
5032 The :ref:`ref-tasks-packagedata` task copies the 5630 The :ref:`ref-tasks-packagedata` task copies the
5033 package metadata from ``PKGDESTWORK`` to 5631 package metadata from ``PKGDESTWORK`` to
5034 :term:`PKGDATA_DIR` to make it available globally. 5632 :term:`PKGDATA_DIR` to make it available globally.
5035 5633
5036 PKGE 5634 PKGE
5037 The epoch of the package(s) built by the recipe. By default, ``PKGE`` 5635 The epoch of the package(s) built by the recipe. By default, ``PKGE``
5038 is set to :term:`PE`. 5636 is set to :term:`PE`.
5039 5637
5040 PKGR 5638 PKGR
5041 The revision of the package(s) built by the recipe. By default, 5639 The revision of the package(s) built by the recipe. By default,
5042 ``PKGR`` is set to :term:`PR`. 5640 ``PKGR`` is set to :term:`PR`.
5043 5641
5044 PKGV 5642 PKGV
5045 The version of the package(s) built by the recipe. By default, 5643 The version of the package(s) built by the recipe. By default,
5046 ``PKGV`` is set to :term:`PV`. 5644 ``PKGV`` is set to :term:`PV`.
5047 5645
5048 PN 5646 PN
5049 This variable can have two separate functions depending on the 5647 This variable can have two separate functions depending on the
5050 context: a recipe name or a resulting package name. 5648 context: a recipe name or a resulting package name.
5051 5649
5052 ``PN`` refers to a recipe name in the context of a file used by the 5650 ``PN`` refers to a recipe name in the context of a file used by the
5053 OpenEmbedded build system as input to create a package. The name is 5651 OpenEmbedded build system as input to create a package. The name is
5054 normally extracted from the recipe file name. For example, if the 5652 normally extracted from the recipe file name. For example, if the
5055 recipe is named ``expat_2.0.1.bb``, then the default value of ``PN`` 5653 recipe is named ``expat_2.0.1.bb``, then the default value of ``PN``
5056 will be "expat". 5654 will be "expat".
5057 5655
5058 The variable refers to a package name in the context of a file 5656 The variable refers to a package name in the context of a file
5059 created or produced by the OpenEmbedded build system. 5657 created or produced by the OpenEmbedded build system.
5060 5658
5061 If applicable, the ``PN`` variable also contains any special suffix 5659 If applicable, the ``PN`` variable also contains any special suffix
5062 or prefix. For example, using ``bash`` to build packages for the 5660 or prefix. For example, using ``bash`` to build packages for the
5063 native machine, ``PN`` is ``bash-native``. Using ``bash`` to build 5661 native machine, ``PN`` is ``bash-native``. Using ``bash`` to build
5064 packages for the target and for Multilib, ``PN`` would be ``bash`` 5662 packages for the target and for Multilib, ``PN`` would be ``bash``
5065 and ``lib64-bash``, respectively. 5663 and ``lib64-bash``, respectively.
5066 5664
5067 PNBLACKLIST 5665 PNBLACKLIST
5068 Lists recipes you do not want the OpenEmbedded build system to build. 5666 Lists recipes you do not want the OpenEmbedded build system to build.
5069 This variable works in conjunction with the 5667 This variable works in conjunction with the
5070 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited 5668 :ref:`blacklist <ref-classes-blacklist>` class, which is inherited
5071 globally. 5669 globally.
5072 5670
5073 To prevent a recipe from being built, use the ``PNBLACKLIST`` 5671 To prevent a recipe from being built, use the ``PNBLACKLIST``
5074 variable in your ``local.conf`` file. Here is an example that 5672 variable in your ``local.conf`` file. Here is an example that
5075 prevents ``myrecipe`` from being built: PNBLACKLIST[myrecipe] = "Not 5673 prevents ``myrecipe`` from being built:
5076 supported by our organization." 5674 ::
5077 5675
5676 PNBLACKLIST[myrecipe] = "Not supported by our organization."
5677
5078 POPULATE_SDK_POST_HOST_COMMAND 5678 POPULATE_SDK_POST_HOST_COMMAND
5079 Specifies a list of functions to call once the OpenEmbedded build 5679 Specifies a list of functions to call once the OpenEmbedded build
5080 system has created the host part of the SDK. You can specify 5680 system has created the host part of the SDK. You can specify
5081 functions separated by semicolons: POPULATE_SDK_POST_HOST_COMMAND += 5681 functions separated by semicolons:
5082 "function; ... " 5682 ::
5083 5683
5684 POPULATE_SDK_POST_HOST_COMMAND += "function; ... "
5685
5084 If you need to pass the SDK path to a command within a function, you 5686 If you need to pass the SDK path to a command within a function, you
5085 can use ``${SDK_DIR}``, which points to the parent directory used by 5687 can use ``${SDK_DIR}``, which points to the parent directory used by
5086 the OpenEmbedded build system when creating SDK output. See the 5688 the OpenEmbedded build system when creating SDK output. See the
5087 :term:`SDK_DIR` variable for more information. 5689 :term:`SDK_DIR` variable for more information.
5088 5690
5089 POPULATE_SDK_POST_TARGET_COMMAND 5691 POPULATE_SDK_POST_TARGET_COMMAND
5090 Specifies a list of functions to call once the OpenEmbedded build 5692 Specifies a list of functions to call once the OpenEmbedded build
5091 system has created the target part of the SDK. You can specify 5693 system has created the target part of the SDK. You can specify
5092 functions separated by semicolons: POPULATE_SDK_POST_TARGET_COMMAND 5694 functions separated by semicolons:
5093 += "function; ... " 5695 ::
5094 5696
5697 POPULATE_SDK_POST_TARGET_COMMAND += "function; ... "
5698
5095 If you need to pass the SDK path to a command within a function, you 5699 If you need to pass the SDK path to a command within a function, you
5096 can use ``${SDK_DIR}``, which points to the parent directory used by 5700 can use ``${SDK_DIR}``, which points to the parent directory used by
5097 the OpenEmbedded build system when creating SDK output. See the 5701 the OpenEmbedded build system when creating SDK output. See the
5098 :term:`SDK_DIR` variable for more information. 5702 :term:`SDK_DIR` variable for more information.
5099 5703
5100 PR 5704 PR
5101 The revision of the recipe. The default value for this variable is 5705 The revision of the recipe. The default value for this variable is
5102 "r0". Subsequent revisions of the recipe conventionally have the 5706 "r0". Subsequent revisions of the recipe conventionally have the
5103 values "r1", "r2", and so forth. When :term:`PV` increases, 5707 values "r1", "r2", and so forth. When :term:`PV` increases,
5104 ``PR`` is conventionally reset to "r0". 5708 ``PR`` is conventionally reset to "r0".
5105 5709
5106 .. note:: 5710 .. note::
5107 5711
5108 The OpenEmbedded build system does not need the aid of 5712 The OpenEmbedded build system does not need the aid of
5109 PR 5713 PR
5110 to know when to rebuild a recipe. The build system uses the task 5714 to know when to rebuild a recipe. The build system uses the task
@@ -5114,7 +5718,7 @@ system and gives an overview of their function and contents.
5114 and 5718 and
5115 shared state cache 5719 shared state cache
5116 mechanisms. 5720 mechanisms.
5117 5721
5118 The ``PR`` variable primarily becomes significant when a package 5722 The ``PR`` variable primarily becomes significant when a package
5119 manager dynamically installs packages on an already built image. In 5723 manager dynamically installs packages on an already built image. In
5120 this case, ``PR``, which is the default value of 5724 this case, ``PR``, which is the default value of
@@ -5124,37 +5728,45 @@ system and gives an overview of their function and contents.
5124 the same ``PV`` usually means that the packages all install the same 5728 the same ``PV`` usually means that the packages all install the same
5125 upstream version, but with later (``PR``) version packages including 5729 upstream version, but with later (``PR``) version packages including
5126 packaging fixes. 5730 packaging fixes.
5127 5731
5128 .. note:: 5732 .. note::
5129 5733
5130 PR 5734 PR
5131 does not need to be increased for changes that do not change the 5735 does not need to be increased for changes that do not change the
5132 package contents or metadata. 5736 package contents or metadata.
5133 5737
5134 Because manually managing ``PR`` can be cumbersome and error-prone, 5738 Because manually managing ``PR`` can be cumbersome and error-prone,
5135 an automated solution exists. See the "`Working With a PR 5739 an automated solution exists. See the
5136 Service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__" section 5740 ":ref:`dev-manual/dev-manual-common-tasks:working with a pr service`" section
5137 in the Yocto Project Development Tasks Manual for more information. 5741 in the Yocto Project Development Tasks Manual for more information.
5138 5742
5139 PREFERRED_PROVIDER 5743 PREFERRED_PROVIDER
5140 If multiple recipes provide the same item, this variable determines 5744 If multiple recipes provide the same item, this variable determines
5141 which recipe is preferred and thus provides the item (i.e. the 5745 which recipe is preferred and thus provides the item (i.e. the
5142 preferred provider). You should always suffix this variable with the 5746 preferred provider). You should always suffix this variable with the
5143 name of the provided item. And, you should define the variable using 5747 name of the provided item. And, you should define the variable using
5144 the preferred recipe's name (:term:`PN`). Here is a common 5748 the preferred recipe's name (:term:`PN`). Here is a common
5145 example: PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" In the 5749 example:
5146 previous example, multiple recipes are providing "virtual/kernel". 5750 ::
5751
5752 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
5753
5754 In the previous example, multiple recipes are providing "virtual/kernel".
5147 The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of 5755 The ``PREFERRED_PROVIDER`` variable is set with the name (``PN``) of
5148 the recipe you prefer to provide "virtual/kernel". 5756 the recipe you prefer to provide "virtual/kernel".
5149 5757
5150 Following are more examples: PREFERRED_PROVIDER_virtual/xserver = 5758 Following are more examples:
5151 "xserver-xf86" PREFERRED_PROVIDER_virtual/libgl ?= "mesa" For more 5759 ::
5152 information, see the "`Using Virtual 5760
5153 Providers <&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers>`__" 5761 PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
5762 PREFERRED_PROVIDER_virtual/libgl ?= "mesa"
5763
5764 For more
5765 information, see the ":ref:`metadata-virtual-providers`"
5154 section in the Yocto Project Development Tasks Manual. 5766 section in the Yocto Project Development Tasks Manual.
5155 5767
5156 .. note:: 5768 .. note::
5157 5769
5158 If you use a 5770 If you use a
5159 virtual/\* 5771 virtual/\*
5160 item with 5772 item with
@@ -5166,56 +5778,69 @@ system and gives an overview of their function and contents.
5166 is prevented from building, which is usually desirable since this 5778 is prevented from building, which is usually desirable since this
5167 mechanism is designed to select between mutually exclusive 5779 mechanism is designed to select between mutually exclusive
5168 alternative providers. 5780 alternative providers.
5169 5781
5170 PREFERRED_VERSION 5782 PREFERRED_VERSION
5171 If multiple versions of recipes exist, this variable determines which 5783 If multiple versions of recipes exist, this variable determines which
5172 version is given preference. You must always suffix the variable with 5784 version is given preference. You must always suffix the variable with
5173 the :term:`PN` you want to select, and you should set the 5785 the :term:`PN` you want to select, and you should set the
5174 :term:`PV` accordingly for precedence. 5786 :term:`PV` accordingly for precedence.
5175 5787
5176 The ``PREFERRED_VERSION`` variable supports limited wildcard use 5788 The ``PREFERRED_VERSION`` variable supports limited wildcard use
5177 through the "``%``" character. You can use the character to match any 5789 through the "``%``" character. You can use the character to match any
5178 number of characters, which can be useful when specifying versions 5790 number of characters, which can be useful when specifying versions
5179 that contain long revision numbers that potentially change. Here are 5791 that contain long revision numbers that potentially change. Here are
5180 two examples: PREFERRED_VERSION_python = "3.4.0" 5792 two examples:
5181 PREFERRED_VERSION_linux-yocto = "5.0%" 5793 ::
5182 5794
5795 PREFERRED_VERSION_python = "3.4.0"
5796 PREFERRED_VERSION_linux-yocto = "5.0%"
5797
5183 .. note:: 5798 .. note::
5184 5799
5185 The use of the " 5800 The use of the "%" character is limited in that it only works at the end of the
5186 %
5187 " character is limited in that it only works at the end of the
5188 string. You cannot use the wildcard character in any other 5801 string. You cannot use the wildcard character in any other
5189 location of the string. 5802 location of the string.
5190 5803
5191 The specified version is matched against :term:`PV`, which 5804 The specified version is matched against :term:`PV`, which
5192 does not necessarily match the version part of the recipe's filename. 5805 does not necessarily match the version part of the recipe's filename.
5193 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb`` 5806 For example, consider two recipes ``foo_1.2.bb`` and ``foo_git.bb``
5194 where ``foo_git.bb`` contains the following assignment: PV = 5807 where ``foo_git.bb`` contains the following assignment:
5195 "1.1+git${SRCPV}" In this case, the correct way to select 5808 ::
5809
5810 PV = "1.1+git${SRCPV}"
5811
5812 In this case, the correct way to select
5196 ``foo_git.bb`` is by using an assignment such as the following: 5813 ``foo_git.bb`` is by using an assignment such as the following:
5197 PREFERRED_VERSION_foo = "1.1+git%" Compare that previous example 5814 ::
5815
5816 PREFERRED_VERSION_foo = "1.1+git%"
5817
5818 Compare that previous example
5198 against the following incorrect example, which does not work: 5819 against the following incorrect example, which does not work:
5199 PREFERRED_VERSION_foo = "git" 5820 ::
5200 5821
5822 PREFERRED_VERSION_foo = "git"
5823
5201 Sometimes the ``PREFERRED_VERSION`` variable can be set by 5824 Sometimes the ``PREFERRED_VERSION`` variable can be set by
5202 configuration files in a way that is hard to change. You can use 5825 configuration files in a way that is hard to change. You can use
5203 :term:`OVERRIDES` to set a machine-specific 5826 :term:`OVERRIDES` to set a machine-specific
5204 override. Here is an example: PREFERRED_VERSION_linux-yocto_qemux86 = 5827 override. Here is an example:
5205 "5.0%" Although not recommended, worst case, you can also use the 5828 ::
5829
5830 PREFERRED_VERSION_linux-yocto_qemux86 = "5.0%"
5831
5832 Although not recommended, worst case, you can also use the
5206 "forcevariable" override, which is the strongest override possible. 5833 "forcevariable" override, which is the strongest override possible.
5207 Here is an example: PREFERRED_VERSION_linux-yocto_forcevariable = 5834 Here is an example:
5208 "5.0%" 5835 ::
5209 5836
5837 PREFERRED_VERSION_linux-yocto_forcevariable = "5.0%"
5838
5210 .. note:: 5839 .. note::
5211 5840
5212 The 5841 The \_forcevariable override is not handled specially. This override
5213 \_forcevariable 5842 only works because the default value of OVERRIDES includes "forcevariable".
5214 override is not handled specially. This override only works 5843
5215 because the default value of
5216 OVERRIDES
5217 includes "forcevariable".
5218
5219 PREMIRRORS 5844 PREMIRRORS
5220 Specifies additional paths from which the OpenEmbedded build system 5845 Specifies additional paths from which the OpenEmbedded build system
5221 gets source code. When the build system searches for source code, it 5846 gets source code. When the build system searches for source code, it
@@ -5223,35 +5848,40 @@ system and gives an overview of their function and contents.
5223 build system tries locations defined by ``PREMIRRORS``, the upstream 5848 build system tries locations defined by ``PREMIRRORS``, the upstream
5224 source, and then locations specified by 5849 source, and then locations specified by
5225 :term:`MIRRORS` in that order. 5850 :term:`MIRRORS` in that order.
5226 5851
5227 Assuming your distribution (:term:`DISTRO`) is "poky", 5852 Assuming your distribution (:term:`DISTRO`) is "poky",
5228 the default value for ``PREMIRRORS`` is defined in the 5853 the default value for ``PREMIRRORS`` is defined in the
5229 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository. 5854 ``conf/distro/poky.conf`` file in the ``meta-poky`` Git repository.
5230 5855
5231 Typically, you could add a specific server for the build system to 5856 Typically, you could add a specific server for the build system to
5232 attempt before any others by adding something like the following to 5857 attempt before any others by adding something like the following to
5233 the ``local.conf`` configuration file in the 5858 the ``local.conf`` configuration file in the
5234 :term:`Build Directory`: PREMIRRORS_prepend = "\\ 5859 :term:`Build Directory`:
5235 git://.*/.\* http://www.yoctoproject.org/sources/ \\n \\ ftp://.*/.\* 5860 ::
5236 http://www.yoctoproject.org/sources/ \\n \\ http://.*/.\* 5861
5237 http://www.yoctoproject.org/sources/ \\n \\ https://.*/.\* 5862 PREMIRRORS_prepend = "\
5238 http://www.yoctoproject.org/sources/ \\n" These changes cause the 5863 git://.*/.* http://www.yoctoproject.org/sources/ \n \
5864 ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
5865 http://.*/.* http://www.yoctoproject.org/sources/ \n \
5866 https://.*/.* http://www.yoctoproject.org/sources/ \n"
5867
5868 These changes cause the
5239 build system to intercept Git, FTP, HTTP, and HTTPS requests and 5869 build system to intercept Git, FTP, HTTP, and HTTPS requests and
5240 direct them to the ``http://`` sources mirror. You can use 5870 direct them to the ``http://`` sources mirror. You can use
5241 ``file://`` URLs to point to local directories or network shares as 5871 ``file://`` URLs to point to local directories or network shares as
5242 well. 5872 well.
5243 5873
5244 PRIORITY 5874 PRIORITY
5245 Indicates the importance of a package. 5875 Indicates the importance of a package.
5246 5876
5247 ``PRIORITY`` is considered to be part of the distribution policy 5877 ``PRIORITY`` is considered to be part of the distribution policy
5248 because the importance of any given recipe depends on the purpose for 5878 because the importance of any given recipe depends on the purpose for
5249 which the distribution is being produced. Thus, ``PRIORITY`` is not 5879 which the distribution is being produced. Thus, ``PRIORITY`` is not
5250 normally set within recipes. 5880 normally set within recipes.
5251 5881
5252 You can set ``PRIORITY`` to "required", "standard", "extra", and 5882 You can set ``PRIORITY`` to "required", "standard", "extra", and
5253 "optional", which is the default. 5883 "optional", which is the default.
5254 5884
5255 PRIVATE_LIBS 5885 PRIVATE_LIBS
5256 Specifies libraries installed within a recipe that should be ignored 5886 Specifies libraries installed within a recipe that should be ignored
5257 by the OpenEmbedded build system's shared library resolver. This 5887 by the OpenEmbedded build system's shared library resolver. This
@@ -5261,16 +5891,23 @@ system and gives an overview of their function and contents.
5261 private libraries to be set as a dependency on other unrelated 5891 private libraries to be set as a dependency on other unrelated
5262 packages that should instead depend on the package providing the 5892 packages that should instead depend on the package providing the
5263 standard version of the library. 5893 standard version of the library.
5264 5894
5265 Libraries specified in this variable should be specified by their 5895 Libraries specified in this variable should be specified by their
5266 file name. For example, from the Firefox recipe in meta-browser: 5896 file name. For example, from the Firefox recipe in meta-browser:
5267 PRIVATE_LIBS = "libmozjs.so \\ libxpcom.so \\ libnspr4.so \\ 5897 ::
5268 libxul.so \\ libmozalloc.so \\ libplc4.so \\ libplds4.so" 5898
5269 5899 PRIVATE_LIBS = "libmozjs.so \
5270 For more information, see the "`Automatically Added Runtime 5900 libxpcom.so \
5271 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 5901 libnspr4.so \
5902 libxul.so \
5903 libmozalloc.so \
5904 libplc4.so \
5905 libplds4.so"
5906
5907 For more information, see the
5908 ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
5272 section in the Yocto Project Overview and Concepts Manual. 5909 section in the Yocto Project Overview and Concepts Manual.
5273 5910
5274 PROVIDES 5911 PROVIDES
5275 A list of aliases by which a particular recipe can be known. By 5912 A list of aliases by which a particular recipe can be known. By
5276 default, a recipe's own ``PN`` is implicitly already in its 5913 default, a recipe's own ``PN`` is implicitly already in its
@@ -5279,13 +5916,18 @@ system and gives an overview of their function and contents.
5279 aliases are synonyms for the recipe and can be useful for satisfying 5916 aliases are synonyms for the recipe and can be useful for satisfying
5280 dependencies of other recipes during the build as specified by 5917 dependencies of other recipes during the build as specified by
5281 ``DEPENDS``. 5918 ``DEPENDS``.
5282 5919
5283 Consider the following example ``PROVIDES`` statement from the recipe 5920 Consider the following example ``PROVIDES`` statement from the recipe
5284 file ``eudev_3.2.9.bb``: PROVIDES = "udev" The ``PROVIDES`` statement 5921 file ``eudev_3.2.9.bb``:
5922 ::
5923
5924 PROVIDES = "udev"
5925
5926 The ``PROVIDES`` statement
5285 results in the "eudev" recipe also being available as simply "udev". 5927 results in the "eudev" recipe also being available as simply "udev".
5286 5928
5287 .. note:: 5929 .. note::
5288 5930
5289 Given that a recipe's own recipe name is already implicitly in its 5931 Given that a recipe's own recipe name is already implicitly in its
5290 own 5932 own
5291 PROVIDES 5933 PROVIDES
@@ -5293,12 +5935,12 @@ system and gives an overview of their function and contents.
5293 using a simple assignment will be sufficient. In other words, 5935 using a simple assignment will be sufficient. In other words,
5294 while you could write: 5936 while you could write:
5295 :: 5937 ::
5296 5938
5297 PROVIDES += "udev" 5939 PROVIDES += "udev"
5298 5940
5299 5941
5300 in the above, the "+=" is overkill and unnecessary. 5942 in the above, the "+=" is overkill and unnecessary.
5301 5943
5302 In addition to providing recipes under alternate names, the 5944 In addition to providing recipes under alternate names, the
5303 ``PROVIDES`` mechanism is also used to implement virtual targets. A 5945 ``PROVIDES`` mechanism is also used to implement virtual targets. A
5304 virtual target is a name that corresponds to some particular 5946 virtual target is a name that corresponds to some particular
@@ -5306,48 +5948,52 @@ system and gives an overview of their function and contents.
5306 functionality in question list the virtual target in ``PROVIDES``. 5948 functionality in question list the virtual target in ``PROVIDES``.
5307 Recipes that depend on the functionality in question can include the 5949 Recipes that depend on the functionality in question can include the
5308 virtual target in ``DEPENDS`` to leave the choice of provider open. 5950 virtual target in ``DEPENDS`` to leave the choice of provider open.
5309 5951
5310 Conventionally, virtual targets have names on the form 5952 Conventionally, virtual targets have names on the form
5311 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part 5953 "virtual/function" (e.g. "virtual/kernel"). The slash is simply part
5312 of the name and has no syntactical significance. 5954 of the name and has no syntactical significance.
5313 5955
5314 The :term:`PREFERRED_PROVIDER` variable is 5956 The :term:`PREFERRED_PROVIDER` variable is
5315 used to select which particular recipe provides a virtual target. 5957 used to select which particular recipe provides a virtual target.
5316 5958
5317 .. note:: 5959 .. note::
5318 5960
5319 A corresponding mechanism for virtual runtime dependencies 5961 A corresponding mechanism for virtual runtime dependencies
5320 (packages) exists. However, the mechanism does not depend on any 5962 (packages) exists. However, the mechanism does not depend on any
5321 special functionality beyond ordinary variable assignments. For 5963 special functionality beyond ordinary variable assignments. For
5322 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of 5964 example, ``VIRTUAL-RUNTIME_dev_manager`` refers to the package of
5323 the component that manages the ``/dev`` directory. 5965 the component that manages the ``/dev`` directory.
5324 5966
5325 Setting the "preferred provider" for runtime dependencies is as 5967 Setting the "preferred provider" for runtime dependencies is as
5326 simple as using the following assignment in a configuration file: 5968 simple as using the following assignment in a configuration file:
5327
5328 :: 5969 ::
5329 5970
5330 VIRTUAL-RUNTIME_dev_manager = "udev" 5971 VIRTUAL-RUNTIME_dev_manager = "udev"
5331 5972
5332 5973
5333 PRSERV_HOST 5974 PRSERV_HOST
5334 The network based :term:`PR` service host and port. 5975 The network based :term:`PR` service host and port.
5335 5976
5336 The ``conf/local.conf.sample.extended`` configuration file in the 5977 The ``conf/local.conf.sample.extended`` configuration file in the
5337 :term:`Source Directory` shows how the 5978 :term:`Source Directory` shows how the
5338 ``PRSERV_HOST`` variable is set: PRSERV_HOST = "localhost:0" You must 5979 ``PRSERV_HOST`` variable is set:
5339 set the variable if you want to automatically start a local `PR 5980 ::
5340 service <&YOCTO_DOCS_DEV_URL;#working-with-a-pr-service>`__. You can 5981
5982 PRSERV_HOST = "localhost:0"
5983
5984 You must
5985 set the variable if you want to automatically start a local :ref:`PR
5986 service <dev-manual/dev-manual-common-tasks:working with a pr service>`. You can
5341 set ``PRSERV_HOST`` to other values to use a remote PR service. 5987 set ``PRSERV_HOST`` to other values to use a remote PR service.
5342 5988
5343 PTEST_ENABLED 5989 PTEST_ENABLED
5344 Specifies whether or not `Package 5990 Specifies whether or not :ref:`Package
5345 Test <&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest>`__ (ptest) 5991 Test <dev-manual/dev-manual-common-tasks:testing packages with ptest>` (ptest)
5346 functionality is enabled when building a recipe. You should not set 5992 functionality is enabled when building a recipe. You should not set
5347 this variable directly. Enabling and disabling building Package Tests 5993 this variable directly. Enabling and disabling building Package Tests
5348 at build time should be done by adding "ptest" to (or removing it 5994 at build time should be done by adding "ptest" to (or removing it
5349 from) :term:`DISTRO_FEATURES`. 5995 from) :term:`DISTRO_FEATURES`.
5350 5996
5351 PV 5997 PV
5352 The version of the recipe. The version is normally extracted from the 5998 The version of the recipe. The version is normally extracted from the
5353 recipe filename. For example, if the recipe is named 5999 recipe filename. For example, if the recipe is named
@@ -5355,9 +6001,9 @@ system and gives an overview of their function and contents.
5355 ``PV`` is generally not overridden within a recipe unless it is 6001 ``PV`` is generally not overridden within a recipe unless it is
5356 building an unstable (i.e. development) version from a source code 6002 building an unstable (i.e. development) version from a source code
5357 repository (e.g. Git or Subversion). 6003 repository (e.g. Git or Subversion).
5358 6004
5359 ``PV`` is the default value of the :term:`PKGV` variable. 6005 ``PV`` is the default value of the :term:`PKGV` variable.
5360 6006
5361 PYTHON_ABI 6007 PYTHON_ABI
5362 When used by recipes that inherit the 6008 When used by recipes that inherit the
5363 :ref:`distutils3 <ref-classes-distutils3>`, 6009 :ref:`distutils3 <ref-classes-distutils3>`,
@@ -5367,15 +6013,15 @@ system and gives an overview of their function and contents.
5367 Application Binary Interface (ABI) currently in use for Python. By 6013 Application Binary Interface (ABI) currently in use for Python. By
5368 default, the ABI is "m". You do not have to set this variable as the 6014 default, the ABI is "m". You do not have to set this variable as the
5369 OpenEmbedded build system sets it for you. 6015 OpenEmbedded build system sets it for you.
5370 6016
5371 The OpenEmbedded build system uses the ABI to construct directory 6017 The OpenEmbedded build system uses the ABI to construct directory
5372 names used when installing the Python headers and libraries in 6018 names used when installing the Python headers and libraries in
5373 sysroot (e.g. ``.../python3.3m/...``). 6019 sysroot (e.g. ``.../python3.3m/...``).
5374 6020
5375 Recipes that inherit the ``distutils`` class during cross-builds also 6021 Recipes that inherit the ``distutils`` class during cross-builds also
5376 use this variable to locate the headers and libraries of the 6022 use this variable to locate the headers and libraries of the
5377 appropriate Python that the extension is targeting. 6023 appropriate Python that the extension is targeting.
5378 6024
5379 PYTHON_PN 6025 PYTHON_PN
5380 When used by recipes that inherit the 6026 When used by recipes that inherit the
5381 `distutils3 <ref-classes-distutils3>`, 6027 `distutils3 <ref-classes-distutils3>`,
@@ -5385,43 +6031,62 @@ system and gives an overview of their function and contents.
5385 major Python version being built. For Python 3.x, ``PYTHON_PN`` would 6031 major Python version being built. For Python 3.x, ``PYTHON_PN`` would
5386 be "python3". You do not have to set this variable as the 6032 be "python3". You do not have to set this variable as the
5387 OpenEmbedded build system automatically sets it for you. 6033 OpenEmbedded build system automatically sets it for you.
5388 6034
5389 The variable allows recipes to use common infrastructure such as the 6035 The variable allows recipes to use common infrastructure such as the
5390 following: DEPENDS += "${PYTHON_PN}-native" In the previous example, 6036 following:
6037 ::
6038
6039 DEPENDS += "${PYTHON_PN}-native"
6040
6041 In the previous example,
5391 the version of the dependency is ``PYTHON_PN``. 6042 the version of the dependency is ``PYTHON_PN``.
5392 6043
5393 RANLIB 6044 RANLIB
5394 The minimal command and arguments to run ``ranlib``. 6045 The minimal command and arguments to run ``ranlib``.
5395 6046
5396 RCONFLICTS 6047 RCONFLICTS
5397 The list of packages that conflict with packages. Note that packages 6048 The list of packages that conflict with packages. Note that packages
5398 will not be installed if conflicting packages are not first removed. 6049 will not be installed if conflicting packages are not first removed.
5399 6050
5400 Like all package-controlling variables, you must always use them in 6051 Like all package-controlling variables, you must always use them in
5401 conjunction with a package name override. Here is an example: 6052 conjunction with a package name override. Here is an example:
5402 RCONFLICTS_${PN} = "another_conflicting_package_name" 6053 ::
5403 6054
6055 RCONFLICTS_${PN} = "another_conflicting_package_name"
6056
5404 BitBake, which the OpenEmbedded build system uses, supports 6057 BitBake, which the OpenEmbedded build system uses, supports
5405 specifying versioned dependencies. Although the syntax varies 6058 specifying versioned dependencies. Although the syntax varies
5406 depending on the packaging format, BitBake hides these differences 6059 depending on the packaging format, BitBake hides these differences
5407 from you. Here is the general syntax to specify versions with the 6060 from you. Here is the general syntax to specify versions with the
5408 ``RCONFLICTS`` variable: RCONFLICTS_${PN} = "package (operator 6061 ``RCONFLICTS`` variable:
5409 version)" For ``operator``, you can specify the following: = < > <= 6062 ::
6063
6064 RCONFLICTS_${PN} = "package (operator version)"
6065
6066 For ``operator``, you can specify the following: = < > <=
5410 >= For example, the following sets up a dependency on version 1.2 or 6067 >= For example, the following sets up a dependency on version 1.2 or
5411 greater of the package ``foo``: RCONFLICTS_${PN} = "foo (>= 1.2)" 6068 greater of the package ``foo``:
5412 6069 ::
6070
6071 RCONFLICTS_${PN} = "foo (>= 1.2)"
6072
5413 RDEPENDS 6073 RDEPENDS
5414 Lists runtime dependencies of a package. These dependencies are other 6074 Lists runtime dependencies of a package. These dependencies are other
5415 packages that must be installed in order for the package to function 6075 packages that must be installed in order for the package to function
5416 correctly. As an example, the following assignment declares that the 6076 correctly. As an example, the following assignment declares that the
5417 package ``foo`` needs the packages ``bar`` and ``baz`` to be 6077 package ``foo`` needs the packages ``bar`` and ``baz`` to be
5418 installed: RDEPENDS_foo = "bar baz" The most common types of package 6078 installed:
6079 ::
6080
6081 RDEPENDS_foo = "bar baz"
6082
6083 The most common types of package
5419 runtime dependencies are automatically detected and added. Therefore, 6084 runtime dependencies are automatically detected and added. Therefore,
5420 most recipes do not need to set ``RDEPENDS``. For more information, 6085 most recipes do not need to set ``RDEPENDS``. For more information,
5421 see the "`Automatically Added Runtime 6086 see the
5422 Dependencies <&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies>`__" 6087 ":ref:`overview-manual/overview-manual-concepts:automatically added runtime dependencies`"
5423 section in the Yocto Project Overview and Concepts Manual. 6088 section in the Yocto Project Overview and Concepts Manual.
5424 6089
5425 The practical effect of the above ``RDEPENDS`` assignment is that 6090 The practical effect of the above ``RDEPENDS`` assignment is that
5426 ``bar`` and ``baz`` will be declared as dependencies inside the 6091 ``bar`` and ``baz`` will be declared as dependencies inside the
5427 package ``foo`` when it is written out by one of the 6092 package ``foo`` when it is written out by one of the
@@ -5431,7 +6096,7 @@ system and gives an overview of their function and contents.
5431 :term:`PACKAGE_CLASSES`. When the 6096 :term:`PACKAGE_CLASSES`. When the
5432 corresponding package manager installs the package, it will know to 6097 corresponding package manager installs the package, it will know to
5433 also install the packages on which it depends. 6098 also install the packages on which it depends.
5434 6099
5435 To ensure that the packages ``bar`` and ``baz`` get built, the 6100 To ensure that the packages ``bar`` and ``baz`` get built, the
5436 previous ``RDEPENDS`` assignment also causes a task dependency to be 6101 previous ``RDEPENDS`` assignment also causes a task dependency to be
5437 added. This dependency is from the recipe's 6102 added. This dependency is from the recipe's
@@ -5439,26 +6104,31 @@ system and gives an overview of their function and contents.
5439 :ref:`ref-tasks-compile`) task to the 6104 :ref:`ref-tasks-compile`) task to the
5440 ``do_package_write_*`` task of the recipes that build ``bar`` and 6105 ``do_package_write_*`` task of the recipes that build ``bar`` and
5441 ``baz``. 6106 ``baz``.
5442 6107
5443 The names of the packages you list within ``RDEPENDS`` must be the 6108 The names of the packages you list within ``RDEPENDS`` must be the
5444 names of other packages - they cannot be recipe names. Although 6109 names of other packages - they cannot be recipe names. Although
5445 package names and recipe names usually match, the important point 6110 package names and recipe names usually match, the important point
5446 here is that you are providing package names within the ``RDEPENDS`` 6111 here is that you are providing package names within the ``RDEPENDS``
5447 variable. For an example of the default list of packages created from 6112 variable. For an example of the default list of packages created from
5448 a recipe, see the :term:`PACKAGES` variable. 6113 a recipe, see the :term:`PACKAGES` variable.
5449 6114
5450 Because the ``RDEPENDS`` variable applies to packages being built, 6115 Because the ``RDEPENDS`` variable applies to packages being built,
5451 you should always use the variable in a form with an attached package 6116 you should always use the variable in a form with an attached package
5452 name (remember that a single recipe can build multiple packages). For 6117 name (remember that a single recipe can build multiple packages). For
5453 example, suppose you are building a development package that depends 6118 example, suppose you are building a development package that depends
5454 on the ``perl`` package. In this case, you would use the following 6119 on the ``perl`` package. In this case, you would use the following
5455 ``RDEPENDS`` statement: RDEPENDS_${PN}-dev += "perl" In the example, 6120 ``RDEPENDS`` statement:
6121 ::
6122
6123 RDEPENDS_${PN}-dev += "perl"
6124
6125 In the example,
5456 the development package depends on the ``perl`` package. Thus, the 6126 the development package depends on the ``perl`` package. Thus, the
5457 ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of 6127 ``RDEPENDS`` variable has the ``${PN}-dev`` package name as part of
5458 the variable. 6128 the variable.
5459 6129
5460 .. note:: 6130 .. note::
5461 6131
5462 RDEPENDS_${PN}-dev 6132 RDEPENDS_${PN}-dev
5463 includes 6133 includes
5464 ${ 6134 ${
@@ -5472,7 +6142,7 @@ system and gives an overview of their function and contents.
5472 when modifying 6142 when modifying
5473 RDEPENDS_${PN}-dev 6143 RDEPENDS_${PN}-dev
5474 . Use the "+=" operator rather than the "=" operator. 6144 . Use the "+=" operator rather than the "=" operator.
5475 6145
5476 The package names you use with ``RDEPENDS`` must appear as they would 6146 The package names you use with ``RDEPENDS`` must appear as they would
5477 in the ``PACKAGES`` variable. The :term:`PKG` variable 6147 in the ``PACKAGES`` variable. The :term:`PKG` variable
5478 allows a different name to be used for the final package (e.g. the 6148 allows a different name to be used for the final package (e.g. the
@@ -5480,31 +6150,38 @@ system and gives an overview of their function and contents.
5480 packages), but this final package name cannot be used with 6150 packages), but this final package name cannot be used with
5481 ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be 6151 ``RDEPENDS``, which makes sense as ``RDEPENDS`` is meant to be
5482 independent of the package format used. 6152 independent of the package format used.
5483 6153
5484 BitBake, which the OpenEmbedded build system uses, supports 6154 BitBake, which the OpenEmbedded build system uses, supports
5485 specifying versioned dependencies. Although the syntax varies 6155 specifying versioned dependencies. Although the syntax varies
5486 depending on the packaging format, BitBake hides these differences 6156 depending on the packaging format, BitBake hides these differences
5487 from you. Here is the general syntax to specify versions with the 6157 from you. Here is the general syntax to specify versions with the
5488 ``RDEPENDS`` variable: RDEPENDS_${PN} = "package (operator version)" 6158 ``RDEPENDS`` variable:
6159 ::
6160
6161 RDEPENDS_${PN} = "package (operator version)"
6162
5489 For operator, you can specify the following: = < > <= >= For version, 6163 For operator, you can specify the following: = < > <= >= For version,
5490 provide the version number. 6164 provide the version number.
5491 6165
5492 .. note:: 6166 .. note::
5493 6167
5494 You can use 6168 You can use
5495 EXTENDPKGV 6169 EXTENDPKGV
5496 to provide a full package version specification. 6170 to provide a full package version specification.
5497 6171
5498 For example, the following sets up a dependency on version 1.2 or 6172 For example, the following sets up a dependency on version 1.2 or
5499 greater of the package ``foo``: RDEPENDS_${PN} = "foo (>= 1.2)" 6173 greater of the package ``foo``:
5500 6174 ::
6175
6176 RDEPENDS_${PN} = "foo (>= 1.2)"
6177
5501 For information on build-time dependencies, see the 6178 For information on build-time dependencies, see the
5502 :term:`DEPENDS` variable. You can also see the 6179 :term:`DEPENDS` variable. You can also see the
5503 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and 6180 ":ref:`Tasks <bitbake:bitbake-user-manual/bitbake-user-manual-metadata:tasks>`" and
5504 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the 6181 ":ref:`Dependencies <bitbake:bitbake-user-manual/bitbake-user-manual-execution:dependencies>`" sections in the
5505 BitBake User Manual for additional information on tasks and 6182 BitBake User Manual for additional information on tasks and
5506 dependencies. 6183 dependencies.
5507 6184
5508 REQUIRED_DISTRO_FEATURES 6185 REQUIRED_DISTRO_FEATURES
5509 When inheriting the 6186 When inheriting the
5510 :ref:`distro_features_check <ref-classes-distro_features_check>` 6187 :ref:`distro_features_check <ref-classes-distro_features_check>`
@@ -5514,115 +6191,136 @@ system and gives an overview of their function and contents.
5514 ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not 6191 ``REQUIRED_DISTRO_FEATURES`` variable lists a feature that does not
5515 appear in ``DISTRO_FEATURES`` within the current configuration, an 6192 appear in ``DISTRO_FEATURES`` within the current configuration, an
5516 error occurs and the build stops. 6193 error occurs and the build stops.
5517 6194
5518 RM_WORK_EXCLUDE 6195 RM_WORK_EXCLUDE
5519 With ``rm_work`` enabled, this variable specifies a list of recipes 6196 With ``rm_work`` enabled, this variable specifies a list of recipes
5520 whose work directories should not be removed. See the 6197 whose work directories should not be removed. See the
5521 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more 6198 ":ref:`rm_work.bbclass <ref-classes-rm-work>`" section for more
5522 details. 6199 details.
5523 6200
5524 ROOT_HOME 6201 ROOT_HOME
5525 Defines the root home directory. By default, this directory is set as 6202 Defines the root home directory. By default, this directory is set as
5526 follows in the BitBake configuration file: ROOT_HOME ??= "/home/root" 6203 follows in the BitBake configuration file:
5527 6204 ::
6205
6206 ROOT_HOME ??= "/home/root"
6207
5528 .. note:: 6208 .. note::
5529 6209
5530 This default value is likely used because some embedded solutions 6210 This default value is likely used because some embedded solutions
5531 prefer to have a read-only root filesystem and prefer to keep 6211 prefer to have a read-only root filesystem and prefer to keep
5532 writeable data in one place. 6212 writeable data in one place.
5533 6213
5534 You can override the default by setting the variable in any layer or 6214 You can override the default by setting the variable in any layer or
5535 in the ``local.conf`` file. Because the default is set using a "weak" 6215 in the ``local.conf`` file. Because the default is set using a "weak"
5536 assignment (i.e. "??="), you can use either of the following forms to 6216 assignment (i.e. "??="), you can use either of the following forms to
5537 define your override: ROOT_HOME = "/root" ROOT_HOME ?= "/root" These 6217 define your override:
6218 ::
6219
6220 ROOT_HOME = "/root"
6221 ROOT_HOME ?= "/root"
6222
6223 These
5538 override examples use ``/root``, which is probably the most commonly 6224 override examples use ``/root``, which is probably the most commonly
5539 used override. 6225 used override.
5540 6226
5541 ROOTFS 6227 ROOTFS
5542 Indicates a filesystem image to include as the root filesystem. 6228 Indicates a filesystem image to include as the root filesystem.
5543 6229
5544 The ``ROOTFS`` variable is an optional variable used with the 6230 The ``ROOTFS`` variable is an optional variable used with the
5545 :ref:`image-live <ref-classes-image-live>` class. 6231 :ref:`image-live <ref-classes-image-live>` class.
5546 6232
5547 ROOTFS_POSTINSTALL_COMMAND 6233 ROOTFS_POSTINSTALL_COMMAND
5548 Specifies a list of functions to call after the OpenEmbedded build 6234 Specifies a list of functions to call after the OpenEmbedded build
5549 system has installed packages. You can specify functions separated by 6235 system has installed packages. You can specify functions separated by
5550 semicolons: ROOTFS_POSTINSTALL_COMMAND += "function; ... " 6236 semicolons:
5551 6237 ::
6238
6239 ROOTFS_POSTINSTALL_COMMAND += "function; ... "
6240
5552 If you need to pass the root filesystem path to a command within a 6241 If you need to pass the root filesystem path to a command within a
5553 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6242 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5554 directory that becomes the root filesystem image. See the 6243 directory that becomes the root filesystem image. See the
5555 :term:`IMAGE_ROOTFS` variable for more 6244 :term:`IMAGE_ROOTFS` variable for more
5556 information. 6245 information.
5557 6246
5558 ROOTFS_POSTPROCESS_COMMAND 6247 ROOTFS_POSTPROCESS_COMMAND
5559 Specifies a list of functions to call once the OpenEmbedded build 6248 Specifies a list of functions to call once the OpenEmbedded build
5560 system has created the root filesystem. You can specify functions 6249 system has created the root filesystem. You can specify functions
5561 separated by semicolons: ROOTFS_POSTPROCESS_COMMAND += "function; ... 6250 separated by semicolons:
5562 " 6251 ::
5563 6252
6253 ROOTFS_POSTPROCESS_COMMAND += "function; ... "
6254
5564 If you need to pass the root filesystem path to a command within a 6255 If you need to pass the root filesystem path to a command within a
5565 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6256 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5566 directory that becomes the root filesystem image. See the 6257 directory that becomes the root filesystem image. See the
5567 :term:`IMAGE_ROOTFS` variable for more 6258 :term:`IMAGE_ROOTFS` variable for more
5568 information. 6259 information.
5569 6260
5570 ROOTFS_POSTUNINSTALL_COMMAND 6261 ROOTFS_POSTUNINSTALL_COMMAND
5571 Specifies a list of functions to call after the OpenEmbedded build 6262 Specifies a list of functions to call after the OpenEmbedded build
5572 system has removed unnecessary packages. When runtime package 6263 system has removed unnecessary packages. When runtime package
5573 management is disabled in the image, several packages are removed 6264 management is disabled in the image, several packages are removed
5574 including ``base-passwd``, ``shadow``, and ``update-alternatives``. 6265 including ``base-passwd``, ``shadow``, and ``update-alternatives``.
5575 You can specify functions separated by semicolons: 6266 You can specify functions separated by semicolons:
5576 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... " 6267 ::
5577 6268
6269 ROOTFS_POSTUNINSTALL_COMMAND += "function; ... "
6270
5578 If you need to pass the root filesystem path to a command within a 6271 If you need to pass the root filesystem path to a command within a
5579 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6272 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5580 directory that becomes the root filesystem image. See the 6273 directory that becomes the root filesystem image. See the
5581 :term:`IMAGE_ROOTFS` variable for more 6274 :term:`IMAGE_ROOTFS` variable for more
5582 information. 6275 information.
5583 6276
5584 ROOTFS_PREPROCESS_COMMAND 6277 ROOTFS_PREPROCESS_COMMAND
5585 Specifies a list of functions to call before the OpenEmbedded build 6278 Specifies a list of functions to call before the OpenEmbedded build
5586 system has created the root filesystem. You can specify functions 6279 system has created the root filesystem. You can specify functions
5587 separated by semicolons: ROOTFS_PREPROCESS_COMMAND += "function; ... 6280 separated by semicolons:
5588 " 6281 ::
5589 6282
6283 ROOTFS_PREPROCESS_COMMAND += "function; ... "
6284
5590 If you need to pass the root filesystem path to a command within a 6285 If you need to pass the root filesystem path to a command within a
5591 function, you can use ``${IMAGE_ROOTFS}``, which points to the 6286 function, you can use ``${IMAGE_ROOTFS}``, which points to the
5592 directory that becomes the root filesystem image. See the 6287 directory that becomes the root filesystem image. See the
5593 :term:`IMAGE_ROOTFS` variable for more 6288 :term:`IMAGE_ROOTFS` variable for more
5594 information. 6289 information.
5595 6290
5596 RPROVIDES 6291 RPROVIDES
5597 A list of package name aliases that a package also provides. These 6292 A list of package name aliases that a package also provides. These
5598 aliases are useful for satisfying runtime dependencies of other 6293 aliases are useful for satisfying runtime dependencies of other
5599 packages both during the build and on the target (as specified by 6294 packages both during the build and on the target (as specified by
5600 ``RDEPENDS``). 6295 ``RDEPENDS``).
5601 6296
5602 .. note:: 6297 .. note::
5603 6298
5604 A package's own name is implicitly already in its 6299 A package's own name is implicitly already in its
5605 RPROVIDES 6300 RPROVIDES
5606 list. 6301 list.
5607 6302
5608 As with all package-controlling variables, you must always use the 6303 As with all package-controlling variables, you must always use the
5609 variable in conjunction with a package name override. Here is an 6304 variable in conjunction with a package name override. Here is an
5610 example: RPROVIDES_${PN} = "widget-abi-2" 6305 example:
5611 6306 ::
6307
6308 RPROVIDES_${PN} = "widget-abi-2"
6309
5612 RRECOMMENDS 6310 RRECOMMENDS
5613 A list of packages that extends the usability of a package being 6311 A list of packages that extends the usability of a package being
5614 built. The package being built does not depend on this list of 6312 built. The package being built does not depend on this list of
5615 packages in order to successfully build, but rather uses them for 6313 packages in order to successfully build, but rather uses them for
5616 extended usability. To specify runtime dependencies for packages, see 6314 extended usability. To specify runtime dependencies for packages, see
5617 the ``RDEPENDS`` variable. 6315 the ``RDEPENDS`` variable.
5618 6316
5619 The package manager will automatically install the ``RRECOMMENDS`` 6317 The package manager will automatically install the ``RRECOMMENDS``
5620 list of packages when installing the built package. However, you can 6318 list of packages when installing the built package. However, you can
5621 prevent listed packages from being installed by using the 6319 prevent listed packages from being installed by using the
5622 :term:`BAD_RECOMMENDATIONS`, 6320 :term:`BAD_RECOMMENDATIONS`,
5623 :term:`NO_RECOMMENDATIONS`, and 6321 :term:`NO_RECOMMENDATIONS`, and
5624 :term:`PACKAGE_EXCLUDE` variables. 6322 :term:`PACKAGE_EXCLUDE` variables.
5625 6323
5626 Packages specified in ``RRECOMMENDS`` need not actually be produced. 6324 Packages specified in ``RRECOMMENDS`` need not actually be produced.
5627 However, a recipe must exist that provides each package, either 6325 However, a recipe must exist that provides each package, either
5628 through the :term:`PACKAGES` or 6326 through the :term:`PACKAGES` or
@@ -5630,55 +6328,93 @@ system and gives an overview of their function and contents.
5630 :term:`RPROVIDES` variable, or an error will occur 6328 :term:`RPROVIDES` variable, or an error will occur
5631 during the build. If such a recipe does exist and the package is not 6329 during the build. If such a recipe does exist and the package is not
5632 produced, the build continues without error. 6330 produced, the build continues without error.
5633 6331
5634 Because the ``RRECOMMENDS`` variable applies to packages being built, 6332 Because the ``RRECOMMENDS`` variable applies to packages being built,
5635 you should always attach an override to the variable to specify the 6333 you should always attach an override to the variable to specify the
5636 particular package whose usability is being extended. For example, 6334 particular package whose usability is being extended. For example,
5637 suppose you are building a development package that is extended to 6335 suppose you are building a development package that is extended to
5638 support wireless functionality. In this case, you would use the 6336 support wireless functionality. In this case, you would use the
5639 following: RRECOMMENDS_${PN}-dev += "wireless_package_name" In the 6337 following:
6338 ::
6339
6340 RRECOMMENDS_${PN}-dev += "wireless_package_name"
6341
6342 In the
5640 example, the package name (``${PN}-dev``) must appear as it would in 6343 example, the package name (``${PN}-dev``) must appear as it would in
5641 the ``PACKAGES`` namespace before any renaming of the output package 6344 the ``PACKAGES`` namespace before any renaming of the output package
5642 by classes such as ``debian.bbclass``. 6345 by classes such as ``debian.bbclass``.
5643 6346
5644 BitBake, which the OpenEmbedded build system uses, supports 6347 BitBake, which the OpenEmbedded build system uses, supports
5645 specifying versioned recommends. Although the syntax varies depending 6348 specifying versioned recommends. Although the syntax varies depending
5646 on the packaging format, BitBake hides these differences from you. 6349 on the packaging format, BitBake hides these differences from you.
5647 Here is the general syntax to specify versions with the 6350 Here is the general syntax to specify versions with the
5648 ``RRECOMMENDS`` variable: RRECOMMENDS_${PN} = "package (operator 6351 ``RRECOMMENDS`` variable:
5649 version)" For ``operator``, you can specify the following: = < > <= 6352 ::
5650 >= For example, the following sets up a recommend on version 1.2 or 6353
5651 greater of the package ``foo``: RRECOMMENDS_${PN} = "foo (>= 1.2)" 6354 RRECOMMENDS_${PN} = "package (operator version)"
5652 6355
6356 For ``operator``, you can specify the following:
6357
6358 - =
6359 - <
6360 - >
6361 - <=
6362 - >=
6363
6364 For example, the following sets up a recommend on version 1.2 or
6365 greater of the package ``foo``:
6366 ::
6367
6368 RRECOMMENDS_${PN} = "foo (>= 1.2)"
6369
5653 RREPLACES 6370 RREPLACES
5654 A list of packages replaced by a package. The package manager uses 6371 A list of packages replaced by a package. The package manager uses
5655 this variable to determine which package should be installed to 6372 this variable to determine which package should be installed to
5656 replace other package(s) during an upgrade. In order to also have the 6373 replace other package(s) during an upgrade. In order to also have the
5657 other package(s) removed at the same time, you must add the name of 6374 other package(s) removed at the same time, you must add the name of
5658 the other package to the ``RCONFLICTS`` variable. 6375 the other package to the ``RCONFLICTS`` variable.
5659 6376
5660 As with all package-controlling variables, you must use this variable 6377 As with all package-controlling variables, you must use this variable
5661 in conjunction with a package name override. Here is an example: 6378 in conjunction with a package name override. Here is an example:
5662 RREPLACES_${PN} = "other_package_being_replaced" 6379 ::
5663 6380
6381 RREPLACES_${PN} = "other_package_being_replaced"
6382
5664 BitBake, which the OpenEmbedded build system uses, supports 6383 BitBake, which the OpenEmbedded build system uses, supports
5665 specifying versioned replacements. Although the syntax varies 6384 specifying versioned replacements. Although the syntax varies
5666 depending on the packaging format, BitBake hides these differences 6385 depending on the packaging format, BitBake hides these differences
5667 from you. Here is the general syntax to specify versions with the 6386 from you. Here is the general syntax to specify versions with the
5668 ``RREPLACES`` variable: RREPLACES_${PN} = "package (operator 6387 ``RREPLACES`` variable:
5669 version)" For ``operator``, you can specify the following: = < > <= 6388 ::
5670 >= For example, the following sets up a replacement using version 1.2 6389
5671 or greater of the package ``foo``: RREPLACES_${PN} = "foo (>= 1.2)" 6390 RREPLACES_${PN} = "package (operator version)"
5672 6391
6392 For ``operator``, you can specify the following:
6393
6394 - =
6395 - <
6396 - >
6397 - <=
6398 - >=
6399
6400 For example, the following sets up a replacement using version 1.2
6401 or greater of the package ``foo``:
6402 ::
6403
6404 RREPLACES_${PN} = "foo (>= 1.2)"
6405
5673 RSUGGESTS 6406 RSUGGESTS
5674 A list of additional packages that you can suggest for installation 6407 A list of additional packages that you can suggest for installation
5675 by the package manager at the time a package is installed. Not all 6408 by the package manager at the time a package is installed. Not all
5676 package managers support this functionality. 6409 package managers support this functionality.
5677 6410
5678 As with all package-controlling variables, you must always use this 6411 As with all package-controlling variables, you must always use this
5679 variable in conjunction with a package name override. Here is an 6412 variable in conjunction with a package name override. Here is an
5680 example: RSUGGESTS_${PN} = "useful_package another_package" 6413 example:
5681 6414 ::
6415
6416 RSUGGESTS_${PN} = "useful_package another_package"
6417
5682 S 6418 S
5683 The location in the :term:`Build Directory` where 6419 The location in the :term:`Build Directory` where
5684 unpacked recipe source code resides. By default, this directory is 6420 unpacked recipe source code resides. By default, this directory is
@@ -5689,27 +6425,33 @@ system and gives an overview of their function and contents.
5689 fetched from an SCM such as Git or Subversion, then you must set 6425 fetched from an SCM such as Git or Subversion, then you must set
5690 ``S`` in the recipe so that the OpenEmbedded build system knows where 6426 ``S`` in the recipe so that the OpenEmbedded build system knows where
5691 to find the unpacked source. 6427 to find the unpacked source.
5692 6428
5693 As an example, assume a :term:`Source Directory` 6429 As an example, assume a :term:`Source Directory`
5694 top-level folder named ``poky`` and a default Build Directory at 6430 top-level folder named ``poky`` and a default Build Directory at
5695 ``poky/build``. In this case, the work directory the build system 6431 ``poky/build``. In this case, the work directory the build system
5696 uses to keep the unpacked recipe for ``db`` is the following: 6432 uses to keep the unpacked recipe for ``db`` is the following:
5697 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19 The 6433 ::
5698 unpacked source code resides in the ``db-5.1.19`` folder. 6434
5699 6435 poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
6436
6437 The unpacked source code resides in the ``db-5.1.19`` folder.
6438
5700 This next example assumes a Git repository. By default, Git 6439 This next example assumes a Git repository. By default, Git
5701 repositories are cloned to ``${WORKDIR}/git`` during 6440 repositories are cloned to ``${WORKDIR}/git`` during
5702 :ref:`ref-tasks-fetch`. Since this path is different 6441 :ref:`ref-tasks-fetch`. Since this path is different
5703 from the default value of ``S``, you must set it specifically so the 6442 from the default value of ``S``, you must set it specifically so the
5704 source can be located: SRC_URI = "git://path/to/repo.git" S = 6443 source can be located:
5705 "${WORKDIR}/git" 6444 ::
5706 6445
6446 SRC_URI = "git://path/to/repo.git"
6447 S = "${WORKDIR}/git"
6448
5707 SANITY_REQUIRED_UTILITIES 6449 SANITY_REQUIRED_UTILITIES
5708 Specifies a list of command-line utilities that should be checked for 6450 Specifies a list of command-line utilities that should be checked for
5709 during the initial sanity checking process when running BitBake. If 6451 during the initial sanity checking process when running BitBake. If
5710 any of the utilities are not installed on the build host, then 6452 any of the utilities are not installed on the build host, then
5711 BitBake immediately exits with an error. 6453 BitBake immediately exits with an error.
5712 6454
5713 SANITY_TESTED_DISTROS 6455 SANITY_TESTED_DISTROS
5714 A list of the host distribution identifiers that the build system has 6456 A list of the host distribution identifiers that the build system has
5715 been tested against. Identifiers consist of the host distributor ID 6457 been tested against. Identifiers consist of the host distributor ID
@@ -5720,25 +6462,31 @@ system and gives an overview of their function and contents.
5720 :term:`NATIVELSBSTRING` does not appear in the 6462 :term:`NATIVELSBSTRING` does not appear in the
5721 list, then the build system reports a warning that indicates the 6463 list, then the build system reports a warning that indicates the
5722 current host distribution has not been tested as a build host. 6464 current host distribution has not been tested as a build host.
5723 6465
5724 SDK_ARCH 6466 SDK_ARCH
5725 The target architecture for the SDK. Typically, you do not directly 6467 The target architecture for the SDK. Typically, you do not directly
5726 set this variable. Instead, use :term:`SDKMACHINE`. 6468 set this variable. Instead, use :term:`SDKMACHINE`.
5727 6469
5728 SDK_DEPLOY 6470 SDK_DEPLOY
5729 The directory set up and used by the 6471 The directory set up and used by the
5730 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which 6472 :ref:`populate_sdk_base <ref-classes-populate-sdk>` class to which
5731 the SDK is deployed. The ``populate_sdk_base`` class defines 6473 the SDK is deployed. The ``populate_sdk_base`` class defines
5732 ``SDK_DEPLOY`` as follows: SDK_DEPLOY = "${TMPDIR}/deploy/sdk" 6474 ``SDK_DEPLOY`` as follows:
5733 6475 ::
6476
6477 SDK_DEPLOY = "${TMPDIR}/deploy/sdk"
6478
5734 SDK_DIR 6479 SDK_DIR
5735 The parent directory used by the OpenEmbedded build system when 6480 The parent directory used by the OpenEmbedded build system when
5736 creating SDK output. The 6481 creating SDK output. The
5737 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines 6482 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class defines
5738 the variable as follows: SDK_DIR = "${WORKDIR}/sdk" 6483 the variable as follows:
5739 6484 ::
6485
6486 SDK_DIR = "${WORKDIR}/sdk"
6487
5740 .. note:: 6488 .. note::
5741 6489
5742 The 6490 The
5743 SDK_DIR 6491 SDK_DIR
5744 directory is a temporary directory as it is part of 6492 directory is a temporary directory as it is part of
@@ -5746,47 +6494,53 @@ system and gives an overview of their function and contents.
5746 . The final output directory is 6494 . The final output directory is
5747 SDK_DEPLOY 6495 SDK_DEPLOY
5748 . 6496 .
5749 6497
5750 SDK_EXT_TYPE 6498 SDK_EXT_TYPE
5751 Controls whether or not shared state artifacts are copied into the 6499 Controls whether or not shared state artifacts are copied into the
5752 extensible SDK. The default value of "full" copies all of the 6500 extensible SDK. The default value of "full" copies all of the
5753 required shared state artifacts into the extensible SDK. The value 6501 required shared state artifacts into the extensible SDK. The value
5754 "minimal" leaves these artifacts out of the SDK. 6502 "minimal" leaves these artifacts out of the SDK.
5755 6503
5756 .. note:: 6504 .. note::
5757 6505
5758 If you set the variable to "minimal", you need to ensure 6506 If you set the variable to "minimal", you need to ensure
5759 SSTATE_MIRRORS 6507 SSTATE_MIRRORS
5760 is set in the SDK's configuration to enable the artifacts to be 6508 is set in the SDK's configuration to enable the artifacts to be
5761 fetched as needed. 6509 fetched as needed.
5762 6510
5763 SDK_HOST_MANIFEST 6511 SDK_HOST_MANIFEST
5764 The manifest file for the host part of the SDK. This file lists all 6512 The manifest file for the host part of the SDK. This file lists all
5765 the installed packages that make up the host part of the SDK. The 6513 the installed packages that make up the host part of the SDK. The
5766 file contains package information on a line-per-package basis as 6514 file contains package information on a line-per-package basis as
5767 follows: packagename packagearch version 6515 follows:
5768 6516 ::
6517
6518 packagename packagearch version
6519
5769 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 6520 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
5770 defines the manifest file as follows: SDK_HOST_MANIFEST = 6521 defines the manifest file as follows:
5771 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest" The location is 6522 ::
5772 derived using the :term:`SDK_DEPLOY` and 6523
6524 SDK_HOST_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.host.manifest"
6525
6526 The location is derived using the :term:`SDK_DEPLOY` and
5773 :term:`TOOLCHAIN_OUTPUTNAME` variables. 6527 :term:`TOOLCHAIN_OUTPUTNAME` variables.
5774 6528
5775 SDK_INCLUDE_PKGDATA 6529 SDK_INCLUDE_PKGDATA
5776 When set to "1", specifies to include the packagedata for all recipes 6530 When set to "1", specifies to include the packagedata for all recipes
5777 in the "world" target in the extensible SDK. Including this data 6531 in the "world" target in the extensible SDK. Including this data
5778 allows the ``devtool search`` command to find these recipes in search 6532 allows the ``devtool search`` command to find these recipes in search
5779 results, as well as allows the ``devtool add`` command to map 6533 results, as well as allows the ``devtool add`` command to map
5780 dependencies more effectively. 6534 dependencies more effectively.
5781 6535
5782 .. note:: 6536 .. note::
5783 6537
5784 Enabling the 6538 Enabling the
5785 SDK_INCLUDE_PKGDATA 6539 SDK_INCLUDE_PKGDATA
5786 variable significantly increases build time because all of world 6540 variable significantly increases build time because all of world
5787 needs to be built. Enabling the variable also slightly increases 6541 needs to be built. Enabling the variable also slightly increases
5788 the size of the extensible SDK. 6542 the size of the extensible SDK.
5789 6543
5790 SDK_INCLUDE_TOOLCHAIN 6544 SDK_INCLUDE_TOOLCHAIN
5791 When set to "1", specifies to include the toolchain in the extensible 6545 When set to "1", specifies to include the toolchain in the extensible
5792 SDK. Including the toolchain is useful particularly when 6546 SDK. Including the toolchain is useful particularly when
@@ -5795,375 +6549,417 @@ system and gives an overview of their function and contents.
5795 toolchain. For example, suppose you want to use the toolchain from an 6549 toolchain. For example, suppose you want to use the toolchain from an
5796 IDE or from other tools and you do not want to perform additional 6550 IDE or from other tools and you do not want to perform additional
5797 steps to install the toolchain. 6551 steps to install the toolchain.
5798 6552
5799 The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if 6553 The ``SDK_INCLUDE_TOOLCHAIN`` variable defaults to "0" if
5800 ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if 6554 ``SDK_EXT_TYPE`` is set to "minimal", and defaults to "1" if
5801 ``SDK_EXT_TYPE`` is set to "full". 6555 ``SDK_EXT_TYPE`` is set to "full".
5802 6556
5803 SDK_INHERIT_BLACKLIST 6557 SDK_INHERIT_BLACKLIST
5804 A list of classes to remove from the :term:`INHERIT` 6558 A list of classes to remove from the :term:`INHERIT`
5805 value globally within the extensible SDK configuration. The 6559 value globally within the extensible SDK configuration. The
5806 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the 6560 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class sets the
5807 default value: SDK_INHERIT_BLACKLIST ?= "buildhistory icecc" 6561 default value:
5808 6562 ::
6563
6564 SDK_INHERIT_BLACKLIST ?= "buildhistory icecc"
6565
5809 Some classes are not generally applicable within the extensible SDK 6566 Some classes are not generally applicable within the extensible SDK
5810 context. You can use this variable to disable those classes. 6567 context. You can use this variable to disable those classes.
5811 6568
5812 For additional information on how to customize the extensible SDK's 6569 For additional information on how to customize the extensible SDK's
5813 configuration, see the "`Configuring the Extensible 6570 configuration, see the
5814 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__" 6571 ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`"
5815 section in the Yocto Project Application Development and the 6572 section in the Yocto Project Application Development and the
5816 Extensible Software Development Kit (eSDK) manual. 6573 Extensible Software Development Kit (eSDK) manual.
5817 6574
5818 SDK_LOCAL_CONF_BLACKLIST 6575 SDK_LOCAL_CONF_BLACKLIST
5819 A list of variables not allowed through from the OpenEmbedded build 6576 A list of variables not allowed through from the OpenEmbedded build
5820 system configuration into the extensible SDK configuration. Usually, 6577 system configuration into the extensible SDK configuration. Usually,
5821 these are variables that are specific to the machine on which the 6578 these are variables that are specific to the machine on which the
5822 build system is running and thus would be potentially problematic 6579 build system is running and thus would be potentially problematic
5823 within the extensible SDK. 6580 within the extensible SDK.
5824 6581
5825 By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the 6582 By default, ``SDK_LOCAL_CONF_BLACKLIST`` is set in the
5826 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and 6583 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class and
5827 excludes the following variables: 6584 excludes the following variables:
5828 :term:`CONF_VERSION` 6585
5829 :term:`BB_NUMBER_THREADS` 6586 - :term:`CONF_VERSION`
5830 :term:`bitbake:BB_NUMBER_PARSE_THREADS` 6587 - :term:`BB_NUMBER_THREADS`
5831 :term:`PARALLEL_MAKE` 6588 - :term:`bitbake:BB_NUMBER_PARSE_THREADS`
5832 :term:`PRSERV_HOST` 6589 - :term:`PARALLEL_MAKE`
5833 :term:`SSTATE_MIRRORS` :term:`DL_DIR` 6590 - :term:`PRSERV_HOST`
5834 :term:`SSTATE_DIR` :term:`TMPDIR` 6591 - :term:`SSTATE_MIRRORS` :term:`DL_DIR`
5835 :term:`BB_SERVER_TIMEOUT` 6592 - :term:`SSTATE_DIR` :term:`TMPDIR`
5836 6593 - :term:`BB_SERVER_TIMEOUT`
6594
5837 For additional information on how to customize the extensible SDK's 6595 For additional information on how to customize the extensible SDK's
5838 configuration, see the "`Configuring the Extensible 6596 configuration, see the
5839 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__" 6597 ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`"
5840 section in the Yocto Project Application Development and the 6598 section in the Yocto Project Application Development and the
5841 Extensible Software Development Kit (eSDK) manual. 6599 Extensible Software Development Kit (eSDK) manual.
5842 6600
5843 SDK_LOCAL_CONF_WHITELIST 6601 SDK_LOCAL_CONF_WHITELIST
5844 A list of variables allowed through from the OpenEmbedded build 6602 A list of variables allowed through from the OpenEmbedded build
5845 system configuration into the extensible SDK configuration. By 6603 system configuration into the extensible SDK configuration. By
5846 default, the list of variables is empty and is set in the 6604 default, the list of variables is empty and is set in the
5847 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class. 6605 :ref:`populate-sdk-ext <ref-classes-populate-sdk-*>` class.
5848 6606
5849 This list overrides the variables specified using the 6607 This list overrides the variables specified using the
5850 :term:`SDK_LOCAL_CONF_BLACKLIST` 6608 :term:`SDK_LOCAL_CONF_BLACKLIST`
5851 variable as well as any variables identified by automatic 6609 variable as well as any variables identified by automatic
5852 blacklisting due to the "/" character being found at the start of the 6610 blacklisting due to the "/" character being found at the start of the
5853 value, which is usually indicative of being a path and thus might not 6611 value, which is usually indicative of being a path and thus might not
5854 be valid on the system where the SDK is installed. 6612 be valid on the system where the SDK is installed.
5855 6613
5856 For additional information on how to customize the extensible SDK's 6614 For additional information on how to customize the extensible SDK's
5857 configuration, see the "`Configuring the Extensible 6615 configuration, see the
5858 SDK <&YOCTO_DOCS_SDK_URL;#sdk-configuring-the-extensible-sdk>`__" 6616 ":ref:`sdk-manual/sdk-appendix-customizing:configuring the extensible sdk`"
5859 section in the Yocto Project Application Development and the 6617 section in the Yocto Project Application Development and the
5860 Extensible Software Development Kit (eSDK) manual. 6618 Extensible Software Development Kit (eSDK) manual.
5861 6619
5862 SDK_NAME 6620 SDK_NAME
5863 The base name for SDK output files. The name is derived from the 6621 The base name for SDK output files. The name is derived from the
5864 :term:`DISTRO`, :term:`TCLIBC`, 6622 :term:`DISTRO`, :term:`TCLIBC`,
5865 :term:`SDK_ARCH`, 6623 :term:`SDK_ARCH`,
5866 :term:`IMAGE_BASENAME`, and 6624 :term:`IMAGE_BASENAME`, and
5867 :term:`TUNE_PKGARCH` variables: SDK_NAME = 6625 :term:`TUNE_PKGARCH` variables:
5868 "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}" 6626 ::
5869 6627
6628 SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
6629
5870 SDK_OS 6630 SDK_OS
5871 Specifies the operating system for which the SDK will be built. The 6631 Specifies the operating system for which the SDK will be built. The
5872 default value is the value of :term:`BUILD_OS`. 6632 default value is the value of :term:`BUILD_OS`.
5873 6633
5874 SDK_OUTPUT 6634 SDK_OUTPUT
5875 The location used by the OpenEmbedded build system when creating SDK 6635 The location used by the OpenEmbedded build system when creating SDK
5876 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` 6636 output. The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>`
5877 class defines the variable as follows: SDK_DIR = "${WORKDIR}/sdk" 6637 class defines the variable as follows:
5878 SDK_OUTPUT = "${SDK_DIR}/image" SDK_DEPLOY = "${DEPLOY_DIR}/sdk" 6638 ::
5879 6639
6640 SDK_DIR = "${WORKDIR}/sdk"
6641 SDK_OUTPUT = "${SDK_DIR}/image"
6642 SDK_DEPLOY = "${DEPLOY_DIR}/sdk"
6643
5880 .. note:: 6644 .. note::
5881 6645
5882 The 6646 The SDK_OUTPUT directory is a temporary directory as it is part of
5883 SDK_OUTPUT 6647 WORKDIR by way of SDK_DIR. The final output directory is
5884 directory is a temporary directory as it is part of 6648 SDK_DEPLOY.
5885 WORKDIR 6649
5886 by way of
5887 SDK_DIR
5888 . The final output directory is
5889 SDK_DEPLOY
5890 .
5891
5892 SDK_PACKAGE_ARCHS 6650 SDK_PACKAGE_ARCHS
5893 Specifies a list of architectures compatible with the SDK machine. 6651 Specifies a list of architectures compatible with the SDK machine.
5894 This variable is set automatically and should not normally be 6652 This variable is set automatically and should not normally be
5895 hand-edited. Entries are separated using spaces and listed in order 6653 hand-edited. Entries are separated using spaces and listed in order
5896 of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any 6654 of priority. The default value for ``SDK_PACKAGE_ARCHS`` is "all any
5897 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}". 6655 noarch ${SDK_ARCH}-${SDKPKGSUFFIX}".
5898 6656
5899 SDK_POSTPROCESS_COMMAND 6657 SDK_POSTPROCESS_COMMAND
5900 Specifies a list of functions to call once the OpenEmbedded build 6658 Specifies a list of functions to call once the OpenEmbedded build
5901 system creates the SDK. You can specify functions separated by 6659 system creates the SDK. You can specify functions separated by
5902 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... " 6660 semicolons: SDK_POSTPROCESS_COMMAND += "function; ... "
5903 6661
5904 If you need to pass an SDK path to a command within a function, you 6662 If you need to pass an SDK path to a command within a function, you
5905 can use ``${SDK_DIR}``, which points to the parent directory used by 6663 can use ``${SDK_DIR}``, which points to the parent directory used by
5906 the OpenEmbedded build system when creating SDK output. See the 6664 the OpenEmbedded build system when creating SDK output. See the
5907 :term:`SDK_DIR` variable for more information. 6665 :term:`SDK_DIR` variable for more information.
5908 6666
5909 SDK_PREFIX 6667 SDK_PREFIX
5910 The toolchain binary prefix used for ``nativesdk`` recipes. The 6668 The toolchain binary prefix used for ``nativesdk`` recipes. The
5911 OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the 6669 OpenEmbedded build system uses the ``SDK_PREFIX`` value to set the
5912 :term:`TARGET_PREFIX` when building 6670 :term:`TARGET_PREFIX` when building
5913 ``nativesdk`` recipes. The default value is "${SDK_SYS}-". 6671 ``nativesdk`` recipes. The default value is "${SDK_SYS}-".
5914 6672
5915 SDK_RECRDEP_TASKS 6673 SDK_RECRDEP_TASKS
5916 A list of shared state tasks added to the extensible SDK. By default, 6674 A list of shared state tasks added to the extensible SDK. By default,
5917 the following tasks are added: do_populate_lic do_package_qa 6675 the following tasks are added:
5918 do_populate_sysroot do_deploy Despite the default value of "" for the 6676
6677 - do_populate_lic
6678 - do_package_qa
6679 - do_populate_sysroot
6680 - do_deploy
6681
6682 Despite the default value of "" for the
5919 ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added 6683 ``SDK_RECRDEP_TASKS`` variable, the above four tasks are always added
5920 to the SDK. To specify tasks beyond these four, you need to use the 6684 to the SDK. To specify tasks beyond these four, you need to use the
5921 ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional 6685 ``SDK_RECRDEP_TASKS`` variable (e.g. you are defining additional
5922 tasks that are needed in order to build 6686 tasks that are needed in order to build
5923 :term:`SDK_TARGETS`). 6687 :term:`SDK_TARGETS`).
5924 6688
5925 SDK_SYS 6689 SDK_SYS
5926 Specifies the system, including the architecture and the operating 6690 Specifies the system, including the architecture and the operating
5927 system, for which the SDK will be built. 6691 system, for which the SDK will be built.
5928 6692
5929 The OpenEmbedded build system automatically sets this variable based 6693 The OpenEmbedded build system automatically sets this variable based
5930 on :term:`SDK_ARCH`, 6694 on :term:`SDK_ARCH`,
5931 :term:`SDK_VENDOR`, and 6695 :term:`SDK_VENDOR`, and
5932 :term:`SDK_OS`. You do not need to set the ``SDK_SYS`` 6696 :term:`SDK_OS`. You do not need to set the ``SDK_SYS``
5933 variable yourself. 6697 variable yourself.
5934 6698
5935 SDK_TARGET_MANIFEST 6699 SDK_TARGET_MANIFEST
5936 The manifest file for the target part of the SDK. This file lists all 6700 The manifest file for the target part of the SDK. This file lists all
5937 the installed packages that make up the target part of the SDK. The 6701 the installed packages that make up the target part of the SDK. The
5938 file contains package information on a line-per-package basis as 6702 file contains package information on a line-per-package basis as
5939 follows: packagename packagearch version 6703 follows:
5940 6704 ::
6705
6706 packagename packagearch version
6707
5941 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class 6708 The :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class
5942 defines the manifest file as follows: SDK_TARGET_MANIFEST = 6709 defines the manifest file as follows:
5943 "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest" The location 6710 ::
5944 is derived using the :term:`SDK_DEPLOY` and 6711
6712 SDK_TARGET_MANIFEST = "${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.target.manifest"
6713
6714 The location is derived using the :term:`SDK_DEPLOY` and
5945 :term:`TOOLCHAIN_OUTPUTNAME` variables. 6715 :term:`TOOLCHAIN_OUTPUTNAME` variables.
5946 6716
5947 SDK_TARGETS 6717 SDK_TARGETS
5948 A list of targets to install from shared state as part of the 6718 A list of targets to install from shared state as part of the
5949 standard or extensible SDK installation. The default value is "${PN}" 6719 standard or extensible SDK installation. The default value is "${PN}"
5950 (i.e. the image from which the SDK is built). 6720 (i.e. the image from which the SDK is built).
5951 6721
5952 The ``SDK_TARGETS`` variable is an internal variable and typically 6722 The ``SDK_TARGETS`` variable is an internal variable and typically
5953 would not be changed. 6723 would not be changed.
5954 6724
5955 SDK_TITLE 6725 SDK_TITLE
5956 The title to be printed when running the SDK installer. By default, 6726 The title to be printed when running the SDK installer. By default,
5957 this title is based on the :term:`DISTRO_NAME` or 6727 this title is based on the :term:`DISTRO_NAME` or
5958 :term:`DISTRO` variable and is set in the 6728 :term:`DISTRO` variable and is set in the
5959 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 6729 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
5960 follows: SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or 6730 follows:
5961 d.getVar('DISTRO')} SDK" For the default distribution "poky", 6731 ::
6732
6733 SDK_TITLE ??= "${@d.getVar('DISTRO_NAME') or d.getVar('DISTRO')} SDK"
6734
6735 For the default distribution "poky",
5962 ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)". 6736 ``SDK_TITLE`` is set to "Poky (Yocto Project Reference Distro)".
5963 6737
5964 For information on how to change this default title, see the 6738 For information on how to change this default title, see the
5965 "`Changing the Extensible SDK Installer 6739 ":ref:`sdk-manual/sdk-appendix-customizing:changing the extensible sdk installer title`"
5966 Title <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-sdk-installer-title>`__"
5967 section in the Yocto Project Application Development and the 6740 section in the Yocto Project Application Development and the
5968 Extensible Software Development Kit (eSDK) manual. 6741 Extensible Software Development Kit (eSDK) manual.
5969 6742
5970 SDK_UPDATE_URL 6743 SDK_UPDATE_URL
5971 An optional URL for an update server for the extensible SDK. If set, 6744 An optional URL for an update server for the extensible SDK. If set,
5972 the value is used as the default update server when running 6745 the value is used as the default update server when running
5973 ``devtool sdk-update`` within the extensible SDK. 6746 ``devtool sdk-update`` within the extensible SDK.
5974 6747
5975 SDK_VENDOR 6748 SDK_VENDOR
5976 Specifies the name of the SDK vendor. 6749 Specifies the name of the SDK vendor.
5977 6750
5978 SDK_VERSION 6751 SDK_VERSION
5979 Specifies the version of the SDK. The distribution configuration file 6752 Specifies the version of the SDK. The distribution configuration file
5980 (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the 6753 (e.g. ``/meta-poky/conf/distro/poky.conf``) defines the
5981 ``SDK_VERSION`` as follows: SDK_VERSION = 6754 ``SDK_VERSION`` as follows:
5982 "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}" 6755 ::
5983 6756
6757 SDK_VERSION = "${@d.getVar('DISTRO_VERSION').replace('snapshot-${DATE}','snapshot')}"
6758
5984 For additional information, see the 6759 For additional information, see the
5985 :term:`DISTRO_VERSION` and 6760 :term:`DISTRO_VERSION` and
5986 :term:`DATE` variables. 6761 :term:`DATE` variables.
5987 6762
5988 SDKEXTPATH 6763 SDKEXTPATH
5989 The default installation directory for the Extensible SDK. By 6764 The default installation directory for the Extensible SDK. By
5990 default, this directory is based on the :term:`DISTRO` 6765 default, this directory is based on the :term:`DISTRO`
5991 variable and is set in the 6766 variable and is set in the
5992 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as 6767 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class as
5993 follows: SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk" For the 6768 follows:
6769 ::
6770
6771 SDKEXTPATH ??= "~/${@d.getVar('DISTRO')}_sdk"
6772
6773 For the
5994 default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk". 6774 default distribution "poky", the ``SDKEXTPATH`` is set to "poky_sdk".
5995 6775
5996 For information on how to change this default directory, see the 6776 For information on how to change this default directory, see the
5997 "`Changing the Default SDK Installation 6777 ":ref:`sdk-manual/sdk-appendix-customizing:changing the default sdk installation directory`"
5998 Directory <&YOCTO_DOCS_SDK_URL;#sdk-changing-the-default-sdk-installation-directory>`__"
5999 section in the Yocto Project Application Development and the 6778 section in the Yocto Project Application Development and the
6000 Extensible Software Development Kit (eSDK) manual. 6779 Extensible Software Development Kit (eSDK) manual.
6001 6780
6002 SDKIMAGE_FEATURES 6781 SDKIMAGE_FEATURES
6003 Equivalent to ``IMAGE_FEATURES``. However, this variable applies to 6782 Equivalent to ``IMAGE_FEATURES``. However, this variable applies to
6004 the SDK generated from an image using the following command: $ 6783 the SDK generated from an image using the following command:
6005 bitbake -c populate_sdk imagename 6784 ::
6006 6785
6786 $ bitbake -c populate_sdk imagename
6787
6007 SDKMACHINE 6788 SDKMACHINE
6008 The machine for which the SDK is built. In other words, the SDK is 6789 The machine for which the SDK is built. In other words, the SDK is
6009 built such that it runs on the target you specify with the 6790 built such that it runs on the target you specify with the
6010 ``SDKMACHINE`` value. The value points to a corresponding ``.conf`` 6791 ``SDKMACHINE`` value. The value points to a corresponding ``.conf``
6011 file under ``conf/machine-sdk/``. 6792 file under ``conf/machine-sdk/``.
6012 6793
6013 You can use "i686" and "x86_64" as possible values for this variable. 6794 You can use "i686" and "x86_64" as possible values for this variable.
6014 The variable defaults to "i686" and is set in the local.conf file in 6795 The variable defaults to "i686" and is set in the local.conf file in
6015 the Build Directory. SDKMACHINE ?= "i686" 6796 the Build Directory.
6016 6797 ::
6798
6799 SDKMACHINE ?= "i686"
6800
6017 .. note:: 6801 .. note::
6018 6802
6019 You cannot set the 6803 You cannot set the
6020 SDKMACHINE 6804 SDKMACHINE
6021 variable in your distribution configuration file. If you do, the 6805 variable in your distribution configuration file. If you do, the
6022 configuration will not take affect. 6806 configuration will not take affect.
6023 6807
6024 SDKPATH 6808 SDKPATH
6025 Defines the path offered to the user for installation of the SDK that 6809 Defines the path offered to the user for installation of the SDK that
6026 is generated by the OpenEmbedded build system. The path appears as 6810 is generated by the OpenEmbedded build system. The path appears as
6027 the default location for installing the SDK when you run the SDK's 6811 the default location for installing the SDK when you run the SDK's
6028 installation script. You can override the offered path when you run 6812 installation script. You can override the offered path when you run
6029 the script. 6813 the script.
6030 6814
6031 SDKTARGETSYSROOT 6815 SDKTARGETSYSROOT
6032 The full path to the sysroot used for cross-compilation within an SDK 6816 The full path to the sysroot used for cross-compilation within an SDK
6033 as it will be when installed into the default 6817 as it will be when installed into the default
6034 :term:`SDKPATH`. 6818 :term:`SDKPATH`.
6035 6819
6036 SECTION 6820 SECTION
6037 The section in which packages should be categorized. Package 6821 The section in which packages should be categorized. Package
6038 management utilities can make use of this variable. 6822 management utilities can make use of this variable.
6039 6823
6040 SELECTED_OPTIMIZATION 6824 SELECTED_OPTIMIZATION
6041 Specifies the optimization flags passed to the C compiler when 6825 Specifies the optimization flags passed to the C compiler when
6042 building for the target. The flags are passed through the default 6826 building for the target. The flags are passed through the default
6043 value of the :term:`TARGET_CFLAGS` variable. 6827 value of the :term:`TARGET_CFLAGS` variable.
6044 6828
6045 The ``SELECTED_OPTIMIZATION`` variable takes the value of 6829 The ``SELECTED_OPTIMIZATION`` variable takes the value of
6046 ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the 6830 ``FULL_OPTIMIZATION`` unless ``DEBUG_BUILD`` = "1". If that is the
6047 case, the value of ``DEBUG_OPTIMIZATION`` is used. 6831 case, the value of ``DEBUG_OPTIMIZATION`` is used.
6048 6832
6049 SERIAL_CONSOLE 6833 SERIAL_CONSOLE
6050 Defines a serial console (TTY) to enable using 6834 Defines a serial console (TTY) to enable using
6051 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a 6835 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6052 value that specifies the baud rate followed by the TTY device name 6836 value that specifies the baud rate followed by the TTY device name
6053 separated by a space. You cannot specify more than one TTY device: 6837 separated by a space. You cannot specify more than one TTY device:
6054 SERIAL_CONSOLE = "115200 ttyS0" 6838 ::
6055 6839
6840 SERIAL_CONSOLE = "115200 ttyS0"
6841
6056 .. note:: 6842 .. note::
6057 6843
6058 The 6844 The
6059 SERIAL_CONSOLE 6845 SERIAL_CONSOLE
6060 variable is deprecated. Please use the 6846 variable is deprecated. Please use the
6061 SERIAL_CONSOLES 6847 SERIAL_CONSOLES
6062 variable. 6848 variable.
6063 6849
6064 SERIAL_CONSOLES 6850 SERIAL_CONSOLES
6065 Defines a serial console (TTY) to enable using 6851 Defines a serial console (TTY) to enable using
6066 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a 6852 `getty <https://en.wikipedia.org/wiki/Getty_(Unix)>`__. Provide a
6067 value that specifies the baud rate followed by the TTY device name 6853 value that specifies the baud rate followed by the TTY device name
6068 separated by a semicolon. Use spaces to separate multiple devices: 6854 separated by a semicolon. Use spaces to separate multiple devices:
6069 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1" 6855 ::
6070 6856
6857 SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
6858
6071 SERIAL_CONSOLES_CHECK 6859 SERIAL_CONSOLES_CHECK
6072 Specifies serial consoles, which must be listed in 6860 Specifies serial consoles, which must be listed in
6073 :term:`SERIAL_CONSOLES`, to check against 6861 :term:`SERIAL_CONSOLES`, to check against
6074 ``/proc/console`` before enabling them using getty. This variable 6862 ``/proc/console`` before enabling them using getty. This variable
6075 allows aliasing in the format: <device>:<alias>. If a device was 6863 allows aliasing in the format: <device>:<alias>. If a device was
6076 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in 6864 listed as "sclp_line0" in ``/dev/`` and "ttyS0" was listed in
6077 ``/proc/console``, you would do the following: SERIAL_CONSOLES_CHECK 6865 ``/proc/console``, you would do the following: ::
6078 = "slcp_line0:ttyS0" This variable is currently only supported with 6866
6079 SysVinit (i.e. not with systemd). 6867 SERIAL_CONSOLES_CHECK = "slcp_line0:ttyS0"
6080 6868
6869 This variable is currently only supported with SysVinit (i.e. not
6870 with systemd).
6871
6081 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS 6872 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS
6082 A list of recipe dependencies that should not be used to determine 6873 A list of recipe dependencies that should not be used to determine
6083 signatures of tasks from one recipe when they depend on tasks from 6874 signatures of tasks from one recipe when they depend on tasks from
6084 another recipe. For example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += 6875 another recipe. For example: ::
6085 "intone->mplayer2" 6876
6086 6877 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
6878
6087 In the previous example, ``intone`` depends on ``mplayer2``. 6879 In the previous example, ``intone`` depends on ``mplayer2``.
6088 6880
6089 You can use the special token ``"*"`` on the left-hand side of the 6881 You can use the special token ``"*"`` on the left-hand side of the
6090 dependency to match all recipes except the one on the right-hand 6882 dependency to match all recipes except the one on the right-hand
6091 side. Here is an example: SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += 6883 side. Here is an example: ::
6092 "*->quilt-native" 6884
6093 6885 SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "*->quilt-native"
6886
6094 In the previous example, all recipes except ``quilt-native`` ignore 6887 In the previous example, all recipes except ``quilt-native`` ignore
6095 task signatures from the ``quilt-native`` recipe when determining 6888 task signatures from the ``quilt-native`` recipe when determining
6096 their task signatures. 6889 their task signatures.
6097 6890
6098 Use of this variable is one mechanism to remove dependencies that 6891 Use of this variable is one mechanism to remove dependencies that
6099 affect task signatures and thus force rebuilds when a recipe changes. 6892 affect task signatures and thus force rebuilds when a recipe changes.
6100 6893
6101 .. note:: 6894 .. note::
6102 6895
6103 If you add an inappropriate dependency for a recipe relationship, 6896 If you add an inappropriate dependency for a recipe relationship,
6104 the software might break during runtime if the interface of the 6897 the software might break during runtime if the interface of the
6105 second recipe was changed after the first recipe had been built. 6898 second recipe was changed after the first recipe had been built.
6106 6899
6107 SIGGEN_EXCLUDERECIPES_ABISAFE 6900 SIGGEN_EXCLUDERECIPES_ABISAFE
6108 A list of recipes that are completely stable and will never change. 6901 A list of recipes that are completely stable and will never change.
6109 The ABI for the recipes in the list are presented by output from the 6902 The ABI for the recipes in the list are presented by output from the
6110 tasks run to build the recipe. Use of this variable is one way to 6903 tasks run to build the recipe. Use of this variable is one way to
6111 remove dependencies from one recipe on another that affect task 6904 remove dependencies from one recipe on another that affect task
6112 signatures and thus force rebuilds when the recipe changes. 6905 signatures and thus force rebuilds when the recipe changes.
6113 6906
6114 .. note:: 6907 .. note::
6115 6908
6116 If you add an inappropriate variable to this list, the software 6909 If you add an inappropriate variable to this list, the software
6117 might break at runtime if the interface of the recipe was changed 6910 might break at runtime if the interface of the recipe was changed
6118 after the other had been built. 6911 after the other had been built.
6119 6912
6120 SITEINFO_BITS 6913 SITEINFO_BITS
6121 Specifies the number of bits for the target system CPU. The value 6914 Specifies the number of bits for the target system CPU. The value
6122 should be either "32" or "64". 6915 should be either "32" or "64".
6123 6916
6124 SITEINFO_ENDIANNESS 6917 SITEINFO_ENDIANNESS
6125 Specifies the endian byte order of the target system. The value 6918 Specifies the endian byte order of the target system. The value
6126 should be either "le" for little-endian or "be" for big-endian. 6919 should be either "le" for little-endian or "be" for big-endian.
6127 6920
6128 SKIP_FILEDEPS 6921 SKIP_FILEDEPS
6129 Enables removal of all files from the "Provides" section of an RPM 6922 Enables removal of all files from the "Provides" section of an RPM
6130 package. Removal of these files is required for packages containing 6923 package. Removal of these files is required for packages containing
6131 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``. 6924 prebuilt binaries and libraries such as ``libstdc++`` and ``glibc``.
6132 6925
6133 To enable file removal, set the variable to "1" in your 6926 To enable file removal, set the variable to "1" in your
6134 ``conf/local.conf`` configuration file in your: 6927 ``conf/local.conf`` configuration file in your:
6135 :term:`Build Directory`. SKIP_FILEDEPS = "1" 6928 :term:`Build Directory`.
6136 6929 ::
6930
6931 SKIP_FILEDEPS = "1"
6932
6137 SOC_FAMILY 6933 SOC_FAMILY
6138 Groups together machines based upon the same family of SOC (System On 6934 Groups together machines based upon the same family of SOC (System On
6139 Chip). You typically set this variable in a common ``.inc`` file that 6935 Chip). You typically set this variable in a common ``.inc`` file that
6140 you include in the configuration files of all the machines. 6936 you include in the configuration files of all the machines.
6141 6937
6142 .. note:: 6938 .. note::
6143 6939
6144 You must include 6940 You must include
6145 conf/machine/include/soc-family.inc 6941 conf/machine/include/soc-family.inc
6146 for this variable to appear in 6942 for this variable to appear in
6147 MACHINEOVERRIDES 6943 MACHINEOVERRIDES
6148 . 6944 .
6149 6945
6150 SOLIBS 6946 SOLIBS
6151 Defines the suffix for shared libraries used on the target platform. 6947 Defines the suffix for shared libraries used on the target platform.
6152 By default, this suffix is ".so.*" for all Linux-based systems and is 6948 By default, this suffix is ".so.*" for all Linux-based systems and is
6153 defined in the ``meta/conf/bitbake.conf`` configuration file. 6949 defined in the ``meta/conf/bitbake.conf`` configuration file.
6154 6950
6155 You will see this variable referenced in the default values of 6951 You will see this variable referenced in the default values of
6156 ``FILES_${PN}``. 6952 ``FILES_${PN}``.
6157 6953
6158 SOLIBSDEV 6954 SOLIBSDEV
6159 Defines the suffix for the development symbolic link (symlink) for 6955 Defines the suffix for the development symbolic link (symlink) for
6160 shared libraries on the target platform. By default, this suffix is 6956 shared libraries on the target platform. By default, this suffix is
6161 ".so" for Linux-based systems and is defined in the 6957 ".so" for Linux-based systems and is defined in the
6162 ``meta/conf/bitbake.conf`` configuration file. 6958 ``meta/conf/bitbake.conf`` configuration file.
6163 6959
6164 You will see this variable referenced in the default values of 6960 You will see this variable referenced in the default values of
6165 ``FILES_${PN}-dev``. 6961 ``FILES_${PN}-dev``.
6166 6962
6167 SOURCE_MIRROR_FETCH 6963 SOURCE_MIRROR_FETCH
6168 When you are fetching files to create a mirror of sources (i.e. 6964 When you are fetching files to create a mirror of sources (i.e.
6169 creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in 6965 creating a source mirror), setting ``SOURCE_MIRROR_FETCH`` to "1" in
@@ -6175,69 +6971,75 @@ system and gives an overview of their function and contents.
6175 variable and :term:`COMPATIBLE_HOST` variables 6971 variable and :term:`COMPATIBLE_HOST` variables
6176 specify compatibility with a machine other than that of the current 6972 specify compatibility with a machine other than that of the current
6177 machine or host. 6973 machine or host.
6178 6974
6179 .. note:: 6975 .. note::
6180 6976
6181 Do not set the 6977 Do not set the
6182 SOURCE_MIRROR_FETCH 6978 SOURCE_MIRROR_FETCH
6183 variable unless you are creating a source mirror. In other words, 6979 variable unless you are creating a source mirror. In other words,
6184 do not set the variable during a normal build. 6980 do not set the variable during a normal build.
6185 6981
6186 SOURCE_MIRROR_URL 6982 SOURCE_MIRROR_URL
6187 Defines your own :term:`PREMIRRORS` from which to 6983 Defines your own :term:`PREMIRRORS` from which to
6188 first fetch source before attempting to fetch from the upstream 6984 first fetch source before attempting to fetch from the upstream
6189 specified in :term:`SRC_URI`. 6985 specified in :term:`SRC_URI`.
6190 6986
6191 To use this variable, you must globally inherit the 6987 To use this variable, you must globally inherit the
6192 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide 6988 :ref:`own-mirrors <ref-classes-own-mirrors>` class and then provide
6193 the URL to your mirrors. Here is the general syntax: INHERIT += 6989 the URL to your mirrors. Here is the general syntax:
6194 "own-mirrors" SOURCE_MIRROR_URL = 6990 ::
6195 "http://example.com/my_source_mirror" 6991
6196 6992 INHERIT += "own-mirrors"
6993 SOURCE_MIRROR_URL = "http://example.com/my_source_mirror"
6994
6197 .. note:: 6995 .. note::
6198 6996
6199 You can specify only a single URL in 6997 You can specify only a single URL in
6200 SOURCE_MIRROR_URL 6998 SOURCE_MIRROR_URL
6201 . 6999 .
6202 7000
6203 SPDXLICENSEMAP 7001 SPDXLICENSEMAP
6204 Maps commonly used license names to their SPDX counterparts found in 7002 Maps commonly used license names to their SPDX counterparts found in
6205 ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP`` 7003 ``meta/files/common-licenses/``. For the default ``SPDXLICENSEMAP``
6206 mappings, see the ``meta/conf/licenses.conf`` file. 7004 mappings, see the ``meta/conf/licenses.conf`` file.
6207 7005
6208 For additional information, see the :term:`LICENSE` 7006 For additional information, see the :term:`LICENSE`
6209 variable. 7007 variable.
6210 7008
6211 SPECIAL_PKGSUFFIX 7009 SPECIAL_PKGSUFFIX
6212 A list of prefixes for :term:`PN` used by the OpenEmbedded 7010 A list of prefixes for :term:`PN` used by the OpenEmbedded
6213 build system to create variants of recipes or packages. The list 7011 build system to create variants of recipes or packages. The list
6214 specifies the prefixes to strip off during certain circumstances such 7012 specifies the prefixes to strip off during certain circumstances such
6215 as the generation of the :term:`BPN` variable. 7013 as the generation of the :term:`BPN` variable.
6216 7014
6217 SPL_BINARY 7015 SPL_BINARY
6218 The file type for the Secondary Program Loader (SPL). Some devices 7016 The file type for the Secondary Program Loader (SPL). Some devices
6219 use an SPL from which to boot (e.g. the BeagleBone development 7017 use an SPL from which to boot (e.g. the BeagleBone development
6220 board). For such cases, you can declare the file type of the SPL 7018 board). For such cases, you can declare the file type of the SPL
6221 binary in the ``u-boot.inc`` include file, which is used in the 7019 binary in the ``u-boot.inc`` include file, which is used in the
6222 U-Boot recipe. 7020 U-Boot recipe.
6223 7021
6224 The SPL file type is set to "null" by default in the ``u-boot.inc`` 7022 The SPL file type is set to "null" by default in the ``u-boot.inc``
6225 file as follows: # Some versions of u-boot build an SPL (Second 7023 file as follows:
6226 Program Loader) image that # should be packaged along with the u-boot 7024 ::
6227 binary as well as placed in the # deploy directory. For those 7025
6228 versions they can set the following variables # to allow packaging 7026 # Some versions of u-boot build an SPL (Second Program Loader) image that
6229 the SPL. SPL_BINARY ?= "" SPL_BINARYNAME ?= 7027 # should be packaged along with the u-boot binary as well as placed in the
6230 "${@os.path.basename(d.getVar("SPL_BINARY"))}" SPL_IMAGE ?= 7028 # deploy directory. For those versions they can set the following variables
6231 "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}" SPL_SYMLINK ?= 7029 # to allow packaging the SPL.
6232 "${SPL_BINARYNAME}-${MACHINE}" The ``SPL_BINARY`` variable helps form 7030 SPL_BINARY ?= ""
7031 SPL_BINARYNAME ?= "${@os.path.basename(d.getVar("SPL_BINARY"))}"
7032 SPL_IMAGE ?= "${SPL_BINARYNAME}-${MACHINE}-${PV}-${PR}"
7033 SPL_SYMLINK ?= "${SPL_BINARYNAME}-${MACHINE}"
7034
7035 The ``SPL_BINARY`` variable helps form
6233 various ``SPL_*`` variables used by the OpenEmbedded build system. 7036 various ``SPL_*`` variables used by the OpenEmbedded build system.
6234 7037
6235 See the BeagleBone machine configuration example in the "`Creating a 7038 See the BeagleBone machine configuration example in the
6236 new BSP Layer Using the ``bitbake-layers`` 7039 ":ref:`dev-manual/dev-manual-common-tasks:adding a layer using the \`\`bitbake-layers\`\` script`"
6237 Script <&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script>`__"
6238 section in the Yocto Project Board Support Package Developer's Guide 7040 section in the Yocto Project Board Support Package Developer's Guide
6239 for additional information. 7041 for additional information.
6240 7042
6241 SRC_URI 7043 SRC_URI
6242 The list of source files - local or remote. This variable tells the 7044 The list of source files - local or remote. This variable tells the
6243 OpenEmbedded build system which bits to pull in for the build and how 7045 OpenEmbedded build system which bits to pull in for the build and how
@@ -6247,34 +7049,34 @@ system and gives an overview of their function and contents.
6247 append file needs to fetch a tarball, apply two patches, and include 7049 append file needs to fetch a tarball, apply two patches, and include
6248 a custom file, the recipe or append file would include four instances 7050 a custom file, the recipe or append file would include four instances
6249 of the variable. 7051 of the variable.
6250 7052
6251 The following list explains the available URI protocols. URI 7053 The following list explains the available URI protocols. URI
6252 protocols are highly dependent on particular BitBake Fetcher 7054 protocols are highly dependent on particular BitBake Fetcher
6253 submodules. Depending on the fetcher BitBake uses, various URL 7055 submodules. Depending on the fetcher BitBake uses, various URL
6254 parameters are employed. For specifics on the supported Fetchers, see 7056 parameters are employed. For specifics on the supported Fetchers, see
6255 the ":ref:`Fetchers <bitbake:bb-fetchers>`" section in the 7057 the ":ref:`Fetchers <bitbake:bb-fetchers>`" section in the
6256 BitBake User Manual. 7058 BitBake User Manual.
6257 7059
6258 - *``file://`` -* Fetches files, which are usually files shipped 7060 - ``file://`` - Fetches files, which are usually files shipped
6259 with the :term:`Metadata`, from the local machine (e.g. 7061 with the :term:`Metadata`, from the local machine (e.g.
6260 `patch <&YOCTO_DOCS_OM_URL;#patching-dev-environment>`__ files). 7062 :ref:`patch <patching-dev-environment>` files).
6261 The path is relative to the :term:`FILESPATH` 7063 The path is relative to the :term:`FILESPATH`
6262 variable. Thus, the build system searches, in order, from the 7064 variable. Thus, the build system searches, in order, from the
6263 following directories, which are assumed to be a subdirectories of 7065 following directories, which are assumed to be a subdirectories of
6264 the directory in which the recipe file (``.bb``) or append file 7066 the directory in which the recipe file (``.bb``) or append file
6265 (``.bbappend``) resides: 7067 (``.bbappend``) resides:
6266 7068
6267 - *``${BPN}`` -* The base recipe name without any special suffix 7069 - ``${BPN}`` - The base recipe name without any special suffix
6268 or version numbers. 7070 or version numbers.
6269 7071
6270 - *``${BP}`` -* ``${BPN}-${PV}``. The base recipe name and 7072 - ``${BP}`` - ``${BPN}-${PV}``. The base recipe name and
6271 version but without any special package name suffix. 7073 version but without any special package name suffix.
6272 7074
6273 - *files -* Files within a directory, which is named ``files`` 7075 - *files -* Files within a directory, which is named ``files``
6274 and is also alongside the recipe or append file. 7076 and is also alongside the recipe or append file.
6275 7077
6276 .. note:: 7078 .. note::
6277 7079
6278 If you want the build system to pick up files specified through 7080 If you want the build system to pick up files specified through
6279 a 7081 a
6280 SRC_URI 7082 SRC_URI
@@ -6284,127 +7086,133 @@ system and gives an overview of their function and contents.
6284 variable by also using the 7086 variable by also using the
6285 FILESEXTRAPATHS 7087 FILESEXTRAPATHS
6286 variable from within your append file. 7088 variable from within your append file.
6287 7089
6288 - *``bzr://`` -* Fetches files from a Bazaar revision control 7090 - ``bzr://`` - Fetches files from a Bazaar revision control
6289 repository. 7091 repository.
6290 7092
6291 - *``git://`` -* Fetches files from a Git revision control 7093 - ``git://`` - Fetches files from a Git revision control
6292 repository. 7094 repository.
6293 7095
6294 - *``osc://`` -* Fetches files from an OSC (OpenSUSE Build service) 7096 - ``osc://`` - Fetches files from an OSC (OpenSUSE Build service)
6295 revision control repository. 7097 revision control repository.
6296 7098
6297 - *``repo://`` -* Fetches files from a repo (Git) repository. 7099 - ``repo://`` - Fetches files from a repo (Git) repository.
6298 7100
6299 - *``ccrc://`` -* Fetches files from a ClearCase repository. 7101 - ``ccrc://`` - Fetches files from a ClearCase repository.
6300 7102
6301 - *``http://`` -* Fetches files from the Internet using ``http``. 7103 - ``http://`` - Fetches files from the Internet using ``http``.
6302 7104
6303 - *``https://`` -* Fetches files from the Internet using ``https``. 7105 - ``https://`` - Fetches files from the Internet using ``https``.
6304 7106
6305 - *``ftp://`` -* Fetches files from the Internet using ``ftp``. 7107 - ``ftp://`` - Fetches files from the Internet using ``ftp``.
6306 7108
6307 - *``cvs://`` -* Fetches files from a CVS revision control 7109 - ``cvs://`` - Fetches files from a CVS revision control
6308 repository. 7110 repository.
6309 7111
6310 - *``hg://`` -* Fetches files from a Mercurial (``hg``) revision 7112 - ``hg://`` - Fetches files from a Mercurial (``hg``) revision
6311 control repository. 7113 control repository.
6312 7114
6313 - *``p4://`` -* Fetches files from a Perforce (``p4``) revision 7115 - ``p4://`` - Fetches files from a Perforce (``p4``) revision
6314 control repository. 7116 control repository.
6315 7117
6316 - *``ssh://`` -* Fetches files from a secure shell. 7118 - ``ssh://`` - Fetches files from a secure shell.
6317 7119
6318 - *``svn://`` -* Fetches files from a Subversion (``svn``) revision 7120 - ``svn://`` - Fetches files from a Subversion (``svn``) revision
6319 control repository. 7121 control repository.
6320 7122
6321 - *``npm://`` -* Fetches JavaScript modules from a registry. 7123 - ``npm://`` - Fetches JavaScript modules from a registry.
6322 7124
6323 Standard and recipe-specific options for ``SRC_URI`` exist. Here are 7125 Standard and recipe-specific options for ``SRC_URI`` exist. Here are
6324 standard options: 7126 standard options:
6325 7127
6326 - *``apply`` -* Whether to apply the patch or not. The default 7128 - ``apply`` - Whether to apply the patch or not. The default
6327 action is to apply the patch. 7129 action is to apply the patch.
6328 7130
6329 - *``striplevel`` -* Which striplevel to use when applying the 7131 - ``striplevel`` - Which striplevel to use when applying the
6330 patch. The default level is 1. 7132 patch. The default level is 1.
6331 7133
6332 - *``patchdir`` -* Specifies the directory in which the patch should 7134 - ``patchdir`` - Specifies the directory in which the patch should
6333 be applied. The default is ``${``\ :term:`S`\ ``}``. 7135 be applied. The default is ``${``\ :term:`S`\ ``}``.
6334 7136
6335 Here are options specific to recipes building code from a revision 7137 Here are options specific to recipes building code from a revision
6336 control system: 7138 control system:
6337 7139
6338 - *``mindate`` -* Apply the patch only if 7140 - ``mindate`` - Apply the patch only if
6339 :term:`SRCDATE` is equal to or greater than 7141 :term:`SRCDATE` is equal to or greater than
6340 ``mindate``. 7142 ``mindate``.
6341 7143
6342 - *``maxdate`` -* Apply the patch only if ``SRCDATE`` is not later 7144 - ``maxdate`` - Apply the patch only if ``SRCDATE`` is not later
6343 than ``maxdate``. 7145 than ``maxdate``.
6344 7146
6345 - *``minrev`` -* Apply the patch only if ``SRCREV`` is equal to or 7147 - ``minrev`` - Apply the patch only if ``SRCREV`` is equal to or
6346 greater than ``minrev``. 7148 greater than ``minrev``.
6347 7149
6348 - *``maxrev`` -* Apply the patch only if ``SRCREV`` is not later 7150 - ``maxrev`` - Apply the patch only if ``SRCREV`` is not later
6349 than ``maxrev``. 7151 than ``maxrev``.
6350 7152
6351 - *``rev`` -* Apply the patch only if ``SRCREV`` is equal to 7153 - ``rev`` - Apply the patch only if ``SRCREV`` is equal to
6352 ``rev``. 7154 ``rev``.
6353 7155
6354 - *``notrev`` -* Apply the patch only if ``SRCREV`` is not equal to 7156 - ``notrev`` - Apply the patch only if ``SRCREV`` is not equal to
6355 ``rev``. 7157 ``rev``.
6356 7158
6357 Here are some additional options worth mentioning: 7159 Here are some additional options worth mentioning:
6358 7160
6359 - *``unpack`` -* Controls whether or not to unpack the file if it is 7161 - ``unpack`` - Controls whether or not to unpack the file if it is
6360 an archive. The default action is to unpack the file. 7162 an archive. The default action is to unpack the file.
6361 7163
6362 - *``destsuffix`` -* Places the file (or extracts its contents) into 7164 - ``destsuffix`` - Places the file (or extracts its contents) into
6363 the specified subdirectory of :term:`WORKDIR` when 7165 the specified subdirectory of :term:`WORKDIR` when
6364 the Git fetcher is used. 7166 the Git fetcher is used.
6365 7167
6366 - *``subdir`` -* Places the file (or extracts its contents) into the 7168 - ``subdir`` - Places the file (or extracts its contents) into the
6367 specified subdirectory of ``WORKDIR`` when the local (``file://``) 7169 specified subdirectory of ``WORKDIR`` when the local (``file://``)
6368 fetcher is used. 7170 fetcher is used.
6369 7171
6370 - *``localdir`` -* Places the file (or extracts its contents) into 7172 - ``localdir`` - Places the file (or extracts its contents) into
6371 the specified subdirectory of ``WORKDIR`` when the CVS fetcher is 7173 the specified subdirectory of ``WORKDIR`` when the CVS fetcher is
6372 used. 7174 used.
6373 7175
6374 - *``subpath`` -* Limits the checkout to a specific subpath of the 7176 - ``subpath`` - Limits the checkout to a specific subpath of the
6375 tree when using the Git fetcher is used. 7177 tree when using the Git fetcher is used.
6376 7178
6377 - *``name`` -* Specifies a name to be used for association with 7179 - ``name`` - Specifies a name to be used for association with
6378 ``SRC_URI`` checksums when you have more than one file specified 7180 ``SRC_URI`` checksums when you have more than one file specified
6379 in ``SRC_URI``. 7181 in ``SRC_URI``.
6380 7182
6381 - *``downloadfilename`` -* Specifies the filename used when storing 7183 - ``downloadfilename`` - Specifies the filename used when storing
6382 the downloaded file. 7184 the downloaded file.
6383 7185
6384 SRC_URI_OVERRIDES_PACKAGE_ARCH 7186 SRC_URI_OVERRIDES_PACKAGE_ARCH
6385 By default, the OpenEmbedded build system automatically detects 7187 By default, the OpenEmbedded build system automatically detects
6386 whether ``SRC_URI`` contains files that are machine-specific. If so, 7188 whether ``SRC_URI`` contains files that are machine-specific. If so,
6387 the build system automatically changes ``PACKAGE_ARCH``. Setting this 7189 the build system automatically changes ``PACKAGE_ARCH``. Setting this
6388 variable to "0" disables this behavior. 7190 variable to "0" disables this behavior.
6389 7191
6390 SRCDATE 7192 SRCDATE
6391 The date of the source code used to build the package. This variable 7193 The date of the source code used to build the package. This variable
6392 applies only if the source was fetched from a Source Code Manager 7194 applies only if the source was fetched from a Source Code Manager
6393 (SCM). 7195 (SCM).
6394 7196
6395 SRCPV 7197 SRCPV
6396 Returns the version string of the current package. This string is 7198 Returns the version string of the current package. This string is
6397 used to help define the value of :term:`PV`. 7199 used to help define the value of :term:`PV`.
6398 7200
6399 The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf`` 7201 The ``SRCPV`` variable is defined in the ``meta/conf/bitbake.conf``
6400 configuration file in the :term:`Source Directory` as 7202 configuration file in the :term:`Source Directory` as
6401 follows: SRCPV = "${@bb.fetch2.get_srcrev(d)}" 7203 follows:
6402 7204 ::
7205
7206 SRCPV = "${@bb.fetch2.get_srcrev(d)}"
7207
6403 Recipes that need to define ``PV`` do so with the help of the 7208 Recipes that need to define ``PV`` do so with the help of the
6404 ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``) 7209 ``SRCPV``. For example, the ``ofono`` recipe (``ofono_git.bb``)
6405 located in ``meta/recipes-connectivity`` in the Source Directory 7210 located in ``meta/recipes-connectivity`` in the Source Directory
6406 defines ``PV`` as follows: PV = "0.12-git${SRCPV}" 7211 defines ``PV`` as follows:
6407 7212 ::
7213
7214 PV = "0.12-git${SRCPV}"
7215
6408 SRCREV 7216 SRCREV
6409 The revision of the source code used to build the package. This 7217 The revision of the source code used to build the package. This
6410 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note 7218 variable applies to Subversion, Git, Mercurial, and Bazaar only. Note
@@ -6412,9 +7220,9 @@ system and gives an overview of their function and contents.
6412 performing a query on the remote repository every time BitBake parses 7220 performing a query on the remote repository every time BitBake parses
6413 your recipe, you should specify a ``SRCREV`` that is a full revision 7221 your recipe, you should specify a ``SRCREV`` that is a full revision
6414 identifier and not just a tag. 7222 identifier and not just a tag.
6415 7223
6416 .. note:: 7224 .. note::
6417 7225
6418 For information on limitations when inheriting the latest revision 7226 For information on limitations when inheriting the latest revision
6419 of software using 7227 of software using
6420 SRCREV 7228 SRCREV
@@ -6423,10 +7231,10 @@ system and gives an overview of their function and contents.
6423 variable description and the " 7231 variable description and the "
6424 Automatically Incrementing a Binary Package Revision Number 7232 Automatically Incrementing a Binary Package Revision Number
6425 " section, which is in the Yocto Project Development Tasks Manual. 7233 " section, which is in the Yocto Project Development Tasks Manual.
6426 7234
6427 SSTATE_DIR 7235 SSTATE_DIR
6428 The directory for the shared state cache. 7236 The directory for the shared state cache.
6429 7237
6430 SSTATE_MIRROR_ALLOW_NETWORK 7238 SSTATE_MIRROR_ALLOW_NETWORK
6431 If set to "1", allows fetches from mirrors that are specified in 7239 If set to "1", allows fetches from mirrors that are specified in
6432 :term:`SSTATE_MIRRORS` to work even when 7240 :term:`SSTATE_MIRRORS` to work even when
@@ -6435,19 +7243,19 @@ system and gives an overview of their function and contents.
6435 you have set ``SSTATE_MIRRORS`` to point to an internal server for 7243 you have set ``SSTATE_MIRRORS`` to point to an internal server for
6436 your shared state cache, but you want to disable any other fetching 7244 your shared state cache, but you want to disable any other fetching
6437 from the network. 7245 from the network.
6438 7246
6439 SSTATE_MIRRORS 7247 SSTATE_MIRRORS
6440 Configures the OpenEmbedded build system to search other mirror 7248 Configures the OpenEmbedded build system to search other mirror
6441 locations for prebuilt cache data objects before building out the 7249 locations for prebuilt cache data objects before building out the
6442 data. This variable works like fetcher :term:`MIRRORS` 7250 data. This variable works like fetcher :term:`MIRRORS`
6443 and :term:`PREMIRRORS` and points to the cache 7251 and :term:`PREMIRRORS` and points to the cache
6444 locations to check for the shared state (sstate) objects. 7252 locations to check for the shared state (sstate) objects.
6445 7253
6446 You can specify a filesystem directory or a remote URL such as HTTP 7254 You can specify a filesystem directory or a remote URL such as HTTP
6447 or FTP. The locations you specify need to contain the shared state 7255 or FTP. The locations you specify need to contain the shared state
6448 cache (sstate-cache) results from previous builds. The sstate-cache 7256 cache (sstate-cache) results from previous builds. The sstate-cache
6449 you point to can also be from builds on other machines. 7257 you point to can also be from builds on other machines.
6450 7258
6451 When pointing to sstate build artifacts on another machine that uses 7259 When pointing to sstate build artifacts on another machine that uses
6452 a different GCC version for native builds, you must configure 7260 a different GCC version for native builds, you must configure
6453 ``SSTATE_MIRRORS`` with a regular expression that maps local search 7261 ``SSTATE_MIRRORS`` with a regular expression that maps local search
@@ -6455,24 +7263,27 @@ system and gives an overview of their function and contents.
6455 :term:`NATIVELSBSTRING` set by the 7263 :term:`NATIVELSBSTRING` set by the
6456 :ref:`uninative <ref-classes-uninative>` class. For example, the 7264 :ref:`uninative <ref-classes-uninative>` class. For example, the
6457 following maps the local search path ``universal-4.9`` to the 7265 following maps the local search path ``universal-4.9`` to the
6458 server-provided path server_url_sstate_path: SSTATE_MIRRORS ?= 7266 server-provided path server_url_sstate_path:
6459 file://universal-4.9/(.*) 7267 ::
6460 http://server_url_sstate_path/universal-4.8/\1 \\n 7268
6461 7269 SSTATE_MIRRORS ?= "file://universal-4.9/(.*) http://server_url_sstate_path/universal-4.8/\1 \n"
7270
6462 If a mirror uses the same structure as 7271 If a mirror uses the same structure as
6463 :term:`SSTATE_DIR`, you need to add "PATH" at the 7272 :term:`SSTATE_DIR`, you need to add "PATH" at the
6464 end as shown in the examples below. The build system substitutes the 7273 end as shown in the examples below. The build system substitutes the
6465 correct path within the directory structure. SSTATE_MIRRORS ?= "\\ 7274 correct path within the directory structure.
6466 file://.\* 7275 ::
6467 http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \\n \\ 7276
6468 file://.\* file:///some-local-dir/sstate/PATH" 7277 SSTATE_MIRRORS ?= "\
6469 7278 file://.* http://someserver.tld/share/sstate/PATH;downloadfilename=PATH \n \
7279 file://.* file:///some-local-dir/sstate/PATH"
7280
6470 SSTATE_SCAN_FILES 7281 SSTATE_SCAN_FILES
6471 Controls the list of files the OpenEmbedded build system scans for 7282 Controls the list of files the OpenEmbedded build system scans for
6472 hardcoded installation paths. The variable uses a space-separated 7283 hardcoded installation paths. The variable uses a space-separated
6473 list of filenames (not paths) with standard wildcard characters 7284 list of filenames (not paths) with standard wildcard characters
6474 allowed. 7285 allowed.
6475 7286
6476 During a build, the OpenEmbedded build system creates a shared state 7287 During a build, the OpenEmbedded build system creates a shared state
6477 (sstate) object during the first stage of preparing the sysroots. 7288 (sstate) object during the first stage of preparing the sysroots.
6478 That object is scanned for hardcoded paths for original installation 7289 That object is scanned for hardcoded paths for original installation
@@ -6482,32 +7293,32 @@ system and gives an overview of their function and contents.
6482 than the variable being comprehensively set. The 7293 than the variable being comprehensively set. The
6483 :ref:`sstate <ref-classes-sstate>` class specifies the default list 7294 :ref:`sstate <ref-classes-sstate>` class specifies the default list
6484 of files. 7295 of files.
6485 7296
6486 For details on the process, see the 7297 For details on the process, see the
6487 :ref:`staging <ref-classes-staging>` class. 7298 :ref:`staging <ref-classes-staging>` class.
6488 7299
6489 STAGING_BASE_LIBDIR_NATIVE 7300 STAGING_BASE_LIBDIR_NATIVE
6490 Specifies the path to the ``/lib`` subdirectory of the sysroot 7301 Specifies the path to the ``/lib`` subdirectory of the sysroot
6491 directory for the build host. 7302 directory for the build host.
6492 7303
6493 STAGING_BASELIBDIR 7304 STAGING_BASELIBDIR
6494 Specifies the path to the ``/lib`` subdirectory of the sysroot 7305 Specifies the path to the ``/lib`` subdirectory of the sysroot
6495 directory for the target for which the current recipe is being built 7306 directory for the target for which the current recipe is being built
6496 (:term:`STAGING_DIR_HOST`). 7307 (:term:`STAGING_DIR_HOST`).
6497 7308
6498 STAGING_BINDIR 7309 STAGING_BINDIR
6499 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 7310 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6500 directory for the target for which the current recipe is being built 7311 directory for the target for which the current recipe is being built
6501 (:term:`STAGING_DIR_HOST`). 7312 (:term:`STAGING_DIR_HOST`).
6502 7313
6503 STAGING_BINDIR_CROSS 7314 STAGING_BINDIR_CROSS
6504 Specifies the path to the directory containing binary configuration 7315 Specifies the path to the directory containing binary configuration
6505 scripts. These scripts provide configuration information for other 7316 scripts. These scripts provide configuration information for other
6506 software that wants to make use of libraries or include files 7317 software that wants to make use of libraries or include files
6507 provided by the software associated with the script. 7318 provided by the software associated with the script.
6508 7319
6509 .. note:: 7320 .. note::
6510 7321
6511 This style of build configuration has been largely replaced by 7322 This style of build configuration has been largely replaced by
6512 pkg-config 7323 pkg-config
6513 . Consequently, if 7324 . Consequently, if
@@ -6516,36 +7327,34 @@ system and gives an overview of their function and contents.
6516 recommended you use 7327 recommended you use
6517 pkg-config 7328 pkg-config
6518 instead of a provided configuration script. 7329 instead of a provided configuration script.
6519 7330
6520 STAGING_BINDIR_NATIVE 7331 STAGING_BINDIR_NATIVE
6521 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot 7332 Specifies the path to the ``/usr/bin`` subdirectory of the sysroot
6522 directory for the build host. 7333 directory for the build host.
6523 7334
6524 STAGING_DATADIR 7335 STAGING_DATADIR
6525 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 7336 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6526 directory for the target for which the current recipe is being built 7337 directory for the target for which the current recipe is being built
6527 (:term:`STAGING_DIR_HOST`). 7338 (:term:`STAGING_DIR_HOST`).
6528 7339
6529 STAGING_DATADIR_NATIVE 7340 STAGING_DATADIR_NATIVE
6530 Specifies the path to the ``/usr/share`` subdirectory of the sysroot 7341 Specifies the path to the ``/usr/share`` subdirectory of the sysroot
6531 directory for the build host. 7342 directory for the build host.
6532 7343
6533 STAGING_DIR 7344 STAGING_DIR
6534 Helps construct the ``recipe-sysroots`` directory, which is used 7345 Helps construct the ``recipe-sysroots`` directory, which is used
6535 during packaging. 7346 during packaging.
6536 7347
6537 For information on how staging for recipe-specific sysroots occurs, 7348 For information on how staging for recipe-specific sysroots occurs,
6538 see the :ref:`ref-tasks-populate_sysroot` 7349 see the :ref:`ref-tasks-populate_sysroot`
6539 task, the "`Sharing Files Between 7350 task, the ":ref:`sdk-manual/sdk-extensible:sharing files between recipes`"
6540 Recipes <&YOCTO_DOCS_DEV_URL;#new-sharing-files-between-recipes>`__"
6541 section in the Yocto Project Development Tasks Manual, the 7351 section in the Yocto Project Development Tasks Manual, the
6542 "`Configuration, Compilation, and 7352 ":ref:`configuration-compilation-and-staging-dev-environment`"
6543 Staging <&YOCTO_DOCS_OM_URL;#configuration-compilation-and-staging-dev-environment>`__"
6544 section in the Yocto Project Overview and Concepts Manual, and the 7353 section in the Yocto Project Overview and Concepts Manual, and the
6545 :term:`SYSROOT_DIRS` variable. 7354 :term:`SYSROOT_DIRS` variable.
6546 7355
6547 .. note:: 7356 .. note::
6548 7357
6549 Recipes should never write files directly under the 7358 Recipes should never write files directly under the
6550 STAGING_DIR 7359 STAGING_DIR
6551 directory because the OpenEmbedded build system manages the 7360 directory because the OpenEmbedded build system manages the
@@ -6557,7 +7366,7 @@ system and gives an overview of their function and contents.
6557 do_install 7366 do_install
6558 task and then the OpenEmbedded build system will stage a subset of 7367 task and then the OpenEmbedded build system will stage a subset of
6559 those files into the sysroot. 7368 those files into the sysroot.
6560 7369
6561 STAGING_DIR_HOST 7370 STAGING_DIR_HOST
6562 Specifies the path to the sysroot directory for the system on which 7371 Specifies the path to the sysroot directory for the system on which
6563 the component is built to run (the system that hosts the component). 7372 the component is built to run (the system that hosts the component).
@@ -6568,16 +7377,16 @@ system and gives an overview of their function and contents.
6568 :term:`STAGING_DIR_NATIVE`. Depending on 7377 :term:`STAGING_DIR_NATIVE`. Depending on
6569 the type of recipe and the build target, ``STAGING_DIR_HOST`` can 7378 the type of recipe and the build target, ``STAGING_DIR_HOST`` can
6570 have the following values: 7379 have the following values:
6571 7380
6572 - For recipes building for the target machine, the value is 7381 - For recipes building for the target machine, the value is
6573 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}". 7382 "${:term:`STAGING_DIR`}/${:term:`MACHINE`}".
6574 7383
6575 - For native recipes building for the build host, the value is empty 7384 - For native recipes building for the build host, the value is empty
6576 given the assumption that when building for the build host, the 7385 given the assumption that when building for the build host, the
6577 build host's own directories should be used. 7386 build host's own directories should be used.
6578 7387
6579 .. note:: 7388 .. note::
6580 7389
6581 ``-native`` recipes are not installed into host paths like such 7390 ``-native`` recipes are not installed into host paths like such
6582 as ``/usr``. Rather, these recipes are installed into 7391 as ``/usr``. Rather, these recipes are installed into
6583 ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes, 7392 ``STAGING_DIR_NATIVE``. When compiling ``-native`` recipes,
@@ -6586,7 +7395,7 @@ system and gives an overview of their function and contents.
6586 :term:`CFLAGS` are set up so that both host paths 7395 :term:`CFLAGS` are set up so that both host paths
6587 and ``STAGING_DIR_NATIVE`` are searched for libraries and 7396 and ``STAGING_DIR_NATIVE`` are searched for libraries and
6588 headers using, for example, GCC's ``-isystem`` option. 7397 headers using, for example, GCC's ``-isystem`` option.
6589 7398
6590 Thus, the emphasis is that the ``STAGING_DIR*`` variables 7399 Thus, the emphasis is that the ``STAGING_DIR*`` variables
6591 should be viewed as input variables by tasks such as 7400 should be viewed as input variables by tasks such as
6592 :ref:`ref-tasks-configure`, 7401 :ref:`ref-tasks-configure`,
@@ -6595,17 +7404,17 @@ system and gives an overview of their function and contents.
6595 root correspond to ``STAGING_DIR_HOST`` makes conceptual sense 7404 root correspond to ``STAGING_DIR_HOST`` makes conceptual sense
6596 for ``-native`` recipes, as they make use of host headers and 7405 for ``-native`` recipes, as they make use of host headers and
6597 libraries. 7406 libraries.
6598 7407
6599 STAGING_DIR_NATIVE 7408 STAGING_DIR_NATIVE
6600 Specifies the path to the sysroot directory used when building 7409 Specifies the path to the sysroot directory used when building
6601 components that run on the build host itself. 7410 components that run on the build host itself.
6602 7411
6603 STAGING_DIR_TARGET 7412 STAGING_DIR_TARGET
6604 Specifies the path to the sysroot used for the system for which the 7413 Specifies the path to the sysroot used for the system for which the
6605 component generates code. For components that do not generate code, 7414 component generates code. For components that do not generate code,
6606 which is the majority, ``STAGING_DIR_TARGET`` is set to match 7415 which is the majority, ``STAGING_DIR_TARGET`` is set to match
6607 :term:`STAGING_DIR_HOST`. 7416 :term:`STAGING_DIR_HOST`.
6608 7417
6609 Some recipes build binaries that can run on the target system but 7418 Some recipes build binaries that can run on the target system but
6610 those binaries in turn generate code for another different system 7419 those binaries in turn generate code for another different system
6611 (e.g. cross-canadian recipes). Using terminology from GNU, the 7420 (e.g. cross-canadian recipes). Using terminology from GNU, the
@@ -6615,171 +7424,203 @@ system and gives an overview of their function and contents.
6615 system. The ``STAGING_DIR_HOST`` variable points to the sysroot used 7424 system. The ``STAGING_DIR_HOST`` variable points to the sysroot used
6616 for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the 7425 for the "HOST" system, while ``STAGING_DIR_TARGET`` points to the
6617 sysroot used for the "TARGET" system. 7426 sysroot used for the "TARGET" system.
6618 7427
6619 STAGING_ETCDIR_NATIVE 7428 STAGING_ETCDIR_NATIVE
6620 Specifies the path to the ``/etc`` subdirectory of the sysroot 7429 Specifies the path to the ``/etc`` subdirectory of the sysroot
6621 directory for the build host. 7430 directory for the build host.
6622 7431
6623 STAGING_EXECPREFIXDIR 7432 STAGING_EXECPREFIXDIR
6624 Specifies the path to the ``/usr`` subdirectory of the sysroot 7433 Specifies the path to the ``/usr`` subdirectory of the sysroot
6625 directory for the target for which the current recipe is being built 7434 directory for the target for which the current recipe is being built
6626 (:term:`STAGING_DIR_HOST`). 7435 (:term:`STAGING_DIR_HOST`).
6627 7436
6628 STAGING_INCDIR 7437 STAGING_INCDIR
6629 Specifies the path to the ``/usr/include`` subdirectory of the 7438 Specifies the path to the ``/usr/include`` subdirectory of the
6630 sysroot directory for the target for which the current recipe being 7439 sysroot directory for the target for which the current recipe being
6631 built (:term:`STAGING_DIR_HOST`). 7440 built (:term:`STAGING_DIR_HOST`).
6632 7441
6633 STAGING_INCDIR_NATIVE 7442 STAGING_INCDIR_NATIVE
6634 Specifies the path to the ``/usr/include`` subdirectory of the 7443 Specifies the path to the ``/usr/include`` subdirectory of the
6635 sysroot directory for the build host. 7444 sysroot directory for the build host.
6636 7445
6637 STAGING_KERNEL_BUILDDIR 7446 STAGING_KERNEL_BUILDDIR
6638 Points to the directory containing the kernel build artifacts. 7447 Points to the directory containing the kernel build artifacts.
6639 Recipes building software that needs to access kernel build artifacts 7448 Recipes building software that needs to access kernel build artifacts
6640 (e.g. ``systemtap-uprobes``) can look in the directory specified with 7449 (e.g. ``systemtap-uprobes``) can look in the directory specified with
6641 the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts 7450 the ``STAGING_KERNEL_BUILDDIR`` variable to find these artifacts
6642 after the kernel has been built. 7451 after the kernel has been built.
6643 7452
6644 STAGING_KERNEL_DIR 7453 STAGING_KERNEL_DIR
6645 The directory with kernel headers that are required to build 7454 The directory with kernel headers that are required to build
6646 out-of-tree modules. 7455 out-of-tree modules.
6647 7456
6648 STAGING_LIBDIR 7457 STAGING_LIBDIR
6649 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 7458 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
6650 directory for the target for which the current recipe is being built 7459 directory for the target for which the current recipe is being built
6651 (:term:`STAGING_DIR_HOST`). 7460 (:term:`STAGING_DIR_HOST`).
6652 7461
6653 STAGING_LIBDIR_NATIVE 7462 STAGING_LIBDIR_NATIVE
6654 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot 7463 Specifies the path to the ``/usr/lib`` subdirectory of the sysroot
6655 directory for the build host. 7464 directory for the build host.
6656 7465
6657 STAMP 7466 STAMP
6658 Specifies the base path used to create recipe stamp files. The path 7467 Specifies the base path used to create recipe stamp files. The path
6659 to an actual stamp file is constructed by evaluating this string and 7468 to an actual stamp file is constructed by evaluating this string and
6660 then appending additional information. Currently, the default 7469 then appending additional information. Currently, the default
6661 assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf`` 7470 assignment for ``STAMP`` as set in the ``meta/conf/bitbake.conf``
6662 file is: STAMP = 7471 file is:
6663 "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}" 7472 ::
6664 7473
7474 STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
7475
6665 For information on how BitBake uses stamp files to determine if a 7476 For information on how BitBake uses stamp files to determine if a
6666 task should be rerun, see the "`Stamp Files and the Rerunning of 7477 task should be rerun, see the
6667 Tasks <&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks>`__" 7478 ":ref:`overview-manual/overview-manual-concepts:stamp files and the rerunning of tasks`"
6668 section in the Yocto Project Overview and Concepts Manual. 7479 section in the Yocto Project Overview and Concepts Manual.
6669 7480
6670 See :term:`STAMPS_DIR`, 7481 See :term:`STAMPS_DIR`,
6671 :term:`MULTIMACH_TARGET_SYS`, 7482 :term:`MULTIMACH_TARGET_SYS`,
6672 :term:`PN`, :term:`EXTENDPE`, 7483 :term:`PN`, :term:`EXTENDPE`,
6673 :term:`PV`, and :term:`PR` for related variable 7484 :term:`PV`, and :term:`PR` for related variable
6674 information. 7485 information.
6675 7486
6676 STAMPS_DIR 7487 STAMPS_DIR
6677 Specifies the base directory in which the OpenEmbedded build system 7488 Specifies the base directory in which the OpenEmbedded build system
6678 places stamps. The default directory is ``${TMPDIR}/stamps``. 7489 places stamps. The default directory is ``${TMPDIR}/stamps``.
6679 7490
6680 STRIP 7491 STRIP
6681 The minimal command and arguments to run ``strip``, which is used to 7492 The minimal command and arguments to run ``strip``, which is used to
6682 strip symbols. 7493 strip symbols.
6683 7494
6684 SUMMARY 7495 SUMMARY
6685 The short (72 characters or less) summary of the binary package for 7496 The short (72 characters or less) summary of the binary package for
6686 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default, 7497 packaging systems such as ``opkg``, ``rpm``, or ``dpkg``. By default,
6687 ``SUMMARY`` is used to define the 7498 ``SUMMARY`` is used to define the
6688 :term:`DESCRIPTION` variable if ``DESCRIPTION`` is 7499 :term:`DESCRIPTION` variable if ``DESCRIPTION`` is
6689 not set in the recipe. 7500 not set in the recipe.
6690 7501
6691 SVNDIR 7502 SVNDIR
6692 The directory in which files checked out of a Subversion system are 7503 The directory in which files checked out of a Subversion system are
6693 stored. 7504 stored.
6694 7505
6695 SYSLINUX_DEFAULT_CONSOLE 7506 SYSLINUX_DEFAULT_CONSOLE
6696 Specifies the kernel boot default console. If you want to use a 7507 Specifies the kernel boot default console. If you want to use a
6697 console other than the default, set this variable in your recipe as 7508 console other than the default, set this variable in your recipe as
6698 follows where "X" is the console number you want to use: 7509 follows where "X" is the console number you want to use:
6699 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX" 7510 ::
6700 7511
7512 SYSLINUX_DEFAULT_CONSOLE = "console=ttyX"
7513
6701 The :ref:`syslinux <ref-classes-syslinux>` class initially sets 7514 The :ref:`syslinux <ref-classes-syslinux>` class initially sets
6702 this variable to null but then checks for a value later. 7515 this variable to null but then checks for a value later.
6703 7516
6704 SYSLINUX_OPTS 7517 SYSLINUX_OPTS
6705 Lists additional options to add to the syslinux file. You need to set 7518 Lists additional options to add to the syslinux file. You need to set
6706 this variable in your recipe. If you want to list multiple options, 7519 this variable in your recipe. If you want to list multiple options,
6707 separate the options with a semicolon character (``;``). 7520 separate the options with a semicolon character (``;``).
6708 7521
6709 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable 7522 The :ref:`syslinux <ref-classes-syslinux>` class uses this variable
6710 to create a set of options. 7523 to create a set of options.
6711 7524
6712 SYSLINUX_SERIAL 7525 SYSLINUX_SERIAL
6713 Specifies the alternate serial port or turns it off. To turn off 7526 Specifies the alternate serial port or turns it off. To turn off
6714 serial, set this variable to an empty string in your recipe. The 7527 serial, set this variable to an empty string in your recipe. The
6715 variable's default value is set in the 7528 variable's default value is set in the
6716 :ref:`syslinux <ref-classes-syslinux>` class as follows: 7529 :ref:`syslinux <ref-classes-syslinux>` class as follows:
6717 SYSLINUX_SERIAL ?= "0 115200" 7530 ::
6718 7531
7532 SYSLINUX_SERIAL ?= "0 115200"
7533
6719 The class checks for and uses the variable as needed. 7534 The class checks for and uses the variable as needed.
6720 7535
6721 SYSLINUX_SPLASH 7536 SYSLINUX_SPLASH
6722 An ``.LSS`` file used as the background for the VGA boot menu when 7537 An ``.LSS`` file used as the background for the VGA boot menu when
6723 you use the boot menu. You need to set this variable in your recipe. 7538 you use the boot menu. You need to set this variable in your recipe.
6724 7539
6725 The :ref:`syslinux <ref-classes-syslinux>` class checks for this 7540 The :ref:`syslinux <ref-classes-syslinux>` class checks for this
6726 variable and if found, the OpenEmbedded build system installs the 7541 variable and if found, the OpenEmbedded build system installs the
6727 splash screen. 7542 splash screen.
6728 7543
6729 SYSLINUX_SERIAL_TTY 7544 SYSLINUX_SERIAL_TTY
6730 Specifies the alternate console=tty... kernel boot argument. The 7545 Specifies the alternate console=tty... kernel boot argument. The
6731 variable's default value is set in the 7546 variable's default value is set in the
6732 :ref:`syslinux <ref-classes-syslinux>` class as follows: 7547 :ref:`syslinux <ref-classes-syslinux>` class as follows:
6733 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200" 7548 ::
6734 7549
7550 SYSLINUX_SERIAL_TTY ?= "console=ttyS0,115200"
7551
6735 The class checks for and uses the variable as needed. 7552 The class checks for and uses the variable as needed.
6736 7553
6737 SYSROOT_DESTDIR 7554 SYSROOT_DESTDIR
6738 Points to the temporary directory under the work directory (default 7555 Points to the temporary directory under the work directory (default
6739 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``") 7556 "``${``\ :term:`WORKDIR`\ ``}/sysroot-destdir``")
6740 where the files populated into the sysroot are assembled during the 7557 where the files populated into the sysroot are assembled during the
6741 :ref:`ref-tasks-populate_sysroot` task. 7558 :ref:`ref-tasks-populate_sysroot` task.
6742 7559
6743 SYSROOT_DIRS 7560 SYSROOT_DIRS
6744 Directories that are staged into the sysroot by the 7561 Directories that are staged into the sysroot by the
6745 :ref:`ref-tasks-populate_sysroot` task. By 7562 :ref:`ref-tasks-populate_sysroot` task. By
6746 default, the following directories are staged: SYSROOT_DIRS = " \\ 7563 default, the following directories are staged:
6747 ${includedir} \\ ${libdir} \\ ${base_libdir} \\ 7564 ::
6748 ${nonarch_base_libdir} \\ ${datadir} \\ " 7565
6749 7566 SYSROOT_DIRS = " \
7567 ${includedir} \
7568 ${libdir} \
7569 ${base_libdir} \
7570 ${nonarch_base_libdir} \
7571 ${datadir} \
7572 "
7573
6750 SYSROOT_DIRS_BLACKLIST 7574 SYSROOT_DIRS_BLACKLIST
6751 Directories that are not staged into the sysroot by the 7575 Directories that are not staged into the sysroot by the
6752 :ref:`ref-tasks-populate_sysroot` task. You 7576 :ref:`ref-tasks-populate_sysroot` task. You
6753 can use this variable to exclude certain subdirectories of 7577 can use this variable to exclude certain subdirectories of
6754 directories listed in :term:`SYSROOT_DIRS` from 7578 directories listed in :term:`SYSROOT_DIRS` from
6755 staging. By default, the following directories are not staged: 7579 staging. By default, the following directories are not staged:
6756 SYSROOT_DIRS_BLACKLIST = " \\ ${mandir} \\ ${docdir} \\ ${infodir} \\ 7580 ::
6757 ${datadir}/locale \\ ${datadir}/applications \\ ${datadir}/fonts \\ 7581
6758 ${datadir}/pixmaps \\ " 7582 SYSROOT_DIRS_BLACKLIST = " \
6759 7583 ${mandir} \
7584 ${docdir} \
7585 ${infodir} \
7586 ${datadir}/locale \
7587 ${datadir}/applications \
7588 ${datadir}/fonts \
7589 ${datadir}/pixmaps \
7590 "
7591
6760 SYSROOT_DIRS_NATIVE 7592 SYSROOT_DIRS_NATIVE
6761 Extra directories staged into the sysroot by the 7593 Extra directories staged into the sysroot by the
6762 :ref:`ref-tasks-populate_sysroot` task for 7594 :ref:`ref-tasks-populate_sysroot` task for
6763 ``-native`` recipes, in addition to those specified in 7595 ``-native`` recipes, in addition to those specified in
6764 :term:`SYSROOT_DIRS`. By default, the following 7596 :term:`SYSROOT_DIRS`. By default, the following
6765 extra directories are staged: SYSROOT_DIRS_NATIVE = " \\ ${bindir} \\ 7597 extra directories are staged:
6766 ${sbindir} \\ ${base_bindir} \\ ${base_sbindir} \\ ${libexecdir} \\ 7598 ::
6767 ${sysconfdir} \\ ${localstatedir} \\ " 7599
6768 7600 SYSROOT_DIRS_NATIVE = " \
7601 ${bindir} \
7602 ${sbindir} \
7603 ${base_bindir} \
7604 ${base_sbindir} \
7605 ${libexecdir} \
7606 ${sysconfdir} \
7607 ${localstatedir} \
7608 "
7609
6769 .. note:: 7610 .. note::
6770 7611
6771 Programs built by 7612 Programs built by
6772 -native 7613 -native
6773 recipes run directly from the sysroot ( 7614 recipes run directly from the sysroot (
6774 STAGING_DIR_NATIVE 7615 STAGING_DIR_NATIVE
6775 ), which is why additional directories containing program 7616 ), which is why additional directories containing program
6776 executables and supporting files need to be staged. 7617 executables and supporting files need to be staged.
6777 7618
6778 SYSROOT_PREPROCESS_FUNCS 7619 SYSROOT_PREPROCESS_FUNCS
6779 A list of functions to execute after files are staged into the 7620 A list of functions to execute after files are staged into the
6780 sysroot. These functions are usually used to apply additional 7621 sysroot. These functions are usually used to apply additional
6781 processing on the staged files, or to stage additional files. 7622 processing on the staged files, or to stage additional files.
6782 7623
6783 SYSTEMD_AUTO_ENABLE 7624 SYSTEMD_AUTO_ENABLE
6784 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 7625 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6785 this variable specifies whether the specified service in 7626 this variable specifies whether the specified service in
@@ -6787,111 +7628,138 @@ system and gives an overview of their function and contents.
6787 automatically or not. By default, the service is enabled to 7628 automatically or not. By default, the service is enabled to
6788 automatically start at boot time. The default setting is in the 7629 automatically start at boot time. The default setting is in the
6789 :ref:`systemd <ref-classes-systemd>` class as follows: 7630 :ref:`systemd <ref-classes-systemd>` class as follows:
6790 SYSTEMD_AUTO_ENABLE ??= "enable" 7631 ::
6791 7632
7633 SYSTEMD_AUTO_ENABLE ??= "enable"
7634
6792 You can disable the service by setting the variable to "disable". 7635 You can disable the service by setting the variable to "disable".
6793 7636
6794 SYSTEMD_BOOT_CFG 7637 SYSTEMD_BOOT_CFG
6795 When :term:`EFI_PROVIDER` is set to 7638 When :term:`EFI_PROVIDER` is set to
6796 "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the 7639 "systemd-boot", the ``SYSTEMD_BOOT_CFG`` variable specifies the
6797 configuration file that should be used. By default, the 7640 configuration file that should be used. By default, the
6798 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 7641 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6799 ``SYSTEMD_BOOT_CFG`` as follows: SYSTEMD_BOOT_CFG ?= 7642 ``SYSTEMD_BOOT_CFG`` as follows:
6800 "${:term:`S`}/loader.conf" 7643 ::
6801 7644
7645 SYSTEMD_BOOT_CFG ?= "${:term:`S`}/loader.conf"
7646
6802 For information on Systemd-boot, see the `Systemd-boot 7647 For information on Systemd-boot, see the `Systemd-boot
6803 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 7648 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6804 7649
6805 SYSTEMD_BOOT_ENTRIES 7650 SYSTEMD_BOOT_ENTRIES
6806 When :term:`EFI_PROVIDER` is set to 7651 When :term:`EFI_PROVIDER` is set to
6807 "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a 7652 "systemd-boot", the ``SYSTEMD_BOOT_ENTRIES`` variable specifies a
6808 list of entry files (``*.conf``) to install that contain one boot 7653 list of entry files (``*.conf``) to install that contain one boot
6809 entry per file. By default, the 7654 entry per file. By default, the
6810 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 7655 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6811 ``SYSTEMD_BOOT_ENTRIES`` as follows: SYSTEMD_BOOT_ENTRIES ?= "" 7656 ``SYSTEMD_BOOT_ENTRIES`` as follows:
6812 7657 ::
7658
7659 SYSTEMD_BOOT_ENTRIES ?= ""
7660
6813 For information on Systemd-boot, see the `Systemd-boot 7661 For information on Systemd-boot, see the `Systemd-boot
6814 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 7662 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6815 7663
6816 SYSTEMD_BOOT_TIMEOUT 7664 SYSTEMD_BOOT_TIMEOUT
6817 When :term:`EFI_PROVIDER` is set to 7665 When :term:`EFI_PROVIDER` is set to
6818 "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the 7666 "systemd-boot", the ``SYSTEMD_BOOT_TIMEOUT`` variable specifies the
6819 boot menu timeout in seconds. By default, the 7667 boot menu timeout in seconds. By default, the
6820 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the 7668 :ref:`systemd-boot <ref-classes-systemd-boot>` class sets the
6821 ``SYSTEMD_BOOT_TIMEOUT`` as follows: SYSTEMD_BOOT_TIMEOUT ?= "10" 7669 ``SYSTEMD_BOOT_TIMEOUT`` as follows:
6822 7670 ::
7671
7672 SYSTEMD_BOOT_TIMEOUT ?= "10"
7673
6823 For information on Systemd-boot, see the `Systemd-boot 7674 For information on Systemd-boot, see the `Systemd-boot
6824 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__. 7675 documentation <http://www.freedesktop.org/wiki/Software/systemd/systemd-boot/>`__.
6825 7676
6826 SYSTEMD_PACKAGES 7677 SYSTEMD_PACKAGES
6827 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 7678 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6828 this variable locates the systemd unit files when they are not found 7679 this variable locates the systemd unit files when they are not found
6829 in the main recipe's package. By default, the ``SYSTEMD_PACKAGES`` 7680 in the main recipe's package. By default, the ``SYSTEMD_PACKAGES``
6830 variable is set such that the systemd unit files are assumed to 7681 variable is set such that the systemd unit files are assumed to
6831 reside in the recipes main package: SYSTEMD_PACKAGES ?= "${PN}" 7682 reside in the recipes main package:
6832 7683 ::
7684
7685 SYSTEMD_PACKAGES ?= "${PN}"
7686
6833 If these unit files are not in this recipe's main package, you need 7687 If these unit files are not in this recipe's main package, you need
6834 to use ``SYSTEMD_PACKAGES`` to list the package or packages in which 7688 to use ``SYSTEMD_PACKAGES`` to list the package or packages in which
6835 the build system can find the systemd unit files. 7689 the build system can find the systemd unit files.
6836 7690
6837 SYSTEMD_SERVICE 7691 SYSTEMD_SERVICE
6838 When inheriting the :ref:`systemd <ref-classes-systemd>` class, 7692 When inheriting the :ref:`systemd <ref-classes-systemd>` class,
6839 this variable specifies the systemd service name for a package. 7693 this variable specifies the systemd service name for a package.
6840 7694
6841 When you specify this file in your recipe, use a package name 7695 When you specify this file in your recipe, use a package name
6842 override to indicate the package to which the value applies. Here is 7696 override to indicate the package to which the value applies. Here is
6843 an example from the connman recipe: SYSTEMD_SERVICE_${PN} = 7697 an example from the connman recipe:
6844 "connman.service" 7698 ::
6845 7699
7700 SYSTEMD_SERVICE_${PN} = "connman.service"
7701
6846 SYSVINIT_ENABLED_GETTYS 7702 SYSVINIT_ENABLED_GETTYS
6847 When using 7703 When using
6848 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__, 7704 :ref:`SysVinit <dev-manual/dev-manual-common-tasks:enabling system services>`,
6849 specifies a space-separated list of the virtual terminals that should 7705 specifies a space-separated list of the virtual terminals that should
6850 run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ 7706 run a `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__
6851 (allowing login), assuming :term:`USE_VT` is not set to 7707 (allowing login), assuming :term:`USE_VT` is not set to
6852 "0". 7708 "0".
6853 7709
6854 The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only 7710 The default value for ``SYSVINIT_ENABLED_GETTYS`` is "1" (i.e. only
6855 run a getty on the first virtual terminal). 7711 run a getty on the first virtual terminal).
6856 7712
6857 T 7713 T
6858 This variable points to a directory were BitBake places temporary 7714 This variable points to a directory were BitBake places temporary
6859 files, which consist mostly of task logs and scripts, when building a 7715 files, which consist mostly of task logs and scripts, when building a
6860 particular recipe. The variable is typically set as follows: T = 7716 particular recipe. The variable is typically set as follows:
6861 "${WORKDIR}/temp" 7717 ::
6862 7718
7719 T = "${WORKDIR}/temp"
7720
6863 The :term:`WORKDIR` is the directory into which 7721 The :term:`WORKDIR` is the directory into which
6864 BitBake unpacks and builds the recipe. The default ``bitbake.conf`` 7722 BitBake unpacks and builds the recipe. The default ``bitbake.conf``
6865 file sets this variable. 7723 file sets this variable.
6866 7724
6867 The ``T`` variable is not to be confused with the 7725 The ``T`` variable is not to be confused with the
6868 :term:`TMPDIR` variable, which points to the root of 7726 :term:`TMPDIR` variable, which points to the root of
6869 the directory tree where BitBake places the output of an entire 7727 the directory tree where BitBake places the output of an entire
6870 build. 7728 build.
6871 7729
6872 TARGET_ARCH 7730 TARGET_ARCH
6873 The target machine's architecture. The OpenEmbedded build system 7731 The target machine's architecture. The OpenEmbedded build system
6874 supports many architectures. Here is an example list of architectures 7732 supports many architectures. Here is an example list of architectures
6875 supported. This list is by no means complete as the architecture is 7733 supported. This list is by no means complete as the architecture is
6876 configurable: arm i586 x86_64 powerpc powerpc64 mips mipsel 7734 configurable:
6877 7735
7736 - arm
7737 - i586
7738 - x86_64
7739 - powerpc
7740 - powerpc64
7741 - mips
7742 - mipsel
7743
6878 For additional information on machine architectures, see the 7744 For additional information on machine architectures, see the
6879 :term:`TUNE_ARCH` variable. 7745 :term:`TUNE_ARCH` variable.
6880 7746
6881 TARGET_AS_ARCH 7747 TARGET_AS_ARCH
6882 Specifies architecture-specific assembler flags for the target 7748 Specifies architecture-specific assembler flags for the target
6883 system. ``TARGET_AS_ARCH`` is initialized from 7749 system. ``TARGET_AS_ARCH`` is initialized from
6884 :term:`TUNE_ASARGS` by default in the BitBake 7750 :term:`TUNE_ASARGS` by default in the BitBake
6885 configuration file (``meta/conf/bitbake.conf``): TARGET_AS_ARCH = 7751 configuration file (``meta/conf/bitbake.conf``):
6886 "${TUNE_ASARGS}" 7752 ::
6887 7753
7754 TARGET_AS_ARCH = "${TUNE_ASARGS}"
7755
6888 TARGET_CC_ARCH 7756 TARGET_CC_ARCH
6889 Specifies architecture-specific C compiler flags for the target 7757 Specifies architecture-specific C compiler flags for the target
6890 system. ``TARGET_CC_ARCH`` is initialized from 7758 system. ``TARGET_CC_ARCH`` is initialized from
6891 :term:`TUNE_CCARGS` by default. 7759 :term:`TUNE_CCARGS` by default.
6892 7760
6893 .. note:: 7761 .. note::
6894 7762
6895 It is a common workaround to append 7763 It is a common workaround to append
6896 LDFLAGS 7764 LDFLAGS
6897 to 7765 to
@@ -6900,7 +7768,7 @@ system and gives an overview of their function and contents.
6900 otherwise respect the exported 7768 otherwise respect the exported
6901 LDFLAGS 7769 LDFLAGS
6902 variable. 7770 variable.
6903 7771
6904 TARGET_CC_KERNEL_ARCH 7772 TARGET_CC_KERNEL_ARCH
6905 This is a specific kernel compiler flag for a CPU or Application 7773 This is a specific kernel compiler flag for a CPU or Application
6906 Binary Interface (ABI) tune. The flag is used rarely and only for 7774 Binary Interface (ABI) tune. The flag is used rarely and only for
@@ -6910,118 +7778,118 @@ system and gives an overview of their function and contents.
6910 different configuration. See the 7778 different configuration. See the
6911 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the 7779 ``meta/conf/machine/include/arm/feature-arm-thumb.inc`` file in the
6912 :term:`Source Directory` for an example. 7780 :term:`Source Directory` for an example.
6913 7781
6914 TARGET_CFLAGS 7782 TARGET_CFLAGS
6915 Specifies the flags to pass to the C compiler when building for the 7783 Specifies the flags to pass to the C compiler when building for the
6916 target. When building in the target context, 7784 target. When building in the target context,
6917 :term:`CFLAGS` is set to the value of this variable by 7785 :term:`CFLAGS` is set to the value of this variable by
6918 default. 7786 default.
6919 7787
6920 Additionally, the SDK's environment setup script sets the ``CFLAGS`` 7788 Additionally, the SDK's environment setup script sets the ``CFLAGS``
6921 variable in the environment to the ``TARGET_CFLAGS`` value so that 7789 variable in the environment to the ``TARGET_CFLAGS`` value so that
6922 executables built using the SDK also have the flags applied. 7790 executables built using the SDK also have the flags applied.
6923 7791
6924 TARGET_CPPFLAGS 7792 TARGET_CPPFLAGS
6925 Specifies the flags to pass to the C pre-processor (i.e. to both the 7793 Specifies the flags to pass to the C pre-processor (i.e. to both the
6926 C and the C++ compilers) when building for the target. When building 7794 C and the C++ compilers) when building for the target. When building
6927 in the target context, :term:`CPPFLAGS` is set to the 7795 in the target context, :term:`CPPFLAGS` is set to the
6928 value of this variable by default. 7796 value of this variable by default.
6929 7797
6930 Additionally, the SDK's environment setup script sets the 7798 Additionally, the SDK's environment setup script sets the
6931 ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS`` 7799 ``CPPFLAGS`` variable in the environment to the ``TARGET_CPPFLAGS``
6932 value so that executables built using the SDK also have the flags 7800 value so that executables built using the SDK also have the flags
6933 applied. 7801 applied.
6934 7802
6935 TARGET_CXXFLAGS 7803 TARGET_CXXFLAGS
6936 Specifies the flags to pass to the C++ compiler when building for the 7804 Specifies the flags to pass to the C++ compiler when building for the
6937 target. When building in the target context, 7805 target. When building in the target context,
6938 :term:`CXXFLAGS` is set to the value of this variable 7806 :term:`CXXFLAGS` is set to the value of this variable
6939 by default. 7807 by default.
6940 7808
6941 Additionally, the SDK's environment setup script sets the 7809 Additionally, the SDK's environment setup script sets the
6942 ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS`` 7810 ``CXXFLAGS`` variable in the environment to the ``TARGET_CXXFLAGS``
6943 value so that executables built using the SDK also have the flags 7811 value so that executables built using the SDK also have the flags
6944 applied. 7812 applied.
6945 7813
6946 TARGET_FPU 7814 TARGET_FPU
6947 Specifies the method for handling FPU code. For FPU-less targets, 7815 Specifies the method for handling FPU code. For FPU-less targets,
6948 which include most ARM CPUs, the variable must be set to "soft". If 7816 which include most ARM CPUs, the variable must be set to "soft". If
6949 not, the kernel emulation gets used, which results in a performance 7817 not, the kernel emulation gets used, which results in a performance
6950 penalty. 7818 penalty.
6951 7819
6952 TARGET_LD_ARCH 7820 TARGET_LD_ARCH
6953 Specifies architecture-specific linker flags for the target system. 7821 Specifies architecture-specific linker flags for the target system.
6954 ``TARGET_LD_ARCH`` is initialized from 7822 ``TARGET_LD_ARCH`` is initialized from
6955 :term:`TUNE_LDARGS` by default in the BitBake 7823 :term:`TUNE_LDARGS` by default in the BitBake
6956 configuration file (``meta/conf/bitbake.conf``): TARGET_LD_ARCH = 7824 configuration file (``meta/conf/bitbake.conf``):
6957 "${TUNE_LDARGS}" 7825 ::
6958 7826
7827 TARGET_LD_ARCH = "${TUNE_LDARGS}"
7828
6959 TARGET_LDFLAGS 7829 TARGET_LDFLAGS
6960 Specifies the flags to pass to the linker when building for the 7830 Specifies the flags to pass to the linker when building for the
6961 target. When building in the target context, 7831 target. When building in the target context,
6962 :term:`LDFLAGS` is set to the value of this variable 7832 :term:`LDFLAGS` is set to the value of this variable
6963 by default. 7833 by default.
6964 7834
6965 Additionally, the SDK's environment setup script sets the 7835 Additionally, the SDK's environment setup script sets the
6966 :term:`LDFLAGS` variable in the environment to the 7836 :term:`LDFLAGS` variable in the environment to the
6967 ``TARGET_LDFLAGS`` value so that executables built using the SDK also 7837 ``TARGET_LDFLAGS`` value so that executables built using the SDK also
6968 have the flags applied. 7838 have the flags applied.
6969 7839
6970 TARGET_OS 7840 TARGET_OS
6971 Specifies the target's operating system. The variable can be set to 7841 Specifies the target's operating system. The variable can be set to
6972 "linux" for glibc-based systems (GNU C Library) and to "linux-musl" 7842 "linux" for glibc-based systems (GNU C Library) and to "linux-musl"
6973 for musl libc. For ARM/EABI targets, "linux-gnueabi" and 7843 for musl libc. For ARM/EABI targets, "linux-gnueabi" and
6974 "linux-musleabi" possible values exist. 7844 "linux-musleabi" possible values exist.
6975 7845
6976 TARGET_PREFIX 7846 TARGET_PREFIX
6977 Specifies the prefix used for the toolchain binary target tools. 7847 Specifies the prefix used for the toolchain binary target tools.
6978 7848
6979 Depending on the type of recipe and the build target, 7849 Depending on the type of recipe and the build target,
6980 ``TARGET_PREFIX`` is set as follows: 7850 ``TARGET_PREFIX`` is set as follows:
6981 7851
6982 - For recipes building for the target machine, the value is 7852 - For recipes building for the target machine, the value is
6983 "${:term:`TARGET_SYS`}-". 7853 "${:term:`TARGET_SYS`}-".
6984 7854
6985 - For native recipes, the build system sets the variable to the 7855 - For native recipes, the build system sets the variable to the
6986 value of ``BUILD_PREFIX``. 7856 value of ``BUILD_PREFIX``.
6987 7857
6988 - For native SDK recipes (``nativesdk``), the build system sets the 7858 - For native SDK recipes (``nativesdk``), the build system sets the
6989 variable to the value of ``SDK_PREFIX``. 7859 variable to the value of ``SDK_PREFIX``.
6990 7860
6991 TARGET_SYS 7861 TARGET_SYS
6992 Specifies the system, including the architecture and the operating 7862 Specifies the system, including the architecture and the operating
6993 system, for which the build is occurring in the context of the 7863 system, for which the build is occurring in the context of the
6994 current recipe. 7864 current recipe.
6995 7865
6996 The OpenEmbedded build system automatically sets this variable based 7866 The OpenEmbedded build system automatically sets this variable based
6997 on :term:`TARGET_ARCH`, 7867 on :term:`TARGET_ARCH`,
6998 :term:`TARGET_VENDOR`, and 7868 :term:`TARGET_VENDOR`, and
6999 :term:`TARGET_OS` variables. 7869 :term:`TARGET_OS` variables.
7000 7870
7001 .. note:: 7871 .. note::
7002 7872
7003 You do not need to set the 7873 You do not need to set the TARGET_SYS variable yourself.
7004 TARGET_SYS 7874
7005 variable yourself.
7006
7007 Consider these two examples: 7875 Consider these two examples:
7008 7876
7009 - Given a native recipe on a 32-bit, x86 machine running Linux, the 7877 - Given a native recipe on a 32-bit, x86 machine running Linux, the
7010 value is "i686-linux". 7878 value is "i686-linux".
7011 7879
7012 - Given a recipe being built for a little-endian, MIPS target 7880 - Given a recipe being built for a little-endian, MIPS target
7013 running Linux, the value might be "mipsel-linux". 7881 running Linux, the value might be "mipsel-linux".
7014 7882
7015 TARGET_VENDOR 7883 TARGET_VENDOR
7016 Specifies the name of the target vendor. 7884 Specifies the name of the target vendor.
7017 7885
7018 TCLIBC 7886 TCLIBC
7019 Specifies the GNU standard C library (``libc``) variant to use during 7887 Specifies the GNU standard C library (``libc``) variant to use during
7020 the build process. This variable replaces ``POKYLIBC``, which is no 7888 the build process. This variable replaces ``POKYLIBC``, which is no
7021 longer supported. 7889 longer supported.
7022 7890
7023 You can select "glibc", "musl", "newlib", or "baremetal" 7891 You can select "glibc", "musl", "newlib", or "baremetal"
7024 7892
7025 TCLIBCAPPEND 7893 TCLIBCAPPEND
7026 Specifies a suffix to be appended onto the 7894 Specifies a suffix to be appended onto the
7027 :term:`TMPDIR` value. The suffix identifies the 7895 :term:`TMPDIR` value. The suffix identifies the
@@ -7029,13 +7897,13 @@ system and gives an overview of their function and contents.
7029 variants with the same :term:`Build Directory`, this 7897 variants with the same :term:`Build Directory`, this
7030 mechanism ensures that output for different ``libc`` variants is kept 7898 mechanism ensures that output for different ``libc`` variants is kept
7031 separate to avoid potential conflicts. 7899 separate to avoid potential conflicts.
7032 7900
7033 In the ``defaultsetup.conf`` file, the default value of 7901 In the ``defaultsetup.conf`` file, the default value of
7034 ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky, 7902 ``TCLIBCAPPEND`` is "-${TCLIBC}". However, distros such as poky,
7035 which normally only support one ``libc`` variant, set 7903 which normally only support one ``libc`` variant, set
7036 ``TCLIBCAPPEND`` to "" in their distro configuration file resulting 7904 ``TCLIBCAPPEND`` to "" in their distro configuration file resulting
7037 in no suffix being applied. 7905 in no suffix being applied.
7038 7906
7039 TCMODE 7907 TCMODE
7040 Specifies the toolchain selector. ``TCMODE`` controls the 7908 Specifies the toolchain selector. ``TCMODE`` controls the
7041 characteristics of the generated packages and images by telling the 7909 characteristics of the generated packages and images by telling the
@@ -7043,9 +7911,9 @@ system and gives an overview of their function and contents.
7043 the OpenEmbedded build system builds its own internal toolchain. The 7911 the OpenEmbedded build system builds its own internal toolchain. The
7044 variable's default value is "default", which uses that internal 7912 variable's default value is "default", which uses that internal
7045 toolchain. 7913 toolchain.
7046 7914
7047 .. note:: 7915 .. note::
7048 7916
7049 If 7917 If
7050 TCMODE 7918 TCMODE
7051 is set to a value other than "default", then it is your 7919 is set to a value other than "default", then it is your
@@ -7058,53 +7926,53 @@ system and gives an overview of their function and contents.
7058 Downloads 7926 Downloads
7059 page on the Yocto Project website and click on the "RELEASE 7927 page on the Yocto Project website and click on the "RELEASE
7060 INFORMATION" link for the appropriate release. 7928 INFORMATION" link for the appropriate release.
7061 7929
7062 The ``TCMODE`` variable is similar to :term:`TCLIBC`, 7930 The ``TCMODE`` variable is similar to :term:`TCLIBC`,
7063 which controls the variant of the GNU standard C library (``libc``) 7931 which controls the variant of the GNU standard C library (``libc``)
7064 used during the build process: ``glibc`` or ``musl``. 7932 used during the build process: ``glibc`` or ``musl``.
7065 7933
7066 With additional layers, it is possible to use a pre-compiled external 7934 With additional layers, it is possible to use a pre-compiled external
7067 toolchain. One example is the Sourcery G++ Toolchain. The support for 7935 toolchain. One example is the Sourcery G++ Toolchain. The support for
7068 this toolchain resides in the separate Mentor Graphics 7936 this toolchain resides in the separate Mentor Graphics
7069 ``meta-sourcery`` layer at 7937 ``meta-sourcery`` layer at
7070 http://github.com/MentorEmbedded/meta-sourcery/. 7938 http://github.com/MentorEmbedded/meta-sourcery/.
7071 7939
7072 The layer's ``README`` file contains information on how to use the 7940 The layer's ``README`` file contains information on how to use the
7073 Sourcery G++ Toolchain as an external toolchain. In summary, you must 7941 Sourcery G++ Toolchain as an external toolchain. In summary, you must
7074 be sure to add the layer to your ``bblayers.conf`` file in front of 7942 be sure to add the layer to your ``bblayers.conf`` file in front of
7075 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable 7943 the ``meta`` layer and then set the ``EXTERNAL_TOOLCHAIN`` variable
7076 in your ``local.conf`` file to the location in which you installed 7944 in your ``local.conf`` file to the location in which you installed
7077 the toolchain. 7945 the toolchain.
7078 7946
7079 The fundamentals used for this example apply to any external 7947 The fundamentals used for this example apply to any external
7080 toolchain. You can use ``meta-sourcery`` as a template for adding 7948 toolchain. You can use ``meta-sourcery`` as a template for adding
7081 support for other external toolchains. 7949 support for other external toolchains.
7082 7950
7083 TEST_EXPORT_DIR 7951 TEST_EXPORT_DIR
7084 The location the OpenEmbedded build system uses to export tests when 7952 The location the OpenEmbedded build system uses to export tests when
7085 the :term:`TEST_EXPORT_ONLY` variable is set 7953 the :term:`TEST_EXPORT_ONLY` variable is set
7086 to "1". 7954 to "1".
7087 7955
7088 The ``TEST_EXPORT_DIR`` variable defaults to 7956 The ``TEST_EXPORT_DIR`` variable defaults to
7089 ``"${TMPDIR}/testimage/${PN}"``. 7957 ``"${TMPDIR}/testimage/${PN}"``.
7090 7958
7091 TEST_EXPORT_ONLY 7959 TEST_EXPORT_ONLY
7092 Specifies to export the tests only. Set this variable to "1" if you 7960 Specifies to export the tests only. Set this variable to "1" if you
7093 do not want to run the tests but you want them to be exported in a 7961 do not want to run the tests but you want them to be exported in a
7094 manner that you to run them outside of the build system. 7962 manner that you to run them outside of the build system.
7095 7963
7096 TEST_LOG_DIR 7964 TEST_LOG_DIR
7097 Holds the SSH log and the boot log for QEMU machines. The 7965 Holds the SSH log and the boot log for QEMU machines. The
7098 ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``. 7966 ``TEST_LOG_DIR`` variable defaults to ``"${WORKDIR}/testimage"``.
7099 7967
7100 .. note:: 7968 .. note::
7101 7969
7102 Actual test results reside in the task log ( 7970 Actual test results reside in the task log (
7103 log.do_testimage 7971 log.do_testimage
7104 ), which is in the 7972 ), which is in the
7105 ${WORKDIR}/temp/ 7973 ${WORKDIR}/temp/
7106 directory. 7974 directory.
7107 7975
7108 TEST_POWERCONTROL_CMD 7976 TEST_POWERCONTROL_CMD
7109 For automated hardware testing, specifies the command to use to 7977 For automated hardware testing, specifies the command to use to
7110 control the power of the target machine under test. Typically, this 7978 control the power of the target machine under test. Typically, this
@@ -7113,7 +7981,7 @@ system and gives an overview of their function and contents.
7113 command should expect to receive as the last argument "off", "on" or 7981 command should expect to receive as the last argument "off", "on" or
7114 "cycle" specifying to power off, on, or cycle (power off and then 7982 "cycle" specifying to power off, on, or cycle (power off and then
7115 power on) the device, respectively. 7983 power on) the device, respectively.
7116 7984
7117 TEST_POWERCONTROL_EXTRA_ARGS 7985 TEST_POWERCONTROL_EXTRA_ARGS
7118 For automated hardware testing, specifies additional arguments to 7986 For automated hardware testing, specifies additional arguments to
7119 pass through to the command specified in 7987 pass through to the command specified in
@@ -7121,30 +7989,31 @@ system and gives an overview of their function and contents.
7121 ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you 7989 ``TEST_POWERCONTROL_EXTRA_ARGS`` is optional. You can use it if you
7122 wish, for example, to separate the machine-specific and 7990 wish, for example, to separate the machine-specific and
7123 non-machine-specific parts of the arguments. 7991 non-machine-specific parts of the arguments.
7124 7992
7125 TEST_QEMUBOOT_TIMEOUT 7993 TEST_QEMUBOOT_TIMEOUT
7126 The time in seconds allowed for an image to boot before automated 7994 The time in seconds allowed for an image to boot before automated
7127 runtime tests begin to run against an image. The default timeout 7995 runtime tests begin to run against an image. The default timeout
7128 period to allow the boot process to reach the login prompt is 500 7996 period to allow the boot process to reach the login prompt is 500
7129 seconds. You can specify a different value in the ``local.conf`` 7997 seconds. You can specify a different value in the ``local.conf``
7130 file. 7998 file.
7131 7999
7132 For more information on testing images, see the "`Performing 8000 For more information on testing images, see the
7133 Automated Runtime 8001 ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
7134 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__"
7135 section in the Yocto Project Development Tasks Manual. 8002 section in the Yocto Project Development Tasks Manual.
7136 8003
7137 TEST_SERIALCONTROL_CMD 8004 TEST_SERIALCONTROL_CMD
7138 For automated hardware testing, specifies the command to use to 8005 For automated hardware testing, specifies the command to use to
7139 connect to the serial console of the target machine under test. This 8006 connect to the serial console of the target machine under test. This
7140 command simply needs to connect to the serial console and forward 8007 command simply needs to connect to the serial console and forward
7141 that connection to standard input and output as any normal terminal 8008 that connection to standard input and output as any normal terminal
7142 program does. 8009 program does.
7143 8010
7144 For example, to use the Picocom terminal program on serial device 8011 For example, to use the Picocom terminal program on serial device
7145 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows: 8012 ``/dev/ttyUSB0`` at 115200bps, you would set the variable as follows:
7146 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200" 8013 ::
7147 8014
8015 TEST_SERIALCONTROL_CMD = "picocom /dev/ttyUSB0 -b 115200"
8016
7148 TEST_SERIALCONTROL_EXTRA_ARGS 8017 TEST_SERIALCONTROL_EXTRA_ARGS
7149 For automated hardware testing, specifies additional arguments to 8018 For automated hardware testing, specifies additional arguments to
7150 pass through to the command specified in 8019 pass through to the command specified in
@@ -7152,238 +8021,273 @@ system and gives an overview of their function and contents.
7152 ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you 8021 ``TEST_SERIALCONTROL_EXTRA_ARGS`` is optional. You can use it if you
7153 wish, for example, to separate the machine-specific and 8022 wish, for example, to separate the machine-specific and
7154 non-machine-specific parts of the command. 8023 non-machine-specific parts of the command.
7155 8024
7156 TEST_SERVER_IP 8025 TEST_SERVER_IP
7157 The IP address of the build machine (host machine). This IP address 8026 The IP address of the build machine (host machine). This IP address
7158 is usually automatically detected. However, if detection fails, this 8027 is usually automatically detected. However, if detection fails, this
7159 variable needs to be set to the IP address of the build machine (i.e. 8028 variable needs to be set to the IP address of the build machine (i.e.
7160 where the build is taking place). 8029 where the build is taking place).
7161 8030
7162 .. note:: 8031 .. note::
7163 8032
7164 The 8033 The
7165 TEST_SERVER_IP 8034 TEST_SERVER_IP
7166 variable is only used for a small number of tests such as the 8035 variable is only used for a small number of tests such as the
7167 "dnf" test suite, which needs to download packages from 8036 "dnf" test suite, which needs to download packages from
7168 WORKDIR/oe-rootfs-repo 8037 WORKDIR/oe-rootfs-repo
7169 . 8038 .
7170 8039
7171 TEST_TARGET 8040 TEST_TARGET
7172 Specifies the target controller to use when running tests against a 8041 Specifies the target controller to use when running tests against a
7173 test image. The default controller to use is "qemu": TEST_TARGET = 8042 test image. The default controller to use is "qemu":
7174 "qemu" 8043 ::
7175 8044
8045 TEST_TARGET = "qemu"
8046
7176 A target controller is a class that defines how an image gets 8047 A target controller is a class that defines how an image gets
7177 deployed on a target and how a target is started. A layer can extend 8048 deployed on a target and how a target is started. A layer can extend
7178 the controllers by adding a module in the layer's 8049 the controllers by adding a module in the layer's
7179 ``/lib/oeqa/controllers`` directory and by inheriting the 8050 ``/lib/oeqa/controllers`` directory and by inheriting the
7180 ``BaseTarget`` class, which is an abstract class that cannot be used 8051 ``BaseTarget`` class, which is an abstract class that cannot be used
7181 as a value of ``TEST_TARGET``. 8052 as a value of ``TEST_TARGET``.
7182 8053
7183 You can provide the following arguments with ``TEST_TARGET``: 8054 You can provide the following arguments with ``TEST_TARGET``:
7184 8055
7185 - *"qemu":* Boots a QEMU image and runs the tests. See the 8056 - *"qemu":* Boots a QEMU image and runs the tests. See the
7186 "`Enabling Runtime Tests on 8057 ":ref:`qemu-image-enabling-tests`" section
7187 QEMU <&YOCTO_DOCS_DEV_URL;#qemu-image-enabling-tests>`__" section
7188 in the Yocto Project Development Tasks Manual for more 8058 in the Yocto Project Development Tasks Manual for more
7189 information. 8059 information.
7190 8060
7191 - *"simpleremote":* Runs the tests on target hardware that is 8061 - *"simpleremote":* Runs the tests on target hardware that is
7192 already up and running. The hardware can be on the network or it 8062 already up and running. The hardware can be on the network or it
7193 can be a device running an image on QEMU. You must also set 8063 can be a device running an image on QEMU. You must also set
7194 :term:`TEST_TARGET_IP` when you use 8064 :term:`TEST_TARGET_IP` when you use
7195 "simpleremote". 8065 "simpleremote".
7196 8066
7197 .. note:: 8067 .. note::
7198 8068
7199 This argument is defined in 8069 This argument is defined in
7200 meta/lib/oeqa/controllers/simpleremote.py 8070 meta/lib/oeqa/controllers/simpleremote.py
7201 . 8071 .
7202 8072
7203 For information on running tests on hardware, see the "`Enabling 8073 For information on running tests on hardware, see the
7204 Runtime Tests on 8074 ":ref:`hardware-image-enabling-tests`"
7205 Hardware <&YOCTO_DOCS_DEV_URL;#hardware-image-enabling-tests>`__"
7206 section in the Yocto Project Development Tasks Manual. 8075 section in the Yocto Project Development Tasks Manual.
7207 8076
7208 TEST_TARGET_IP 8077 TEST_TARGET_IP
7209 The IP address of your hardware under test. The ``TEST_TARGET_IP`` 8078 The IP address of your hardware under test. The ``TEST_TARGET_IP``
7210 variable has no effect when :term:`TEST_TARGET` is 8079 variable has no effect when :term:`TEST_TARGET` is
7211 set to "qemu". 8080 set to "qemu".
7212 8081
7213 When you specify the IP address, you can also include a port. Here is 8082 When you specify the IP address, you can also include a port. Here is
7214 an example: TEST_TARGET_IP = "192.168.1.4:2201" Specifying a port is 8083 an example:
8084 ::
8085
8086 TEST_TARGET_IP = "192.168.1.4:2201"
8087
8088 Specifying a port is
7215 useful when SSH is started on a non-standard port or in cases when 8089 useful when SSH is started on a non-standard port or in cases when
7216 your hardware under test is behind a firewall or network that is not 8090 your hardware under test is behind a firewall or network that is not
7217 directly accessible from your host and you need to do port address 8091 directly accessible from your host and you need to do port address
7218 translation. 8092 translation.
7219 8093
7220 TEST_SUITES 8094 TEST_SUITES
7221 An ordered list of tests (modules) to run against an image when 8095 An ordered list of tests (modules) to run against an image when
7222 performing automated runtime testing. 8096 performing automated runtime testing.
7223 8097
7224 The OpenEmbedded build system provides a core set of tests that can 8098 The OpenEmbedded build system provides a core set of tests that can
7225 be used against images. 8099 be used against images.
7226 8100
7227 .. note:: 8101 .. note::
7228 8102
7229 Currently, there is only support for running these tests under 8103 Currently, there is only support for running these tests under
7230 QEMU. 8104 QEMU.
7231 8105
7232 Tests include ``ping``, ``ssh``, ``df`` among others. You can add 8106 Tests include ``ping``, ``ssh``, ``df`` among others. You can add
7233 your own tests to the list of tests by appending ``TEST_SUITES`` as 8107 your own tests to the list of tests by appending ``TEST_SUITES`` as
7234 follows: TEST_SUITES_append = " mytest" Alternatively, you can 8108 follows:
8109 ::
8110
8111 TEST_SUITES_append = " mytest"
8112
8113 Alternatively, you can
7235 provide the "auto" option to have all applicable tests run against 8114 provide the "auto" option to have all applicable tests run against
7236 the image. TEST_SUITES_append = " auto" Using this option causes the 8115 the image.
8116 ::
8117
8118 TEST_SUITES_append = " auto"
8119
8120 Using this option causes the
7237 build system to automatically run tests that are applicable to the 8121 build system to automatically run tests that are applicable to the
7238 image. Tests that are not applicable are skipped. 8122 image. Tests that are not applicable are skipped.
7239 8123
7240 The order in which tests are run is important. Tests that depend on 8124 The order in which tests are run is important. Tests that depend on
7241 another test must appear later in the list than the test on which 8125 another test must appear later in the list than the test on which
7242 they depend. For example, if you append the list of tests with two 8126 they depend. For example, if you append the list of tests with two
7243 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on 8127 tests (``test_A`` and ``test_B``) where ``test_B`` is dependent on
7244 ``test_A``, then you must order the tests as follows: TEST_SUITES = " 8128 ``test_A``, then you must order the tests as follows:
7245 test_A test_B" 8129 ::
7246 8130
7247 For more information on testing images, see the "`Performing 8131 TEST_SUITES = "test_A test_B"
7248 Automated Runtime 8132
7249 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" 8133 For more information on testing images, see the
8134 ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
7250 section in the Yocto Project Development Tasks Manual. 8135 section in the Yocto Project Development Tasks Manual.
7251 8136
7252 TESTIMAGE_AUTO 8137 TESTIMAGE_AUTO
7253 Automatically runs the series of automated tests for images when an 8138 Automatically runs the series of automated tests for images when an
7254 image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes 8139 image is successfully built. Setting ``TESTIMAGE_AUTO`` to "1" causes
7255 any image that successfully builds to automatically boot under QEMU. 8140 any image that successfully builds to automatically boot under QEMU.
7256 Using the variable also adds in dependencies so that any SDK for 8141 Using the variable also adds in dependencies so that any SDK for
7257 which testing is requested is automatically built first. 8142 which testing is requested is automatically built first.
7258 8143
7259 These tests are written in Python making use of the ``unittest`` 8144 These tests are written in Python making use of the ``unittest``
7260 module, and the majority of them run commands on the target system 8145 module, and the majority of them run commands on the target system
7261 over ``ssh``. You can set this variable to "1" in your ``local.conf`` 8146 over ``ssh``. You can set this variable to "1" in your ``local.conf``
7262 file in the :term:`Build Directory` to have the 8147 file in the :term:`Build Directory` to have the
7263 OpenEmbedded build system automatically run these tests after an 8148 OpenEmbedded build system automatically run these tests after an
7264 image successfully builds: TESTIMAGE_AUTO = "1" For more information 8149 image successfully builds:
7265 on enabling, running, and writing these tests, see the "`Performing 8150
7266 Automated Runtime 8151 TESTIMAGE_AUTO = "1"
7267 Testing <&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing>`__" 8152
8153 For more information
8154 on enabling, running, and writing these tests, see the
8155 ":ref:`dev-manual/dev-manual-common-tasks:performing automated runtime testing`"
7268 section in the Yocto Project Development Tasks Manual and the 8156 section in the Yocto Project Development Tasks Manual and the
7269 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section. 8157 ":ref:`testimage*.bbclass <ref-classes-testimage*>`" section.
7270 8158
7271 THISDIR 8159 THISDIR
7272 The directory in which the file BitBake is currently parsing is 8160 The directory in which the file BitBake is currently parsing is
7273 located. Do not manually set this variable. 8161 located. Do not manually set this variable.
7274 8162
7275 TIME 8163 TIME
7276 The time the build was started. Times appear using the hour, minute, 8164 The time the build was started. Times appear using the hour, minute,
7277 and second (HMS) format (e.g. "140159" for one minute and fifty-nine 8165 and second (HMS) format (e.g. "140159" for one minute and fifty-nine
7278 seconds past 1400 hours). 8166 seconds past 1400 hours).
7279 8167
7280 TMPDIR 8168 TMPDIR
7281 This variable is the base directory the OpenEmbedded build system 8169 This variable is the base directory the OpenEmbedded build system
7282 uses for all build output and intermediate files (other than the 8170 uses for all build output and intermediate files (other than the
7283 shared state cache). By default, the ``TMPDIR`` variable points to 8171 shared state cache). By default, the ``TMPDIR`` variable points to
7284 ``tmp`` within the :term:`Build Directory`. 8172 ``tmp`` within the :term:`Build Directory`.
7285 8173
7286 If you want to establish this directory in a location other than the 8174 If you want to establish this directory in a location other than the
7287 default, you can uncomment and edit the following statement in the 8175 default, you can uncomment and edit the following statement in the
7288 ``conf/local.conf`` file in the :term:`Source Directory`: 8176 ``conf/local.conf`` file in the :term:`Source Directory`:
7289 #TMPDIR = "${TOPDIR}/tmp" An 8177 ::
7290 example use for this scenario is to set ``TMPDIR`` to a local disk, 8178
8179 #TMPDIR = "${TOPDIR}/tmp"
8180
8181 An example use for this scenario is to set ``TMPDIR`` to a local disk,
7291 which does not use NFS, while having the Build Directory use NFS. 8182 which does not use NFS, while having the Build Directory use NFS.
7292 8183
7293 The filesystem used by ``TMPDIR`` must have standard filesystem 8184 The filesystem used by ``TMPDIR`` must have standard filesystem
7294 semantics (i.e. mixed-case files are unique, POSIX file locking, and 8185 semantics (i.e. mixed-case files are unique, POSIX file locking, and
7295 persistent inodes). Due to various issues with NFS and bugs in some 8186 persistent inodes). Due to various issues with NFS and bugs in some
7296 implementations, NFS does not meet this minimum requirement. 8187 implementations, NFS does not meet this minimum requirement.
7297 Consequently, ``TMPDIR`` cannot be on NFS. 8188 Consequently, ``TMPDIR`` cannot be on NFS.
7298 8189
7299 TOOLCHAIN_HOST_TASK 8190 TOOLCHAIN_HOST_TASK
7300 This variable lists packages the OpenEmbedded build system uses when 8191 This variable lists packages the OpenEmbedded build system uses when
7301 building an SDK, which contains a cross-development environment. The 8192 building an SDK, which contains a cross-development environment. The
7302 packages specified by this variable are part of the toolchain set 8193 packages specified by this variable are part of the toolchain set
7303 that runs on the :term:`SDKMACHINE`, and each 8194 that runs on the :term:`SDKMACHINE`, and each
7304 package should usually have the prefix ``nativesdk-``. For example, 8195 package should usually have the prefix ``nativesdk-``. For example,
7305 consider the following command when building an SDK: $ bitbake -c 8196 consider the following command when building an SDK:
7306 populate_sdk imagename In this case, a default list of packages is 8197 ::
8198
8199 $ bitbake -c populate_sdk imagename
8200
8201 In this case, a default list of packages is
7307 set in this variable, but you can add additional packages to the 8202 set in this variable, but you can add additional packages to the
7308 list. See the "`Adding Individual Packages to the Standard 8203 list. See the
7309 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section 8204 ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section
7310 in the Yocto Project Application Development and the Extensible 8205 in the Yocto Project Application Development and the Extensible
7311 Software Development Kit (eSDK) manual for more information. 8206 Software Development Kit (eSDK) manual for more information.
7312 8207
7313 For background information on cross-development toolchains in the 8208 For background information on cross-development toolchains in the
7314 Yocto Project development environment, see the "`Cross-Development 8209 Yocto Project development environment, see the
7315 Toolchain 8210 ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`"
7316 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
7317 section in the Yocto Project Overview and Concepts Manual. For 8211 section in the Yocto Project Overview and Concepts Manual. For
7318 information on setting up a cross-development environment, see the 8212 information on setting up a cross-development environment, see the
7319 `Yocto Project Application Development and the Extensible Software 8213 :doc:`../sdk-manual/sdk-manual` manual.
7320 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. 8214
7321
7322 TOOLCHAIN_OUTPUTNAME 8215 TOOLCHAIN_OUTPUTNAME
7323 This variable defines the name used for the toolchain output. The 8216 This variable defines the name used for the toolchain output. The
7324 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets 8217 :ref:`populate_sdk_base <ref-classes-populate-sdk-*>` class sets
7325 the ``TOOLCHAIN_OUTPUTNAME`` variable as follows: 8218 the ``TOOLCHAIN_OUTPUTNAME`` variable as follows:
7326 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}" See 8219 ::
8220
8221 TOOLCHAIN_OUTPUTNAME ?= "${SDK_NAME}-toolchain-${SDK_VERSION}"
8222
8223 See
7327 the :term:`SDK_NAME` and 8224 the :term:`SDK_NAME` and
7328 :term:`SDK_VERSION` variables for additional 8225 :term:`SDK_VERSION` variables for additional
7329 information. 8226 information.
7330 8227
7331 TOOLCHAIN_TARGET_TASK 8228 TOOLCHAIN_TARGET_TASK
7332 This variable lists packages the OpenEmbedded build system uses when 8229 This variable lists packages the OpenEmbedded build system uses when
7333 it creates the target part of an SDK (i.e. the part built for the 8230 it creates the target part of an SDK (i.e. the part built for the
7334 target hardware), which includes libraries and headers. Use this 8231 target hardware), which includes libraries and headers. Use this
7335 variable to add individual packages to the part of the SDK that runs 8232 variable to add individual packages to the part of the SDK that runs
7336 on the target. See the "`Adding Individual Packages to the Standard 8233 on the target. See the
7337 SDK <&YOCTO_DOCS_SDK_URL;#sdk-adding-individual-packages>`__" section 8234 ":ref:`sdk-manual/sdk-appendix-customizing-standard:adding individual packages to the standard sdk`" section
7338 in the Yocto Project Application Development and the Extensible 8235 in the Yocto Project Application Development and the Extensible
7339 Software Development Kit (eSDK) manual for more information. 8236 Software Development Kit (eSDK) manual for more information.
7340 8237
7341 For background information on cross-development toolchains in the 8238 For background information on cross-development toolchains in the
7342 Yocto Project development environment, see the "`Cross-Development 8239 Yocto Project development environment, see the
7343 Toolchain 8240 ":ref:`sdk-manual/sdk-intro:the cross-development toolchain`"
7344 Generation <&YOCTO_DOCS_OM_URL;#cross-development-toolchain-generation>`__"
7345 section in the Yocto Project Overview and Concepts Manual. For 8241 section in the Yocto Project Overview and Concepts Manual. For
7346 information on setting up a cross-development environment, see the 8242 information on setting up a cross-development environment, see the
7347 `Yocto Project Application Development and the Extensible Software 8243 :doc:`../sdk-manual/sdk-manual` manual.
7348 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__ manual. 8244
7349
7350 TOPDIR 8245 TOPDIR
7351 The top-level :term:`Build Directory`. BitBake 8246 The top-level :term:`Build Directory`. BitBake
7352 automatically sets this variable when you initialize your build 8247 automatically sets this variable when you initialize your build
7353 environment using ````` <#structure-core-script>`__. 8248 environment using ````` <#structure-core-script>`__.
7354 8249
7355 TRANSLATED_TARGET_ARCH 8250 TRANSLATED_TARGET_ARCH
7356 A sanitized version of :term:`TARGET_ARCH`. This 8251 A sanitized version of :term:`TARGET_ARCH`. This
7357 variable is used where the architecture is needed in a value where 8252 variable is used where the architecture is needed in a value where
7358 underscores are not allowed, for example within package filenames. In 8253 underscores are not allowed, for example within package filenames. In
7359 this case, dash characters replace any underscore characters used in 8254 this case, dash characters replace any underscore characters used in
7360 ``TARGET_ARCH``. 8255 ``TARGET_ARCH``.
7361 8256
7362 Do not edit this variable. 8257 Do not edit this variable.
7363 8258
7364 TUNE_ARCH 8259 TUNE_ARCH
7365 The GNU canonical architecture for a specific architecture (i.e. 8260 The GNU canonical architecture for a specific architecture (i.e.
7366 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses 8261 ``arm``, ``armeb``, ``mips``, ``mips64``, and so forth). BitBake uses
7367 this value to setup configuration. 8262 this value to setup configuration.
7368 8263
7369 ``TUNE_ARCH`` definitions are specific to a given architecture. The 8264 ``TUNE_ARCH`` definitions are specific to a given architecture. The
7370 definitions can be a single static definition, or can be dynamically 8265 definitions can be a single static definition, or can be dynamically
7371 adjusted. You can see details for a given CPU family by looking at 8266 adjusted. You can see details for a given CPU family by looking at
7372 the architecture's ``README`` file. For example, the 8267 the architecture's ``README`` file. For example, the
7373 ``meta/conf/machine/include/mips/README`` file in the 8268 ``meta/conf/machine/include/mips/README`` file in the
7374 :term:`Source Directory` provides information for 8269 :term:`Source Directory` provides information for
7375 ``TUNE_ARCH`` specific to the ``mips`` architecture. 8270 ``TUNE_ARCH`` specific to the ``mips`` architecture.
7376 8271
7377 ``TUNE_ARCH`` is tied closely to 8272 ``TUNE_ARCH`` is tied closely to
7378 :term:`TARGET_ARCH`, which defines the target 8273 :term:`TARGET_ARCH`, which defines the target
7379 machine's architecture. The BitBake configuration file 8274 machine's architecture. The BitBake configuration file
7380 (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows: 8275 (``meta/conf/bitbake.conf``) sets ``TARGET_ARCH`` as follows:
7381 TARGET_ARCH = "${TUNE_ARCH}" 8276 ::
7382 8277
8278 TARGET_ARCH = "${TUNE_ARCH}"
8279
7383 The following list, which is by no means complete since architectures 8280 The following list, which is by no means complete since architectures
7384 are configurable, shows supported machine architectures: arm i586 8281 are configurable, shows supported machine architectures:
7385 x86_64 powerpc powerpc64 mips mipsel 8282
7386 8283 - arm
8284 - i586
8285 - x86_64
8286 - powerpc
8287 - powerpc64
8288 - mips
8289 - mipsel
8290
7387 TUNE_ASARGS 8291 TUNE_ASARGS
7388 Specifies architecture-specific assembler flags for the target 8292 Specifies architecture-specific assembler flags for the target
7389 system. The set of flags is based on the selected tune features. 8293 system. The set of flags is based on the selected tune features.
@@ -7391,28 +8295,30 @@ system and gives an overview of their function and contents.
7391 typically under ``meta/conf/machine/include/`` and are influenced 8295 typically under ``meta/conf/machine/include/`` and are influenced
7392 through :term:`TUNE_FEATURES`. For example, the 8296 through :term:`TUNE_FEATURES`. For example, the
7393 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 8297 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
7394 for the x86 architecture as follows: TUNE_ASARGS += 8298 for the x86 architecture as follows:
7395 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}" 8299 ::
7396 8300
8301 TUNE_ASARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-x32", "", d)}"
8302
7397 .. note:: 8303 .. note::
7398 8304
7399 Board Support Packages (BSPs) select the tune. The selected tune, 8305 Board Support Packages (BSPs) select the tune. The selected tune,
7400 in turn, affects the tune variables themselves (i.e. the tune can 8306 in turn, affects the tune variables themselves (i.e. the tune can
7401 supply its own set of flags). 8307 supply its own set of flags).
7402 8308
7403 TUNE_CCARGS 8309 TUNE_CCARGS
7404 Specifies architecture-specific C compiler flags for the target 8310 Specifies architecture-specific C compiler flags for the target
7405 system. The set of flags is based on the selected tune features. 8311 system. The set of flags is based on the selected tune features.
7406 ``TUNE_CCARGS`` is set using the tune include files, which are 8312 ``TUNE_CCARGS`` is set using the tune include files, which are
7407 typically under ``meta/conf/machine/include/`` and are influenced 8313 typically under ``meta/conf/machine/include/`` and are influenced
7408 through :term:`TUNE_FEATURES`. 8314 through :term:`TUNE_FEATURES`.
7409 8315
7410 .. note:: 8316 .. note::
7411 8317
7412 Board Support Packages (BSPs) select the tune. The selected tune, 8318 Board Support Packages (BSPs) select the tune. The selected tune,
7413 in turn, affects the tune variables themselves (i.e. the tune can 8319 in turn, affects the tune variables themselves (i.e. the tune can
7414 supply its own set of flags). 8320 supply its own set of flags).
7415 8321
7416 TUNE_LDARGS 8322 TUNE_LDARGS
7417 Specifies architecture-specific linker flags for the target system. 8323 Specifies architecture-specific linker flags for the target system.
7418 The set of flags is based on the selected tune features. 8324 The set of flags is based on the selected tune features.
@@ -7420,41 +8326,49 @@ system and gives an overview of their function and contents.
7420 typically under ``meta/conf/machine/include/`` and are influenced 8326 typically under ``meta/conf/machine/include/`` and are influenced
7421 through :term:`TUNE_FEATURES`. For example, the 8327 through :term:`TUNE_FEATURES`. For example, the
7422 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags 8328 ``meta/conf/machine/include/x86/arch-x86.inc`` file defines the flags
7423 for the x86 architecture as follows: TUNE_LDARGS += 8329 for the x86 architecture as follows:
7424 "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", 8330 ::
7425 d)}" 8331
7426 8332 TUNE_LDARGS += "${@bb.utils.contains("TUNE_FEATURES", "mx32", "-m elf32_x86_64", "", d)}"
8333
7427 .. note:: 8334 .. note::
7428 8335
7429 Board Support Packages (BSPs) select the tune. The selected tune, 8336 Board Support Packages (BSPs) select the tune. The selected tune,
7430 in turn, affects the tune variables themselves (i.e. the tune can 8337 in turn, affects the tune variables themselves (i.e. the tune can
7431 supply its own set of flags). 8338 supply its own set of flags).
7432 8339
7433 TUNE_FEATURES 8340 TUNE_FEATURES
7434 Features used to "tune" a compiler for optimal use given a specific 8341 Features used to "tune" a compiler for optimal use given a specific
7435 processor. The features are defined within the tune files and allow 8342 processor. The features are defined within the tune files and allow
7436 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on 8343 arguments (i.e. ``TUNE_*ARGS``) to be dynamically generated based on
7437 the features. 8344 the features.
7438 8345
7439 The OpenEmbedded build system verifies the features to be sure they 8346 The OpenEmbedded build system verifies the features to be sure they
7440 are not conflicting and that they are supported. 8347 are not conflicting and that they are supported.
7441 8348
7442 The BitBake configuration file (``meta/conf/bitbake.conf``) defines 8349 The BitBake configuration file (``meta/conf/bitbake.conf``) defines
7443 ``TUNE_FEATURES`` as follows: TUNE_FEATURES ??= 8350 ``TUNE_FEATURES`` as follows:
7444 "${TUNE_FEATURES_tune-${DEFAULTTUNE}}" See the 8351 ::
7445 :term:`DEFAULTTUNE` variable for more information. 8352
7446 8353 TUNE_FEATURES ??= "${TUNE_FEATURES_tune-${DEFAULTTUNE}}"
8354
8355 See the :term:`DEFAULTTUNE` variable for more information.
8356
7447 TUNE_PKGARCH 8357 TUNE_PKGARCH
7448 The package architecture understood by the packaging system to define 8358 The package architecture understood by the packaging system to define
7449 the architecture, ABI, and tuning of output packages. The specific 8359 the architecture, ABI, and tuning of output packages. The specific
7450 tune is defined using the "_tune" override as follows: 8360 tune is defined using the "_tune" override as follows:
7451 TUNE_PKGARCH_tune-tune = "tune" 8361 ::
7452 8362
8363 TUNE_PKGARCH_tune-tune = "tune"
8364
7453 These tune-specific package architectures are defined in the machine 8365 These tune-specific package architectures are defined in the machine
7454 include files. Here is an example of the "core2-32" tuning as used in 8366 include files. Here is an example of the "core2-32" tuning as used in
7455 the ``meta/conf/machine/include/tune-core2.inc`` file: 8367 the ``meta/conf/machine/include/tune-core2.inc`` file:
7456 TUNE_PKGARCH_tune-core2-32 = "core2-32" 8368 ::
7457 8369
8370 TUNE_PKGARCH_tune-core2-32 = "core2-32"
8371
7458 TUNEABI 8372 TUNEABI
7459 An underlying Application Binary Interface (ABI) used by a particular 8373 An underlying Application Binary Interface (ABI) used by a particular
7460 tuning in a given toolchain layer. Providers that use prebuilt 8374 tuning in a given toolchain layer. Providers that use prebuilt
@@ -7462,11 +8376,11 @@ system and gives an overview of their function and contents.
7462 :term:`TUNEABI_OVERRIDE`, and 8376 :term:`TUNEABI_OVERRIDE`, and
7463 :term:`TUNEABI_WHITELIST` variables to check 8377 :term:`TUNEABI_WHITELIST` variables to check
7464 compatibility of tunings against their selection of libraries. 8378 compatibility of tunings against their selection of libraries.
7465 8379
7466 If ``TUNEABI`` is undefined, then every tuning is allowed. See the 8380 If ``TUNEABI`` is undefined, then every tuning is allowed. See the
7467 :ref:`sanity <ref-classes-sanity>` class to see how the variable is 8381 :ref:`sanity <ref-classes-sanity>` class to see how the variable is
7468 used. 8382 used.
7469 8383
7470 TUNEABI_OVERRIDE 8384 TUNEABI_OVERRIDE
7471 If set, the OpenEmbedded system ignores the 8385 If set, the OpenEmbedded system ignores the
7472 :term:`TUNEABI_WHITELIST` variable. 8386 :term:`TUNEABI_WHITELIST` variable.
@@ -7474,10 +8388,10 @@ system and gives an overview of their function and contents.
7474 ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and 8388 ``TUNEABI_OVERRIDE``, ``TUNEABI_WHITELIST``, and
7475 :term:`TUNEABI` variables to check compatibility of a 8389 :term:`TUNEABI` variables to check compatibility of a
7476 tuning against their selection of libraries. 8390 tuning against their selection of libraries.
7477 8391
7478 See the :ref:`sanity <ref-classes-sanity>` class to see how the 8392 See the :ref:`sanity <ref-classes-sanity>` class to see how the
7479 variable is used. 8393 variable is used.
7480 8394
7481 TUNEABI_WHITELIST 8395 TUNEABI_WHITELIST
7482 A whitelist of permissible :term:`TUNEABI` values. If 8396 A whitelist of permissible :term:`TUNEABI` values. If
7483 ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers 8397 ``TUNEABI_WHITELIST`` is not set, all tunes are allowed. Providers
@@ -7485,100 +8399,112 @@ system and gives an overview of their function and contents.
7485 :term:`TUNEABI_OVERRIDE`, and ``TUNEABI`` 8399 :term:`TUNEABI_OVERRIDE`, and ``TUNEABI``
7486 variables to check compatibility of a tuning against their selection 8400 variables to check compatibility of a tuning against their selection
7487 of libraries. 8401 of libraries.
7488 8402
7489 See the :ref:`sanity <ref-classes-sanity>` class to see how the 8403 See the :ref:`sanity <ref-classes-sanity>` class to see how the
7490 variable is used. 8404 variable is used.
7491 8405
7492 TUNECONFLICTS[feature] 8406 TUNECONFLICTS[feature]
7493 Specifies CPU or Application Binary Interface (ABI) tuning features 8407 Specifies CPU or Application Binary Interface (ABI) tuning features
7494 that conflict with feature. 8408 that conflict with feature.
7495 8409
7496 Known tuning conflicts are specified in the machine include files in 8410 Known tuning conflicts are specified in the machine include files in
7497 the :term:`Source Directory`. Here is an example from 8411 the :term:`Source Directory`. Here is an example from
7498 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file 8412 the ``meta/conf/machine/include/mips/arch-mips.inc`` include file
7499 that lists the "o32" and "n64" features as conflicting with the "n32" 8413 that lists the "o32" and "n64" features as conflicting with the "n32"
7500 feature: TUNECONFLICTS[n32] = "o32 n64" 8414 feature:
7501 8415 ::
8416
8417 TUNECONFLICTS[n32] = "o32 n64"
8418
7502 TUNEVALID[feature] 8419 TUNEVALID[feature]
7503 Specifies a valid CPU or Application Binary Interface (ABI) tuning 8420 Specifies a valid CPU or Application Binary Interface (ABI) tuning
7504 feature. The specified feature is stored as a flag. Valid features 8421 feature. The specified feature is stored as a flag. Valid features
7505 are specified in the machine include files (e.g. 8422 are specified in the machine include files (e.g.
7506 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example 8423 ``meta/conf/machine/include/arm/arch-arm.inc``). Here is an example
7507 from that file: TUNEVALID[bigendian] = "Enable big-endian mode." 8424 from that file:
7508 8425 ::
8426
8427 TUNEVALID[bigendian] = "Enable big-endian mode."
8428
7509 See the machine include files in the :term:`Source Directory` 8429 See the machine include files in the :term:`Source Directory`
7510 for these features. 8430 for these features.
7511 8431
7512 UBOOT_CONFIG 8432 UBOOT_CONFIG
7513 Configures the :term:`UBOOT_MACHINE` and can 8433 Configures the :term:`UBOOT_MACHINE` and can
7514 also define :term:`IMAGE_FSTYPES` for individual 8434 also define :term:`IMAGE_FSTYPES` for individual
7515 cases. 8435 cases.
7516 8436
7517 Following is an example from the ``meta-fsl-arm`` layer. UBOOT_CONFIG 8437 Following is an example from the ``meta-fsl-arm`` layer. ::
7518 ??= "sd" UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard" 8438
7519 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config" 8439 UBOOT_CONFIG ??= "sd"
7520 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs" 8440 UBOOT_CONFIG[sd] = "mx6qsabreauto_config,sdcard"
7521 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config" In this example, 8441 UBOOT_CONFIG[eimnor] = "mx6qsabreauto_eimnor_config"
7522 "sd" is selected as the configuration of the possible four for the 8442 UBOOT_CONFIG[nand] = "mx6qsabreauto_nand_config,ubifs"
8443 UBOOT_CONFIG[spinor] = "mx6qsabreauto_spinor_config"
8444
8445 In this example, "sd" is selected as the configuration of the possible four for the
7523 ``UBOOT_MACHINE``. The "sd" configuration defines 8446 ``UBOOT_MACHINE``. The "sd" configuration defines
7524 "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the 8447 "mx6qsabreauto_config" as the value for ``UBOOT_MACHINE``, while the
7525 "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image. 8448 "sdcard" specifies the ``IMAGE_FSTYPES`` to use for the U-boot image.
7526 8449
7527 For more information on how the ``UBOOT_CONFIG`` is handled, see the 8450 For more information on how the ``UBOOT_CONFIG`` is handled, see the
7528 ```uboot-config`http://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/classes/uboot-config.bbclass 8451 :ref:`uboot-config <ref-classes-uboot-config>`
7529 class. 8452 class.
7530 8453
7531 UBOOT_DTB_LOADADDRESS 8454 UBOOT_DTB_LOADADDRESS
7532 Specifies the load address for the dtb image used by U-boot. During FIT 8455 Specifies the load address for the dtb image used by U-boot. During FIT
7533 image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in 8456 image creation, the ``UBOOT_DTB_LOADADDRESS`` variable is used in
7534 ``kernel-fitimage`` class to specify the load address to be used in 8457 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify
8458 the load address to be used in
7535 creating the dtb sections of Image Tree Source for the FIT image. 8459 creating the dtb sections of Image Tree Source for the FIT image.
7536 8460
7537 UBOOT_DTBO_LOADADDRESS 8461 UBOOT_DTBO_LOADADDRESS
7538 Specifies the load address for the dtbo image used by U-boot. During FIT 8462 Specifies the load address for the dtbo image used by U-boot. During FIT
7539 image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in 8463 image creation, the ``UBOOT_DTBO_LOADADDRESS`` variable is used in
7540 ``kernel-fitimage`` class to specify the load address to be used in 8464 :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the load address to be used in
7541 creating the dtbo sections of Image Tree Source for the FIT image. 8465 creating the dtbo sections of Image Tree Source for the FIT image.
7542 8466
7543 UBOOT_ENTRYPOINT 8467 UBOOT_ENTRYPOINT
7544 Specifies the entry point for the U-Boot image. During U-Boot image 8468 Specifies the entry point for the U-Boot image. During U-Boot image
7545 creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a 8469 creation, the ``UBOOT_ENTRYPOINT`` variable is passed as a
7546 command-line parameter to the ``uboot-mkimage`` utility. 8470 command-line parameter to the ``uboot-mkimage`` utility.
7547 8471
7548 UBOOT_LOADADDRESS 8472 UBOOT_LOADADDRESS
7549 Specifies the load address for the U-Boot image. During U-Boot image 8473 Specifies the load address for the U-Boot image. During U-Boot image
7550 creation, the ``UBOOT_LOADADDRESS`` variable is passed as a 8474 creation, the ``UBOOT_LOADADDRESS`` variable is passed as a
7551 command-line parameter to the ``uboot-mkimage`` utility. 8475 command-line parameter to the ``uboot-mkimage`` utility.
7552 8476
7553 UBOOT_LOCALVERSION 8477 UBOOT_LOCALVERSION
7554 Appends a string to the name of the local version of the U-Boot 8478 Appends a string to the name of the local version of the U-Boot
7555 image. For example, assuming the version of the U-Boot image built 8479 image. For example, assuming the version of the U-Boot image built
7556 was "2013.10", the full version string reported by U-Boot would be 8480 was "2013.10", the full version string reported by U-Boot would be
7557 "2013.10-yocto" given the following statement: UBOOT_LOCALVERSION = 8481 "2013.10-yocto" given the following statement:
7558 "-yocto" 8482 ::
7559 8483
8484 UBOOT_LOCALVERSION = "-yocto"
8485
7560 UBOOT_MACHINE 8486 UBOOT_MACHINE
7561 Specifies the value passed on the ``make`` command line when building 8487 Specifies the value passed on the ``make`` command line when building
7562 a U-Boot image. The value indicates the target platform 8488 a U-Boot image. The value indicates the target platform
7563 configuration. You typically set this variable from the machine 8489 configuration. You typically set this variable from the machine
7564 configuration file (i.e. ``conf/machine/machine_name.conf``). 8490 configuration file (i.e. ``conf/machine/machine_name.conf``).
7565 8491
7566 Please see the "Selection of Processor Architecture and Board Type" 8492 Please see the "Selection of Processor Architecture and Board Type"
7567 section in the U-Boot README for valid values for this variable. 8493 section in the U-Boot README for valid values for this variable.
7568 8494
7569 UBOOT_MAKE_TARGET 8495 UBOOT_MAKE_TARGET
7570 Specifies the target called in the ``Makefile``. The default target 8496 Specifies the target called in the ``Makefile``. The default target
7571 is "all". 8497 is "all".
7572 8498
7573 UBOOT_MKIMAGE_DTCOPTS 8499 UBOOT_MKIMAGE_DTCOPTS
7574 Options for the device tree compiler passed to mkimage '-D' 8500 Options for the device tree compiler passed to mkimage '-D'
7575 feature while creating FIT image in ``kernel-fitimage`` class. 8501 feature while creating FIT image in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class.
7576 8502
7577 UBOOT_RD_LOADADDRESS 8503 UBOOT_RD_LOADADDRESS
7578 Specifies the load address for the RAM disk image. 8504 Specifies the load address for the RAM disk image.
7579 During FIT image creation, the 8505 During FIT image creation, the
7580 ``UBOOT_RD_LOADADDRESS`` variable is used 8506 ``UBOOT_RD_LOADADDRESS`` variable is used
7581 in ``kernel-fitimage`` class to specify the 8507 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
7582 load address to be used in creating the Image Tree Source for 8508 load address to be used in creating the Image Tree Source for
7583 the FIT image. 8509 the FIT image.
7584 8510
@@ -7586,10 +8512,10 @@ system and gives an overview of their function and contents.
7586 Specifies the entrypoint for the RAM disk image. 8512 Specifies the entrypoint for the RAM disk image.
7587 During FIT image creation, the 8513 During FIT image creation, the
7588 ``UBOOT_RD_ENTRYPOINT`` variable is used 8514 ``UBOOT_RD_ENTRYPOINT`` variable is used
7589 in ``kernel-fitimage`` class to specify the 8515 in :ref:`kernel-fitimage <ref-classes-kernel-fitimage>` class to specify the
7590 entrypoint to be used in creating the Image Tree Source for 8516 entrypoint to be used in creating the Image Tree Source for
7591 the FIT image. 8517 the FIT image.
7592 8518
7593 UBOOT_SIGN_ENABLE 8519 UBOOT_SIGN_ENABLE
7594 Enable signing of FIT image. The default value is "0". 8520 Enable signing of FIT image. The default value is "0".
7595 8521
@@ -7628,40 +8554,44 @@ system and gives an overview of their function and contents.
7628 configure scripts. It follows that no benefit exists in seeing a 8554 configure scripts. It follows that no benefit exists in seeing a
7629 warning about these options. For these cases, the options are added 8555 warning about these options. For these cases, the options are added
7630 to ``UNKNOWN_CONFIGURE_WHITELIST``. 8556 to ``UNKNOWN_CONFIGURE_WHITELIST``.
7631 8557
7632 The configure arguments check that uses 8558 The configure arguments check that uses
7633 ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the 8559 ``UNKNOWN_CONFIGURE_WHITELIST`` is part of the
7634 :ref:`insane <ref-classes-insane>` class and is only enabled if the 8560 :ref:`insane <ref-classes-insane>` class and is only enabled if the
7635 recipe inherits the :ref:`autotools <ref-classes-autotools>` class. 8561 recipe inherits the :ref:`autotools <ref-classes-autotools>` class.
7636 8562
7637 UPDATERCPN 8563 UPDATERCPN
7638 For recipes inheriting the 8564 For recipes inheriting the
7639 :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN`` 8565 :ref:`update-rc.d <ref-classes-update-rc.d>` class, ``UPDATERCPN``
7640 specifies the package that contains the initscript that is enabled. 8566 specifies the package that contains the initscript that is enabled.
7641 8567
7642 The default value is "${PN}". Given that almost all recipes that 8568 The default value is "${PN}". Given that almost all recipes that
7643 install initscripts package them in the main package for the recipe, 8569 install initscripts package them in the main package for the recipe,
7644 you rarely need to set this variable in individual recipes. 8570 you rarely need to set this variable in individual recipes.
7645 8571
7646 UPSTREAM_CHECK_GITTAGREGEX 8572 UPSTREAM_CHECK_GITTAGREGEX
7647 You can perform a per-recipe check for what the latest upstream 8573 You can perform a per-recipe check for what the latest upstream
7648 source code version is by calling ``bitbake -c checkpkg`` recipe. If 8574 source code version is by calling ``bitbake -c checkpkg`` recipe. If
7649 the recipe source code is provided from Git repositories, the 8575 the recipe source code is provided from Git repositories, the
7650 OpenEmbedded build system determines the latest upstream version by 8576 OpenEmbedded build system determines the latest upstream version by
7651 picking the latest tag from the list of all repository tags. 8577 picking the latest tag from the list of all repository tags.
7652 8578
7653 You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a 8579 You can use the ``UPSTREAM_CHECK_GITTAGREGEX`` variable to provide a
7654 regular expression to filter only the relevant tags should the 8580 regular expression to filter only the relevant tags should the
7655 default filter not work correctly. UPSTREAM_CHECK_GITTAGREGEX = 8581 default filter not work correctly.
7656 "git_tag_regex" 8582 ::
7657 8583
8584 UPSTREAM_CHECK_GITTAGREGEX = "git_tag_regex"
8585
7658 UPSTREAM_CHECK_REGEX 8586 UPSTREAM_CHECK_REGEX
7659 Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different 8587 Use the ``UPSTREAM_CHECK_REGEX`` variable to specify a different
7660 regular expression instead of the default one when the package 8588 regular expression instead of the default one when the package
7661 checking system is parsing the page found using 8589 checking system is parsing the page found using
7662 :term:`UPSTREAM_CHECK_URI`. 8590 :term:`UPSTREAM_CHECK_URI`.
7663 UPSTREAM_CHECK_REGEX = "package_regex" 8591 ::
7664 8592
8593 UPSTREAM_CHECK_REGEX = "package_regex"
8594
7665 UPSTREAM_CHECK_URI 8595 UPSTREAM_CHECK_URI
7666 You can perform a per-recipe check for what the latest upstream 8596 You can perform a per-recipe check for what the latest upstream
7667 source code version is by calling ``bitbake -c checkpkg`` recipe. If 8597 source code version is by calling ``bitbake -c checkpkg`` recipe. If
@@ -7669,43 +8599,48 @@ system and gives an overview of their function and contents.
7669 determined by fetching the directory listing where the tarball is and 8599 determined by fetching the directory listing where the tarball is and
7670 attempting to find a later tarball. When this approach does not work, 8600 attempting to find a later tarball. When this approach does not work,
7671 you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that 8601 you can use ``UPSTREAM_CHECK_URI`` to provide a different URI that
7672 contains the link to the latest tarball. UPSTREAM_CHECK_URI = 8602 contains the link to the latest tarball.
7673 "recipe_url" 8603 ::
7674 8604
8605 UPSTREAM_CHECK_URI = "recipe_url"
8606
7675 USE_DEVFS 8607 USE_DEVFS
7676 Determines if ``devtmpfs`` is used for ``/dev`` population. The 8608 Determines if ``devtmpfs`` is used for ``/dev`` population. The
7677 default value used for ``USE_DEVFS`` is "1" when no value is 8609 default value used for ``USE_DEVFS`` is "1" when no value is
7678 specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a 8610 specifically set. Typically, you would set ``USE_DEVFS`` to "0" for a
7679 statically populated ``/dev`` directory. 8611 statically populated ``/dev`` directory.
7680 8612
7681 See the "`Selecting a Device 8613 See the ":ref:`selecting-dev-manager`" section in
7682 Manager <&YOCTO_DOCS_DEV_URL;#selecting-dev-manager>`__" section in
7683 the Yocto Project Development Tasks Manual for information on how to 8614 the Yocto Project Development Tasks Manual for information on how to
7684 use this variable. 8615 use this variable.
7685 8616
7686 USE_VT 8617 USE_VT
7687 When using 8618 When using
7688 `SysVinit <&YOCTO_DOCS_DEV_URL;#new-recipe-enabling-system-services>`__, 8619 :ref:`SysVinit <new-recipe-enabling-system-services>`,
7689 determines whether or not to run a 8620 determines whether or not to run a
7690 `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any 8621 `getty <http://en.wikipedia.org/wiki/Getty_%28Unix%29>`__ on any
7691 virtual terminals in order to enable logging in through those 8622 virtual terminals in order to enable logging in through those
7692 terminals. 8623 terminals.
7693 8624
7694 The default value used for ``USE_VT`` is "1" when no default value is 8625 The default value used for ``USE_VT`` is "1" when no default value is
7695 specifically set. Typically, you would set ``USE_VT`` to "0" in the 8626 specifically set. Typically, you would set ``USE_VT`` to "0" in the
7696 machine configuration file for machines that do not have a graphical 8627 machine configuration file for machines that do not have a graphical
7697 display attached and therefore do not need virtual terminal 8628 display attached and therefore do not need virtual terminal
7698 functionality. 8629 functionality.
7699 8630
7700 USER_CLASSES 8631 USER_CLASSES
7701 A list of classes to globally inherit. These classes are used by the 8632 A list of classes to globally inherit. These classes are used by the
7702 OpenEmbedded build system to enable extra features (e.g. 8633 OpenEmbedded build system to enable extra features (e.g.
7703 ``buildstats``, ``image-mklibs``, and so forth). 8634 ``buildstats``, ``image-mklibs``, and so forth).
7704 8635
7705 The default list is set in your ``local.conf`` file: USER_CLASSES ?= 8636 The default list is set in your ``local.conf`` file:
7706 "buildstats image-mklibs image-prelink" For more information, see 8637 ::
8638
8639 USER_CLASSES ?= "buildstats image-mklibs image-prelink"
8640
8641 For more information, see
7707 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`. 8642 ``meta-poky/conf/local.conf.sample`` in the :term:`Source Directory`.
7708 8643
7709 USERADD_ERROR_DYNAMIC 8644 USERADD_ERROR_DYNAMIC
7710 If set to ``error``, forces the OpenEmbedded build system to produce 8645 If set to ``error``, forces the OpenEmbedded build system to produce
7711 an error if the user identification (``uid``) and group 8646 an error if the user identification (``uid``) and group
@@ -7713,21 +8648,26 @@ system and gives an overview of their function and contents.
7713 listed in :term:`USERADD_UID_TABLES` and 8648 listed in :term:`USERADD_UID_TABLES` and
7714 :term:`USERADD_GID_TABLES`. If set to 8649 :term:`USERADD_GID_TABLES`. If set to
7715 ``warn``, a warning will be issued instead. 8650 ``warn``, a warning will be issued instead.
7716 8651
7717 The default behavior for the build system is to dynamically apply 8652 The default behavior for the build system is to dynamically apply
7718 ``uid`` and ``gid`` values. Consequently, the 8653 ``uid`` and ``gid`` values. Consequently, the
7719 ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan 8654 ``USERADD_ERROR_DYNAMIC`` variable is by default not set. If you plan
7720 on using statically assigned ``gid`` and ``uid`` values, you should 8655 on using statically assigned ``gid`` and ``uid`` values, you should
7721 set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf`` 8656 set the ``USERADD_ERROR_DYNAMIC`` variable in your ``local.conf``
7722 file as follows: USERADD_ERROR_DYNAMIC = "error" Overriding the 8657 file as follows:
8658 ::
8659
8660 USERADD_ERROR_DYNAMIC = "error"
8661
8662 Overriding the
7723 default behavior implies you are going to also take steps to set 8663 default behavior implies you are going to also take steps to set
7724 static ``uid`` and ``gid`` values through use of the 8664 static ``uid`` and ``gid`` values through use of the
7725 :term:`USERADDEXTENSION`, 8665 :term:`USERADDEXTENSION`,
7726 :term:`USERADD_UID_TABLES`, and 8666 :term:`USERADD_UID_TABLES`, and
7727 :term:`USERADD_GID_TABLES` variables. 8667 :term:`USERADD_GID_TABLES` variables.
7728 8668
7729 .. note:: 8669 .. note::
7730 8670
7731 There is a difference in behavior between setting 8671 There is a difference in behavior between setting
7732 USERADD_ERROR_DYNAMIC 8672 USERADD_ERROR_DYNAMIC
7733 to 8673 to
@@ -7745,38 +8685,44 @@ system and gives an overview of their function and contents.
7745 , it will only report errors for recipes that are actually built. 8685 , it will only report errors for recipes that are actually built.
7746 This saves you from having to add static IDs for recipes that you 8686 This saves you from having to add static IDs for recipes that you
7747 know will never be built. 8687 know will never be built.
7748 8688
7749 USERADD_GID_TABLES 8689 USERADD_GID_TABLES
7750 Specifies a password file to use for obtaining static group 8690 Specifies a password file to use for obtaining static group
7751 identification (``gid``) values when the OpenEmbedded build system 8691 identification (``gid``) values when the OpenEmbedded build system
7752 adds a group to the system during package installation. 8692 adds a group to the system during package installation.
7753 8693
7754 When applying static group identification (``gid``) values, the 8694 When applying static group identification (``gid``) values, the
7755 OpenEmbedded build system looks in :term:`BBPATH` for a 8695 OpenEmbedded build system looks in :term:`BBPATH` for a
7756 ``files/group`` file and then applies those ``uid`` values. Set the 8696 ``files/group`` file and then applies those ``uid`` values. Set the
7757 variable as follows in your ``local.conf`` file: USERADD_GID_TABLES = 8697 variable as follows in your ``local.conf`` file:
7758 "files/group" 8698 ::
7759 8699
8700
8701 USERADD_GID_TABLES = "files/group"
8702
7760 .. note:: 8703 .. note::
7761 8704
7762 Setting the 8705 Setting the
7763 USERADDEXTENSION 8706 USERADDEXTENSION
7764 variable to "useradd-staticids" causes the build system to use 8707 variable to "useradd-staticids" causes the build system to use
7765 static 8708 static
7766 gid 8709 gid
7767 values. 8710 values.
7768 8711
7769 USERADD_PACKAGES 8712 USERADD_PACKAGES
7770 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 8713 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
7771 this variable specifies the individual packages within the recipe 8714 this variable specifies the individual packages within the recipe
7772 that require users and/or groups to be added. 8715 that require users and/or groups to be added.
7773 8716
7774 You must set this variable if the recipe inherits the class. For 8717 You must set this variable if the recipe inherits the class. For
7775 example, the following enables adding a user for the main package in 8718 example, the following enables adding a user for the main package in
7776 a recipe: USERADD_PACKAGES = "${PN}" 8719 a recipe:
7777 8720 ::
8721
8722 USERADD_PACKAGES = "${PN}"
8723
7778 .. note:: 8724 .. note::
7779 8725
7780 It follows that if you are going to use the 8726 It follows that if you are going to use the
7781 USERADD_PACKAGES 8727 USERADD_PACKAGES
7782 variable, you need to set one or more of the 8728 variable, you need to set one or more of the
@@ -7786,50 +8732,57 @@ system and gives an overview of their function and contents.
7786 , or 8732 , or
7787 GROUPMEMS_PARAM 8733 GROUPMEMS_PARAM
7788 variables. 8734 variables.
7789 8735
7790 USERADD_PARAM 8736 USERADD_PARAM
7791 When inheriting the :ref:`useradd <ref-classes-useradd>` class, 8737 When inheriting the :ref:`useradd <ref-classes-useradd>` class,
7792 this variable specifies for a package what parameters should pass to 8738 this variable specifies for a package what parameters should pass to
7793 the ``useradd`` command if you add a user to the system when the 8739 the ``useradd`` command if you add a user to the system when the
7794 package is installed. 8740 package is installed.
7795 8741
7796 Here is an example from the ``dbus`` recipe: USERADD_PARAM_${PN} = 8742 Here is an example from the ``dbus`` recipe:
7797 "--system --home ${localstatedir}/lib/dbus \\ --no-create-home 8743 ::
7798 --shell /bin/false \\ --user-group messagebus" For information on the 8744
8745 USERADD_PARAM_${PN} = "--system --home ${localstatedir}/lib/dbus \
8746 --no-create-home --shell /bin/false \
8747 --user-group messagebus"
8748
8749 For information on the
7799 standard Linux shell command ``useradd``, see 8750 standard Linux shell command ``useradd``, see
7800 http://linux.die.net/man/8/useradd. 8751 http://linux.die.net/man/8/useradd.
7801 8752
7802 USERADD_UID_TABLES 8753 USERADD_UID_TABLES
7803 Specifies a password file to use for obtaining static user 8754 Specifies a password file to use for obtaining static user
7804 identification (``uid``) values when the OpenEmbedded build system 8755 identification (``uid``) values when the OpenEmbedded build system
7805 adds a user to the system during package installation. 8756 adds a user to the system during package installation.
7806 8757
7807 When applying static user identification (``uid``) values, the 8758 When applying static user identification (``uid``) values, the
7808 OpenEmbedded build system looks in :term:`BBPATH` for a 8759 OpenEmbedded build system looks in :term:`BBPATH` for a
7809 ``files/passwd`` file and then applies those ``uid`` values. Set the 8760 ``files/passwd`` file and then applies those ``uid`` values. Set the
7810 variable as follows in your ``local.conf`` file: USERADD_UID_TABLES = 8761 variable as follows in your ``local.conf`` file:
7811 "files/passwd" 8762 ::
7812 8763
8764 USERADD_UID_TABLES = "files/passwd"
8765
7813 .. note:: 8766 .. note::
7814 8767
7815 Setting the 8768 Setting the
7816 USERADDEXTENSION 8769 USERADDEXTENSION
7817 variable to "useradd-staticids" causes the build system to use 8770 variable to "useradd-staticids" causes the build system to use
7818 static 8771 static
7819 uid 8772 uid
7820 values. 8773 values.
7821 8774
7822 USERADDEXTENSION 8775 USERADDEXTENSION
7823 When set to "useradd-staticids", causes the OpenEmbedded build system 8776 When set to "useradd-staticids", causes the OpenEmbedded build system
7824 to base all user and group additions on a static ``passwd`` and 8777 to base all user and group additions on a static ``passwd`` and
7825 ``group`` files found in :term:`BBPATH`. 8778 ``group`` files found in :term:`BBPATH`.
7826 8779
7827 To use static user identification (``uid``) and group identification 8780 To use static user identification (``uid``) and group identification
7828 (``gid``) values, set the variable as follows in your ``local.conf`` 8781 (``gid``) values, set the variable as follows in your ``local.conf``
7829 file: USERADDEXTENSION = "useradd-staticids" 8782 file: USERADDEXTENSION = "useradd-staticids"
7830 8783
7831 .. note:: 8784 .. note::
7832 8785
7833 Setting this variable to use static 8786 Setting this variable to use static
7834 uid 8787 uid
7835 and 8788 and
@@ -7837,29 +8790,29 @@ system and gives an overview of their function and contents.
7837 values causes the OpenEmbedded build system to employ the 8790 values causes the OpenEmbedded build system to employ the
7838 useradd-staticids 8791 useradd-staticids
7839 class. 8792 class.
7840 8793
7841 If you use static ``uid`` and ``gid`` information, you must also 8794 If you use static ``uid`` and ``gid`` information, you must also
7842 specify the ``files/passwd`` and ``files/group`` files by setting the 8795 specify the ``files/passwd`` and ``files/group`` files by setting the
7843 :term:`USERADD_UID_TABLES` and 8796 :term:`USERADD_UID_TABLES` and
7844 :term:`USERADD_GID_TABLES` variables. 8797 :term:`USERADD_GID_TABLES` variables.
7845 Additionally, you should also set the 8798 Additionally, you should also set the
7846 :term:`USERADD_ERROR_DYNAMIC` variable. 8799 :term:`USERADD_ERROR_DYNAMIC` variable.
7847 8800
7848 VOLATILE_LOG_DIR 8801 VOLATILE_LOG_DIR
7849 Specifies the persistence of the target's ``/var/log`` directory, 8802 Specifies the persistence of the target's ``/var/log`` directory,
7850 which is used to house postinstall target log files. 8803 which is used to house postinstall target log files.
7851 8804
7852 By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the 8805 By default, ``VOLATILE_LOG_DIR`` is set to "yes", which means the
7853 file is not persistent. You can override this setting by setting the 8806 file is not persistent. You can override this setting by setting the
7854 variable to "no" to make the log directory persistent. 8807 variable to "no" to make the log directory persistent.
7855 8808
7856 WARN_QA 8809 WARN_QA
7857 Specifies the quality assurance checks whose failures are reported as 8810 Specifies the quality assurance checks whose failures are reported as
7858 warnings by the OpenEmbedded build system. You set this variable in 8811 warnings by the OpenEmbedded build system. You set this variable in
7859 your distribution configuration file. For a list of the checks you 8812 your distribution configuration file. For a list of the checks you
7860 can control with this variable, see the 8813 can control with this variable, see the
7861 ":ref:`insane.bbclass <ref-classes-insane>`" section. 8814 ":ref:`insane.bbclass <ref-classes-insane>`" section.
7862 8815
7863 WKS_FILE_DEPENDS 8816 WKS_FILE_DEPENDS
7864 When placed in the recipe that builds your image, this variable lists 8817 When placed in the recipe that builds your image, this variable lists
7865 build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only 8818 build-time dependencies. The ``WKS_FILE_DEPENDS`` variable is only
@@ -7867,39 +8820,46 @@ system and gives an overview of their function and contents.
7867 :term:`IMAGE_FSTYPES` contains entries related 8820 :term:`IMAGE_FSTYPES` contains entries related
7868 to Wic). If your recipe does not create Wic images, the variable has 8821 to Wic). If your recipe does not create Wic images, the variable has
7869 no effect. 8822 no effect.
7870 8823
7871 The ``WKS_FILE_DEPENDS`` variable is similar to the 8824 The ``WKS_FILE_DEPENDS`` variable is similar to the
7872 :term:`DEPENDS` variable. When you use the variable in 8825 :term:`DEPENDS` variable. When you use the variable in
7873 your recipe that builds the Wic image, dependencies you list in the 8826 your recipe that builds the Wic image, dependencies you list in the
7874 ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable. 8827 ``WIC_FILE_DEPENDS`` variable are added to the ``DEPENDS`` variable.
7875 8828
7876 With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to 8829 With the ``WKS_FILE_DEPENDS`` variable, you have the possibility to
7877 specify a list of additional dependencies (e.g. native tools, 8830 specify a list of additional dependencies (e.g. native tools,
7878 bootloaders, and so forth), that are required to build Wic images. 8831 bootloaders, and so forth), that are required to build Wic images.
7879 Following is an example: WKS_FILE_DEPENDS = "some-native-tool" In the 8832 Following is an example:
8833 ::
8834
8835 WKS_FILE_DEPENDS = "some-native-tool"
8836
8837 In the
7880 previous example, some-native-tool would be replaced with an actual 8838 previous example, some-native-tool would be replaced with an actual
7881 native tool on which the build would depend. 8839 native tool on which the build would depend.
7882 8840
7883 WKS_FILE 8841 WKS_FILE
7884 Specifies the location of the Wic kickstart file that is used by the 8842 Specifies the location of the Wic kickstart file that is used by the
7885 OpenEmbedded build system to create a partitioned image 8843 OpenEmbedded build system to create a partitioned image
7886 (image\ ``.wic``). For information on how to create a partitioned 8844 (image\ ``.wic``). For information on how to create a partitioned
7887 image, see the "`Creating Partitioned Images Using 8845 image, see the
7888 Wic <&YOCTO_DOCS_DEV_URL;#creating-partitioned-images-using-wic>`__" 8846 ":ref:`dev-manual/dev-manual-common-tasks:creating partitioned images using wic`"
7889 section in the Yocto Project Development Tasks Manual. For details on 8847 section in the Yocto Project Development Tasks Manual. For details on
7890 the kickstart file format, see the "`OpenEmbedded Kickstart 8848 the kickstart file format, see the ":doc:`../ref-manual/ref-kickstart`" Chapter.
7891 (``.wks``) Reference <#ref-kickstart>`__" Chapter. 8849
7892
7893 WORKDIR 8850 WORKDIR
7894 The pathname of the work directory in which the OpenEmbedded build 8851 The pathname of the work directory in which the OpenEmbedded build
7895 system builds a recipe. This directory is located within the 8852 system builds a recipe. This directory is located within the
7896 :term:`TMPDIR` directory structure and is specific to 8853 :term:`TMPDIR` directory structure and is specific to
7897 the recipe being built and the system for which it is being built. 8854 the recipe being built and the system for which it is being built.
7898 8855
7899 The ``WORKDIR`` directory is defined as follows: 8856 The ``WORKDIR`` directory is defined as follows:
7900 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR} 8857 ::
8858
8859 ${TMPDIR}/work/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}
8860
7901 The actual directory depends on several things: 8861 The actual directory depends on several things:
7902 8862
7903 - TMPDIR 8863 - TMPDIR
7904 : The top-level build output directory 8864 : The top-level build output directory
7905 - MULTIMACH_TARGET_SYS 8865 - MULTIMACH_TARGET_SYS
@@ -7916,21 +8876,24 @@ system and gives an overview of their function and contents.
7916 : The recipe version 8876 : The recipe version
7917 - PR 8877 - PR
7918 : The recipe revision 8878 : The recipe revision
7919 8879
7920 As an example, assume a Source Directory top-level folder name 8880 As an example, assume a Source Directory top-level folder name
7921 ``poky``, a default Build Directory at ``poky/build``, and a 8881 ``poky``, a default Build Directory at ``poky/build``, and a
7922 ``qemux86-poky-linux`` machine target system. Furthermore, suppose 8882 ``qemux86-poky-linux`` machine target system. Furthermore, suppose
7923 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work 8883 your recipe is named ``foo_1.3.0-r0.bb``. In this case, the work
7924 directory the build system uses to build the package would be as 8884 directory the build system uses to build the package would be as
7925 follows: poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0 8885 follows:
7926 8886 ::
8887
8888 poky/build/tmp/work/qemux86-poky-linux/foo/1.3.0-r0
8889
7927 XSERVER 8890 XSERVER
7928 Specifies the packages that should be installed to provide an X 8891 Specifies the packages that should be installed to provide an X
7929 server and drivers for the current machine, assuming your image 8892 server and drivers for the current machine, assuming your image
7930 directly includes ``packagegroup-core-x11-xserver`` or, perhaps 8893 directly includes ``packagegroup-core-x11-xserver`` or, perhaps
7931 indirectly, includes "x11-base" in 8894 indirectly, includes "x11-base" in
7932 :term:`IMAGE_FEATURES`. 8895 :term:`IMAGE_FEATURES`.
7933 8896
7934 The default value of ``XSERVER``, if not specified in the machine 8897 The default value of ``XSERVER``, if not specified in the machine
7935 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev". 8898 configuration, is "xserver-xorg xf86-video-fbdev xf86-input-evdev".
7936 8899
diff --git a/documentation/ref-manual/ref-varlocality.rst b/documentation/ref-manual/ref-varlocality.rst
index a130945718..a95504b571 100644
--- a/documentation/ref-manual/ref-varlocality.rst
+++ b/documentation/ref-manual/ref-varlocality.rst
@@ -25,23 +25,23 @@ Distribution (Distro)
25This section lists variables whose configuration context is the 25This section lists variables whose configuration context is the
26distribution, or distro. 26distribution, or distro.
27 27
28- ``DISTRO`` 28- :term:`DISTRO`
29 29
30- ``DISTRO_NAME`` 30- :term:`DISTRO_NAME`
31 31
32- ``DISTRO_VERSION`` 32- :term:`DISTRO_VERSION`
33 33
34- ``MAINTAINER`` 34- :term:`MAINTAINER`
35 35
36- ``PACKAGE_CLASSES`` 36- :term:`PACKAGE_CLASSES`
37 37
38- ``TARGET_OS`` 38- :term:`TARGET_OS`
39 39
40- ``TARGET_FPU`` 40- :term:`TARGET_FPU`
41 41
42- ``TCMODE`` 42- :term:`TCMODE`
43 43
44- ``TCLIBC`` 44- :term:`TCLIBC`
45 45
46.. _ref-varlocality-config-machine: 46.. _ref-varlocality-config-machine:
47 47
@@ -50,23 +50,23 @@ Machine
50 50
51This section lists variables whose configuration context is the machine. 51This section lists variables whose configuration context is the machine.
52 52
53- ``TARGET_ARCH`` 53- :term:`TARGET_ARCH`
54 54
55- ``SERIAL_CONSOLES`` 55- :term:`SERIAL_CONSOLES`
56 56
57- ``PACKAGE_EXTRA_ARCHS`` 57- :term:`PACKAGE_EXTRA_ARCHS`
58 58
59- ``IMAGE_FSTYPES`` 59- :term:`IMAGE_FSTYPES`
60 60
61- ``MACHINE_FEATURES`` 61- :term:`MACHINE_FEATURES`
62 62
63- ``MACHINE_EXTRA_RDEPENDS`` 63- :term:`MACHINE_EXTRA_RDEPENDS`
64 64
65- ``MACHINE_EXTRA_RRECOMMENDS`` 65- :term:`MACHINE_EXTRA_RRECOMMENDS`
66 66
67- ``MACHINE_ESSENTIAL_EXTRA_RDEPENDS`` 67- :term:`MACHINE_ESSENTIAL_EXTRA_RDEPENDS`
68 68
69- ``MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`` 69- :term:`MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS`
70 70
71.. _ref-varlocality-config-local: 71.. _ref-varlocality-config-local:
72 72
@@ -76,23 +76,23 @@ Local
76This section lists variables whose configuration context is the local 76This section lists variables whose configuration context is the local
77configuration through the ``local.conf`` file. 77configuration through the ``local.conf`` file.
78 78
79- ``DISTRO`` 79- :term:`DISTRO`
80 80
81- ``MACHINE`` 81- :term:`MACHINE`
82 82
83- ``DL_DIR`` 83- :term:`DL_DIR`
84 84
85- ``BBFILES`` 85- :term:`BBFILES`
86 86
87- ``EXTRA_IMAGE_FEATURES`` 87- :term:`EXTRA_IMAGE_FEATURES`
88 88
89- ``PACKAGE_CLASSES`` 89- :term:`PACKAGE_CLASSES`
90 90
91- ``BB_NUMBER_THREADS`` 91- :term:`BB_NUMBER_THREADS`
92 92
93- ``BBINCLUDELOGS`` 93- :term:`BBINCLUDELOGS`
94 94
95- ``ENABLE_BINARY_LOCALE_GENERATION`` 95- :term:`ENABLE_BINARY_LOCALE_GENERATION`
96 96
97.. _ref-varlocality-recipes: 97.. _ref-varlocality-recipes:
98 98
@@ -109,11 +109,11 @@ Required
109 109
110This section lists variables that are required for recipes. 110This section lists variables that are required for recipes.
111 111
112- ``LICENSE`` 112- :term:`LICENSE`
113 113
114- ``LIC_FILES_CHKSUM`` 114- :term:`LIC_FILES_CHKSUM`
115 115
116- ``SRC_URI`` - used in recipes that fetch local or remote files. 116- :term:`SRC_URI` - used in recipes that fetch local or remote files.
117 117
118.. _ref-varlocality-recipe-dependencies: 118.. _ref-varlocality-recipe-dependencies:
119 119
@@ -122,15 +122,15 @@ Dependencies
122 122
123This section lists variables that define recipe dependencies. 123This section lists variables that define recipe dependencies.
124 124
125- ``DEPENDS`` 125- :term:`DEPENDS`
126 126
127- ``RDEPENDS`` 127- :term:`RDEPENDS`
128 128
129- ``RRECOMMENDS`` 129- :term:`RRECOMMENDS`
130 130
131- ``RCONFLICTS`` 131- :term:`RCONFLICTS`
132 132
133- ``RREPLACES`` 133- :term:`RREPLACES`
134 134
135.. _ref-varlocality-recipe-paths: 135.. _ref-varlocality-recipe-paths:
136 136
@@ -139,11 +139,11 @@ Paths
139 139
140This section lists variables that define recipe paths. 140This section lists variables that define recipe paths.
141 141
142- ``WORKDIR`` 142- :term:`WORKDIR`
143 143
144- ``S`` 144- :term:`S`
145 145
146- ``FILES`` 146- :term:`FILES`
147 147
148.. _ref-varlocality-recipe-build: 148.. _ref-varlocality-recipe-build:
149 149
@@ -153,14 +153,14 @@ Extra Build Information
153This section lists variables that define extra build information for 153This section lists variables that define extra build information for
154recipes. 154recipes.
155 155
156- ``DEFAULT_PREFERENCE`` 156- :term:`DEFAULT_PREFERENCE`
157 157
158- ``EXTRA_OECMAKE`` 158- :term:`EXTRA_OECMAKE`
159 159
160- ``EXTRA_OECONF`` 160- :term:`EXTRA_OECONF`
161 161
162- ``EXTRA_OEMAKE`` 162- :term:`EXTRA_OEMAKE`
163 163
164- ``PACKAGECONFIG_CONFARGS`` 164- :term:`PACKAGECONFIG_CONFARGS`
165 165
166- ``PACKAGES`` 166- :term:`PACKAGES`
diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst
index c5ddcca97f..2b82b79102 100644
--- a/documentation/ref-manual/resources.rst
+++ b/documentation/ref-manual/resources.rst
@@ -23,8 +23,7 @@ The Yocto Project gladly accepts contributions. You can submit changes
23to the project either by creating and sending pull requests, or by 23to the project either by creating and sending pull requests, or by
24submitting patches through email. For information on how to do both as 24submitting patches through email. For information on how to do both as
25well as information on how to identify the maintainer for each area of 25well as information on how to identify the maintainer for each area of
26code, see the "`Submitting a Change to the Yocto 26code, see the ":ref:`how-to-submit-a-change`" section in the
27Project <&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change>`__" section in the
28Yocto Project Development Tasks Manual. 27Yocto Project Development Tasks Manual.
29 28
30.. _resources-bugtracker: 29.. _resources-bugtracker:
@@ -48,8 +47,7 @@ A general procedure and guidelines exist for when you use Bugzilla to
48submit a bug. For information on how to use Bugzilla to submit a bug 47submit a bug. For information on how to use Bugzilla to submit a bug
49against the Yocto Project, see the following: 48against the Yocto Project, see the following:
50 49
51- The "`Submitting a Defect Against the Yocto 50- The ":ref:`dev-manual/dev-manual-common-tasks:submitting a defect against the yocto project`"
52 Project <&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project>`__"
53 section in the Yocto Project Development Tasks Manual. 51 section in the Yocto Project Development Tasks Manual.
54 52
55- The Yocto Project :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>` 53- The Yocto Project :yocto_wiki:`Bugzilla wiki page </wiki/Bugzilla_Configuration_and_Bug_Tracking>`
@@ -67,22 +65,22 @@ and announcements. To subscribe to one of the following mailing lists,
67click on the appropriate URL in the following list and follow the 65click on the appropriate URL in the following list and follow the
68instructions: 66instructions:
69 67
70- ` <&YOCTO_LISTS_URL;/listinfo/yocto>`__ - General Yocto Project 68- https://lists.yoctoproject.org/g/yocto - General Yocto Project
71 discussion mailing list. 69 discussion mailing list.
72 70
73- ` <&OE_LISTS_URL;/listinfo/openembedded-core>`__ - Discussion mailing 71- https://lists.openembedded.org/g/openembedded-core - Discussion mailing
74 list about OpenEmbedded-Core (the core metadata). 72 list about OpenEmbedded-Core (the core metadata).
75 73
76- ` <&OE_LISTS_URL;/listinfo/openembedded-devel>`__ - Discussion 74- https://lists.openembedded.org/g/openembedded-devel - Discussion
77 mailing list about OpenEmbedded. 75 mailing list about OpenEmbedded.
78 76
79- ` <&OE_LISTS_URL;/listinfo/bitbake-devel>`__ - Discussion mailing 77- https://lists.openembedded.org/g/bitbake-devel - Discussion mailing
80 list about the :term:`BitBake` build tool. 78 list about the :term:`BitBake` build tool.
81 79
82- ` <&YOCTO_LISTS_URL;/listinfo/poky>`__ - Discussion mailing list 80- https://lists.yoctoproject.org/g/poky - Discussion mailing list
83 about `Poky <#poky>`__. 81 about `Poky <#poky>`__.
84 82
85- ` <&YOCTO_LISTS_URL;/listinfo/yocto-announce>`__ - Mailing list to 83- https://lists.yoctoproject.org/g/yocto-announce - Mailing list to
86 receive official Yocto Project release and milestone announcements. 84 receive official Yocto Project release and milestone announcements.
87 85
88For more Yocto Project-related mailing lists, see the 86For more Yocto Project-related mailing lists, see the
@@ -115,7 +113,7 @@ Here is a list of resources you might find helpful:
115 planning, release engineering, QA & automation, a reference site map, 113 planning, release engineering, QA & automation, a reference site map,
116 and other resources related to the Yocto Project. 114 and other resources related to the Yocto Project.
117 115
118- `OpenEmbedded <&OE_HOME_URL;>`__\ *:* The build system used by the 116- `OpenEmbedded <http://www.openembedded.org/>`__\ *:* The build system used by the
119 Yocto Project. This project is the upstream, generic, embedded 117 Yocto Project. This project is the upstream, generic, embedded
120 distribution from which the Yocto Project derives its build system 118 distribution from which the Yocto Project derives its build system
121 (Poky) and to which it contributes. 119 (Poky) and to which it contributes.
@@ -127,53 +125,47 @@ Here is a list of resources you might find helpful:
127 guide to the BitBake tool. If you want information on BitBake, see 125 guide to the BitBake tool. If you want information on BitBake, see
128 this manual. 126 this manual.
129 127
130- `Yocto Project Quick Build <&YOCTO_DOCS_BRIEF_URL;>`__\ *:* This 128- :doc:`../brief-yoctoprojectqs/brief-yoctoprojectqs` *:* This
131 short document lets you experience building an image using the Yocto 129 short document lets you experience building an image using the Yocto
132 Project without having to understand any concepts or details. 130 Project without having to understand any concepts or details.
133 131
134- `Yocto Project Overview and Concepts 132- :doc:`../overview-manual/overview-manual` *:* This manual provides overview
135 Manual <&YOCTO_DOCS_OM_URL;>`__\ *:* This manual provides overview
136 and conceptual information about the Yocto Project. 133 and conceptual information about the Yocto Project.
137 134
138- `Yocto Project Development Tasks 135- :doc:`../dev-manual/dev-manual` *:* This manual is a "how-to" guide
139 Manual <&YOCTO_DOCS_DEV_URL;>`__\ *:* This manual is a "how-to" guide
140 that presents procedures useful to both application and system 136 that presents procedures useful to both application and system
141 developers who use the Yocto Project. 137 developers who use the Yocto Project.
142 138
143- `Yocto Project Application Development and the Extensible Software 139- :doc:`../sdk-manual/sdk-manual` *manual :* This
144 Development Kit (eSDK) <&YOCTO_DOCS_SDK_URL;>`__\ *manual:* This
145 guide provides information that lets you get going with the standard 140 guide provides information that lets you get going with the standard
146 or extensible SDK. An SDK, with its cross-development toolchains, 141 or extensible SDK. An SDK, with its cross-development toolchains,
147 allows you to develop projects inside or outside of the Yocto Project 142 allows you to develop projects inside or outside of the Yocto Project
148 environment. 143 environment.
149 144
150- `Yocto Project Board Support Package (BSP) Developer's 145- :doc:`../bsp-guide/bsp` *:* This guide defines the structure
151 Guide <&YOCTO_DOCS_BSP_URL;>`__\ *:* This guide defines the structure
152 for BSP components. Having a commonly understood structure encourages 146 for BSP components. Having a commonly understood structure encourages
153 standardization. 147 standardization.
154 148
155- `Yocto Project Linux Kernel Development 149- :doc:`../kernel-dev/kernel-dev` *:* This manual describes
156 Manual <&YOCTO_DOCS_KERNEL_DEV_URL;>`__\ *:* This manual describes
157 how to work with Linux Yocto kernels as well as provides a bit of 150 how to work with Linux Yocto kernels as well as provides a bit of
158 conceptual information on the construction of the Yocto Linux kernel 151 conceptual information on the construction of the Yocto Linux kernel
159 tree. 152 tree.
160 153
161- `Yocto Project Reference Manual <&YOCTO_DOCS_REF_URL;>`__\ *:* This 154- :doc:`../ref-manual/ref-manual` *:* This
162 manual provides reference material such as variable, task, and class 155 manual provides reference material such as variable, task, and class
163 descriptions. 156 descriptions.
164 157
165- `Yocto Project Mega-Manual <&YOCTO_DOCS_MM_URL;>`__\ *:* This manual 158- `Yocto Project Mega-Manual <https://docs.yoctoproject.org/singleindex.html>`__\ *:* This manual
166 is simply a single HTML file comprised of the bulk of the Yocto 159 is simply a single HTML file comprised of the bulk of the Yocto
167 Project manuals. The Mega-Manual primarily exists as a vehicle by 160 Project manuals. The Mega-Manual primarily exists as a vehicle by
168 which you can easily search for phrases and terms used in the Yocto 161 which you can easily search for phrases and terms used in the Yocto
169 Project documentation set. 162 Project documentation set.
170 163
171- `Yocto Project Profiling and Tracing 164- :doc:`../profile-manual/profile-manual` *:* This manual presents a set of
172 Manual <&YOCTO_DOCS_PROF_URL;>`__\ *:* This manual presents a set of
173 common and generally useful tracing and profiling schemes along with 165 common and generally useful tracing and profiling schemes along with
174 their applications (as appropriate) to each tool. 166 their applications (as appropriate) to each tool.
175 167
176- `Toaster User Manual <&YOCTO_DOCS_TOAST_URL;>`__\ *:* This manual 168- :doc:`../toaster-manual/toaster-manual` *:* This manual
177 introduces and describes how to set up and use Toaster. Toaster is an 169 introduces and describes how to set up and use Toaster. Toaster is an
178 Application Programming Interface (API) and web-based interface to 170 Application Programming Interface (API) and web-based interface to
179 the :term:`OpenEmbedded Build System`, which uses 171 the :term:`OpenEmbedded Build System`, which uses
@@ -188,7 +180,7 @@ Here is a list of resources you might find helpful:
188 the Yocto Project website and click on the "RELEASE INFORMATION" link 180 the Yocto Project website and click on the "RELEASE INFORMATION" link
189 for the appropriate release. 181 for the appropriate release.
190 182
191- `Bugzilla <&YOCTO_BUGZILLA_URL;>`__\ *:* The bug tracking application 183- `Bugzilla <https://bugzilla.yoctoproject.org>`__\ *:* The bug tracking application
192 the Yocto Project uses. If you find problems with the Yocto Project, 184 the Yocto Project uses. If you find problems with the Yocto Project,
193 you should report them using this application. 185 you should report them using this application.
194 186